caudate-cli 0.1.0__py3-none-any.whl

core/paste.py

@@ -0,0 +1,81 @@
+"""Image / PDF paste detection.
+
+Most terminals don't paste binary content directly. What you actually
+get when dragging an image or a PDF into the prompt is the *path* to
+that file, often quoted (macOS Terminal, iTerm, Alacritty, kitty all
+behave this way). This module scans an input line for those bare paths,
+uploads anything that's an image or a PDF to the FileStore, and returns
+the cleaned text plus a list of attachment ids ready for `chat()`.
+
+Distinct from `core.file_refs.expand_with_attachments`:
+  - `file_refs` requires an explicit `@` prefix (intentional).
+  - `paste` is heuristic — it triggers on any quoted path or any token
+    that's an existing image/PDF file in cwd. Useful for drag-drop UX.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+# Image / PDF extensions we auto-attach.
+_PASTE_EXTS = {
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp",
+    ".pdf",
+}
+
+# Match either a quoted path ('...' or "...") or a bare unquoted token.
+_PATH_RE = re.compile(
+    r"""(?P<quoted>'[^']+'|"[^"]+")|(?P<bare>\S+)"""
+)
+
+
+def _looks_like_paste_path(token: str) -> Path | None:
+    """Return a resolved Path if the token points to an existing image/PDF."""
+    raw = token.strip().strip("'\"")
+    if not raw:
+        return None
+    p = Path(raw).expanduser()
+    if not p.is_absolute():
+        p = Path.cwd() / p
+    if not p.exists() or not p.is_file():
+        return None
+    if p.suffix.lower() not in _PASTE_EXTS:
+        return None
+    return p
+
+
+def detect_paste(text: str, file_store: Any) -> tuple[str, list[str]]:
+    """Strip image/PDF paths from `text` and upload them via `file_store`.
+
+    Returns (rewritten_text, [file_id, ...]). Order is preserved. Tokens
+    that don't resolve to an existing image/PDF are left untouched.
+    """
+    attachments: list[str] = []
+    parts: list[str] = []
+    last = 0
+
+    for match in _PATH_RE.finditer(text):
+        token = match.group(0)
+        path = _looks_like_paste_path(token)
+        if path is None:
+            continue
+        try:
+            record = file_store.upload(path, filename=path.name)
+        except Exception as e:
+            logger.debug(f"paste upload failed for {path}: {e}")
+            continue
+        attachments.append(record.id)
+        parts.append(text[last:match.start()])
+        parts.append(f"[attached: {path.name}]")
+        last = match.end()
+
+    if not attachments:
+        return text, []
+    parts.append(text[last:])
+    return "".join(parts), attachments

core/permissions.py

@@ -0,0 +1,210 @@
+"""Permission system — control tool execution with modes and rules.
+
+Modes:
+  - DEFAULT: prompt the user before executing destructive or sensitive tools
+  - PLAN: read-only — reject any tool that mutates state
+  - ACCEPT_EDITS: auto-approve file writes/edits but still prompt for Bash
+  - BYPASS: skip every check (dangerous; for trusted contexts)
+
+Rules:
+  - allow: tool+regex-on-args patterns that auto-approve
+  - deny: tool+regex-on-args patterns that auto-reject
+
+All decisions are written to an audit log (JSONL).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+class PermissionMode(str, Enum):
+    DEFAULT = "default"
+    PLAN = "plan"
+    ACCEPT_EDITS = "accept_edits"
+    BYPASS = "bypass"
+
+
+class PermissionDecision(str, Enum):
+    ALLOW = "allow"
+    DENY = "deny"
+    ASK = "ask"
+
+
+# Which tools are considered mutating / sensitive / safe.
+_SENSITIVE = {"Bash", "PythonExec"}
+_MUTATING = {"Write", "Edit"}
+_READONLY = {"Read", "Glob", "Grep", "WebSearch", "WebFetch", "Think", "Respond"}
+
+
+class PermissionRule:
+    """A single allow/deny rule. Matches a tool name + optional arg pattern."""
+
+    def __init__(self, tool: str, pattern: str | None = None):
+        self.tool = tool
+        self.pattern = re.compile(pattern) if pattern else None
+
+    def matches(self, tool: str, args: dict[str, Any]) -> bool:
+        if tool != self.tool and self.tool != "*":
+            return False
+        if self.pattern is None:
+            return True
+        return bool(self.pattern.search(json.dumps(args, ensure_ascii=False)))
+
+
+class PermissionManager:
+    """Evaluates tool calls against permission modes and rules, prompts when needed."""
+
+    def __init__(
+        self,
+        mode: PermissionMode = PermissionMode.DEFAULT,
+        allow: list[PermissionRule] | None = None,
+        deny: list[PermissionRule] | None = None,
+        audit_log: Path | None = None,
+        prompt: Callable[[str, dict[str, Any]], bool] | None = None,
+    ):
+        self.mode = mode
+        self.allow = allow or []
+        self.deny = deny or []
+        self.audit_log = audit_log
+        self._prompt_fn = prompt
+
+    # ------------------------------------------------------------------
+
+    def _classify(self, tool: str) -> str:
+        if tool in _MUTATING:
+            return "mutating"
+        if tool in _SENSITIVE:
+            return "sensitive"
+        if tool in _READONLY:
+            return "readonly"
+        return "unknown"
+
+    def _decide(self, tool: str, args: dict[str, Any]) -> PermissionDecision:
+        # Explicit deny rules win
+        if any(r.matches(tool, args) for r in self.deny):
+            return PermissionDecision.DENY
+
+        # Mode-level overrides
+        if self.mode == PermissionMode.BYPASS:
+            return PermissionDecision.ALLOW
+
+        # Explicit allow rules
+        if any(r.matches(tool, args) for r in self.allow):
+            return PermissionDecision.ALLOW
+
+        kind = self._classify(tool)
+
+        if self.mode == PermissionMode.PLAN:
+            # Plan mode: only readonly tools allowed
+            return PermissionDecision.ALLOW if kind == "readonly" else PermissionDecision.DENY
+
+        if self.mode == PermissionMode.ACCEPT_EDITS:
+            if kind in ("readonly", "mutating"):
+                return PermissionDecision.ALLOW
+            return PermissionDecision.ASK  # sensitive/unknown still prompts
+
+        # DEFAULT mode
+        if kind == "readonly":
+            return PermissionDecision.ALLOW
+        return PermissionDecision.ASK  # mutating / sensitive / unknown
+
+    async def check(self, tool: str, args: dict[str, Any]) -> tuple[bool, str]:
+        """Check whether a tool call is permitted.
+
+        Returns (allowed, reason).
+        """
+        decision = self._decide(tool, args)
+
+        if decision == PermissionDecision.ASK:
+            approved = await self._ask_user(tool, args)
+            final = "allow (user)" if approved else "deny (user)"
+            self._audit(tool, args, final)
+            return approved, final
+
+        final = decision.value
+        self._audit(tool, args, final)
+        return decision == PermissionDecision.ALLOW, final
+
+    # ------------------------------------------------------------------
+
+    async def _ask_user(self, tool: str, args: dict[str, Any]) -> bool:
+        if self._prompt_fn is None:
+            # No prompt wired: conservative default is deny
+            logger.warning(
+                f"Permission ASK for {tool} but no prompt configured; denying"
+            )
+            return False
+        result = self._prompt_fn(tool, args)
+        if asyncio.iscoroutine(result):
+            result = await result
+        return bool(result)
+
+    def _audit(self, tool: str, args: dict[str, Any], decision: str) -> None:
+        if self.audit_log is None:
+            return
+        try:
+            self.audit_log.parent.mkdir(parents=True, exist_ok=True)
+            entry = {
+                "ts": datetime.utcnow().isoformat(),
+                "tool": tool,
+                "args": args,
+                "decision": decision,
+                "mode": self.mode.value,
+            }
+            with self.audit_log.open("a") as f:
+                f.write(json.dumps(entry) + "\n")
+        except Exception as e:
+            logger.debug(f"Audit log write failed: {e}")
+
+
+def rules_from_settings(entries: list[dict[str, Any]] | None) -> list[PermissionRule]:
+    """Build PermissionRule objects from a settings list.
+
+    Each entry: {"tool": "<name or '*'>", "pattern": "<regex|None>"}.
+    Bad entries are dropped with a warning, not raised — settings are
+    user-editable and a typo shouldn't crash the agent.
+    """
+    out: list[PermissionRule] = []
+    for entry in entries or []:
+        try:
+            tool = entry["tool"] if "tool" in entry else "*"
+            pattern = entry.get("pattern")
+            out.append(PermissionRule(tool=tool, pattern=pattern))
+        except Exception as e:
+            logger.warning(f"Skipping invalid permission rule {entry!r}: {e}")
+    return out
+
+
+def default_cli_prompt(tool: str, args: dict[str, Any]) -> bool:
+    """Interactive terminal prompt used in CLI mode."""
+    from rich.console import Console
+    console = Console()
+
+    # Show a unified diff for proposed file changes — Claude Code parity.
+    if tool in ("Edit", "Write"):
+        try:
+            from core.diff_viewer import render_proposed_change
+            render_proposed_change(tool, args, console=console)
+        except Exception as e:
+            logger.debug(f"diff preview failed: {e}")
+    else:
+        preview = json.dumps(args, ensure_ascii=False)
+        if len(preview) > 400:
+            preview = preview[:397] + "…"
+        console.print(f"[yellow]Permission needed:[/yellow] {tool}({preview})")
+
+    try:
+        answer = console.input("[bold]Allow? [y/N]:[/bold] ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        return False
+    return answer in ("y", "yes")

core/plan_mode.py

@@ -0,0 +1,215 @@
+"""Plan Mode + system FSM — read-only flag and explicit phase tracking.
+
+Two layers sharing one module-level state:
+
+1. **Bool API** (`is_active`, `enter`, `exit_mode`) — the historical
+   plan-mode toggle. When ON, the executor refuses any tool whose
+   `mutates = True` (Bash, Write, Edit, PythonExec, HttpRequest, …).
+   Read-only tools (Read, Grep, Glob, SystemInfo, …) still work.
+
+2. **Phase FSM** (`SystemState`, `current_state`, `transition_to`,
+   `can_write`, `handle_validation_failure`) — formal 5-state machine
+   mirroring /home/raveuk/src/orchestrator/state_machine.py. Adds
+   explicit PLAN / EXEC / VALIDATION / RECOVERY / TERMINATED phases
+   with allowed-transition guards, a per-state write-lock matrix, and
+   a failure counter that auto-escalates to RECOVERY after
+   `MAX_TASK_FAILURES` strikes.
+
+The two layers are coupled: `is_active()` returns True iff the
+current state does **not** allow writes. So `enter()` puts us in
+PLAN_MODE, `exit_mode()` returns us to EXEC_MODE, and the FSM can
+also flip the bool implicitly by transitioning to VALIDATION_MODE
+or RECOVERY_MODE.
+
+Use case for the bool API: the user asks for a complex change, the
+agent plans the edits, the user reviews, then exits plan mode to
+actually make the changes. Mirrors Claude Code's Plan Mode UX.
+
+Use case for the FSM: the cognitive loop drives explicit phase
+transitions so write-blocking has rigor (only EXEC writes) and
+repeated validation failures route to a recovery handler.
+
+Process-global state — Cognos is single-user, simple is better than
+per-session here.
+"""
+
+from __future__ import annotations
+
+import enum
+import logging
+import threading
+
+try:
+    from config import MAX_TASK_FAILURES as _DEFAULT_MAX_FAILURES
+except Exception:  # config import failure shouldn't crash plan_mode
+    _DEFAULT_MAX_FAILURES = 2
+
+logger = logging.getLogger(__name__)
+
+
+class SystemState(str, enum.Enum):
+    """Phase of the cognitive loop. Mirrors src/orchestrator FSM."""
+    PLAN_MODE = "PLAN_MODE"
+    EXEC_MODE = "EXEC_MODE"
+    VALIDATION_MODE = "VALIDATION_MODE"
+    RECOVERY_MODE = "RECOVERY_MODE"
+    TERMINATED = "TERMINATED"
+
+
+class StateMachineError(Exception):
+    """Raised on illegal state transitions."""
+
+
+# Only EXEC_MODE may write. Everything else is read-only — this is the
+# write-lock matrix from the dual-brain spec.
+_WRITES_ALLOWED: dict[SystemState, bool] = {
+    SystemState.PLAN_MODE: False,
+    SystemState.EXEC_MODE: True,
+    SystemState.VALIDATION_MODE: False,
+    SystemState.RECOVERY_MODE: False,
+    SystemState.TERMINATED: False,
+}
+
+_ALLOWED_TRANSITIONS: dict[SystemState, list[SystemState]] = {
+    SystemState.PLAN_MODE: [SystemState.EXEC_MODE, SystemState.TERMINATED],
+    SystemState.EXEC_MODE: [SystemState.VALIDATION_MODE, SystemState.PLAN_MODE,
+                            SystemState.TERMINATED],
+    SystemState.VALIDATION_MODE: [SystemState.PLAN_MODE, SystemState.EXEC_MODE,
+                                  SystemState.RECOVERY_MODE, SystemState.TERMINATED],
+    SystemState.RECOVERY_MODE: [SystemState.PLAN_MODE, SystemState.TERMINATED],
+    SystemState.TERMINATED: [],
+}
+
+
+class _PlanState:
+    """Wraps the FSM in a class so swaps are atomic and observable."""
+
+    def __init__(self) -> None:
+        # Default phase is EXEC_MODE — writes allowed, plan-mode bool OFF.
+        self._state: SystemState = SystemState.EXEC_MODE
+        self._failure_counter: int = 0
+        self._max_failures: int = int(_DEFAULT_MAX_FAILURES)
+        self._lock = threading.Lock()
+
+    # ---- bool API ----
+    def is_active(self) -> bool:
+        """True iff writes are currently blocked (any non-EXEC state)."""
+        return not _WRITES_ALLOWED[self._state]
+
+    def enter(self) -> bool:
+        """Force PLAN_MODE. Returns True if state changed."""
+        with self._lock:
+            if self._state == SystemState.PLAN_MODE:
+                return False
+            self._state = SystemState.PLAN_MODE
+            logger.info("Plan mode: ON (state=PLAN_MODE, writes blocked)")
+            return True
+
+    def exit(self) -> bool:
+        """Force EXEC_MODE. Returns True if state changed."""
+        with self._lock:
+            if self._state == SystemState.EXEC_MODE:
+                return False
+            self._state = SystemState.EXEC_MODE
+            self._failure_counter = 0  # fresh exec scope
+            logger.info("Plan mode: OFF (state=EXEC_MODE, writes allowed)")
+            return True
+
+    # ---- FSM API ----
+    def current_state(self) -> SystemState:
+        return self._state
+
+    def can_write(self) -> bool:
+        return _WRITES_ALLOWED[self._state]
+
+    def transition_to(self, target: SystemState, reason: str = "") -> None:
+        with self._lock:
+            allowed = _ALLOWED_TRANSITIONS[self._state]
+            if target not in allowed:
+                raise StateMachineError(
+                    f"Illegal transition {self._state.value} -> {target.value}"
+                    + (f" (reason: {reason})" if reason else "")
+                )
+            logger.info(
+                f"FSM: {self._state.value} -> {target.value}"
+                + (f" ({reason})" if reason else "")
+            )
+            self._state = target
+            if target == SystemState.EXEC_MODE:
+                self._failure_counter = 0  # exec scope resets counter
+
+    def handle_validation_failure(self, error_trace: str = "") -> SystemState:
+        """Increment failure counter; escalate to RECOVERY past threshold.
+
+        Returns the new state. Counter resets when EXEC_MODE is next
+        entered (either via `exit()` or `transition_to(EXEC_MODE, ...)`).
+        """
+        with self._lock:
+            self._failure_counter += 1
+            if self._failure_counter >= self._max_failures:
+                if SystemState.RECOVERY_MODE in _ALLOWED_TRANSITIONS[self._state]:
+                    self._state = SystemState.RECOVERY_MODE
+                    logger.warning(
+                        f"FSM: validation failure threshold "
+                        f"({self._failure_counter}/{self._max_failures}) "
+                        f"-> RECOVERY_MODE. trace={error_trace[:200]}"
+                    )
+                else:
+                    logger.warning(
+                        f"FSM: failure threshold met but RECOVERY not "
+                        f"reachable from {self._state.value}; staying put"
+                    )
+            else:
+                logger.info(
+                    f"FSM: validation failure "
+                    f"{self._failure_counter}/{self._max_failures}"
+                )
+            return self._state
+
+    def failure_count(self) -> int:
+        return self._failure_counter
+
+    def set_max_failures(self, n: int) -> None:
+        with self._lock:
+            self._max_failures = max(1, int(n))
+
+
+_STATE = _PlanState()
+
+
+# ---- bool API (back-compat) ----
+def is_active() -> bool:
+    return _STATE.is_active()
+
+
+def enter() -> bool:
+    return _STATE.enter()
+
+
+def exit_mode() -> bool:
+    return _STATE.exit()
+
+
+# ---- FSM API ----
+def current_state() -> SystemState:
+    return _STATE.current_state()
+
+
+def can_write() -> bool:
+    return _STATE.can_write()
+
+
+def transition_to(target: SystemState, reason: str = "") -> None:
+    _STATE.transition_to(target, reason)
+
+
+def handle_validation_failure(error_trace: str = "") -> SystemState:
+    return _STATE.handle_validation_failure(error_trace)
+
+
+def failure_count() -> int:
+    return _STATE.failure_count()
+
+
+def set_max_failures(n: int) -> None:
+    _STATE.set_max_failures(n)

core/sandbox_prompt.py

@@ -0,0 +1,185 @@
+"""Sandbox-awareness system prompt injection.
+
+Both API endpoints (`/v1/chat/completions` for Open WebUI and
+`/v1/messages` for Claude Code CLI) call `inject_sandbox_hint` on
+their internal-shape message list. The helper appends a short hint
+to an existing system message, or prepends a new system message if
+none exists, telling the LLM to scaffold new files into
+`/home/raveuk/cognos/sandbox/` by default.
+
+Single source of truth so the chat and CLI paths stay consistent.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+# Resolve once at import — repository-relative so it follows the user's
+# checkout. Could also be made configurable via env var if needed.
+SANDBOX_DIR = (Path(__file__).resolve().parent.parent / "sandbox").resolve()
+
+SANDBOX_HINT = f"""## System access and workspace conventions
+
+You are running on the user's own machine and have full inspection
+access to it. Use the tools you have:
+
+### Questions about your own internals
+
+When the user asks where your system prompt lives, what your
+configuration is, "which file is it", "what's in your prompt", or
+anything about your own runtime composition — **call `CognosCard`
+first** (try `CognosCard(section="architecture")` for the file list).
+**Do NOT** run `find` / `grep` / `Bash` to hunt for "the system prompt
+file" — there isn't one single file. The system prompt is composed
+at runtime from several sources, all listed in the Cognos card. If
+`CognosCard` doesn't have what you need, read `data/COGNOS_CARD.md`
+directly with `Read`. After two attempts, if you still don't have an
+answer, surface the question to the user — don't keep searching.
+
+
+
+- **Read access is unrestricted.** Use `Read`, `Grep`, `Glob`,
+  `FindAnywhere`, and read-only `Bash` (`ls`, `cat`, `df`, `nvidia-smi`,
+  `free`, `uname`, `ps`, `git status`, etc.) anywhere on the system
+  the user has access to. If they ask "what GPU do you have?" or
+  "what's in /etc/hosts?" — just look. The `SystemInfo` tool gives
+  you a one-call summary (CPU/RAM/GPU/disk/Python/CUDA).
+- **Writes default to the sandbox.** When the user asks you to
+  *create*, *build*, *make*, *write*, or *scaffold* something new
+  and doesn't specify a path, write into:
+    - `{SANDBOX_DIR}/projects/<name>/`  for multi-file apps
+    - `{SANDBOX_DIR}/scripts/`           for one-off scripts/helpers
+    - `{SANDBOX_DIR}/notes/`             for plain-text notes
+  The sandbox is its own 50GB filesystem (loopback ext4) — fill it
+  freely. Treat it as scratch space.
+- **Writes outside the sandbox** are allowed when the user explicitly
+  references those files (e.g. "edit my .bashrc", "fix this bug in
+  /home/raveuk/cognos/api/openai_compat.py"). Don't write outside
+  the sandbox just because it would be tidier; only when asked.
+
+### Uploaded images / files — **READ THIS, IT IS NOT A SUGGESTION**
+
+When the user attaches an image (or any file) in the chat, the API
+auto-saves it to the FileStore (`/home/raveuk/cognos/data/files/`)
+and injects a marker into the user message:
+
+    [uploaded image: files/<id>]
+
+**`files/<id>` is a fully accessible local-filesystem reference.**
+It is NOT cloud storage, NOT chat-only, NOT a placeholder. Every
+local Cognos tool can read it. The image already exists on disk at
+`/home/raveuk/cognos/data/files/<id>.<ext>` — it was saved before
+you saw the message.
+
+**ABSOLUTE RULES — no exceptions, no "but maybe":**
+
+1. If you see `[uploaded image: files/<id>]` in the user's message,
+   **ALWAYS pass that string directly to EditImage / DescribeImage**.
+   No path conversion, no path lookup, no "save it first" — just use
+   the handle as-is.
+2. **NEVER tell the user "save it to a local path"** or "the upload
+   isn't reaching my tool" or "it's in chat cloud storage". These
+   statements are false. The file IS local. Saying any of them is a
+   bug — if you find yourself about to type one, STOP and call the
+   tool with the file handle instead.
+3. **NEVER preface or follow a successful tool result with disclaimers
+   like "if this isn't your photo…"**. If EditImage returned a
+   markdown image link, the edit happened. Trust the tool. Show the
+   result without second-guessing.
+4. If the tool returns an actual error (status=error), surface that
+   exact error to the user. Do NOT substitute it with a fabricated
+   "save to a path" explanation.
+"""
+
+
+def inject_sandbox_hint(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Return a new messages list with the sandbox hint applied.
+
+    Also folds in the durable memory.md contents so the LLM has access
+    to cross-session context every turn.
+
+    - Appends to an existing leading system message
+    - Otherwise prepends a fresh system message
+    - Idempotent: if the hint marker is already present, returns input
+      unchanged so multi-turn calls don't accumulate copies.
+    """
+    marker = "## Workspace conventions"
+
+    # Pull the durable memory file (empty string if no entries yet)
+    memory_block = ""
+    try:
+        from core.memory_md import get_memory
+        memory_block = get_memory().render_for_system_prompt()
+    except Exception:
+        pass
+
+    # Pull installed-skills TOC + auto-activate any skills whose
+    # name/description overlaps the user's prompt. The TOC keeps the
+    # LLM aware of all installed skills; the auto-activated FULL bodies
+    # live below so the LLM doesn't have to round-trip via LoadSkill
+    # when a skill is obviously relevant.
+    skills_toc = ""
+    skills_active = ""
+    try:
+        from core.skills import get_skills
+        registry = get_skills()
+        skills_toc = registry.render_toc()
+        # Find the most-recent user message to score skills against
+        latest_user = ""
+        for m in reversed(messages or []):
+            if m.get("role") == "user":
+                c = m.get("content", "")
+                if isinstance(c, list):
+                    c = " ".join(b.get("text", "") for b in c
+                                 if isinstance(b, dict))
+                latest_user = c or ""
+                break
+        if latest_user:
+            skills_active = registry.render_active_skills(latest_user, top_k=2)
+    except Exception:
+        pass
+
+    # Cognos self-spec card reference — short pointer + reminder that
+    # the LLM should call `CognosCard` when it's unsure about Cognos's
+    # capabilities or boundaries.
+    cognos_card_block = ""
+    try:
+        from execution.tools.cognos_card_tool import render_cognos_card_short
+        cognos_card_block = render_cognos_card_short()
+    except Exception:
+        pass
+
+    full_hint = SANDBOX_HINT
+    if cognos_card_block:
+        full_hint = f"{full_hint}\n\n{cognos_card_block}"
+    if skills_toc:
+        full_hint = f"{full_hint}\n\n{skills_toc}"
+    if skills_active:
+        full_hint = f"{full_hint}\n\n{skills_active}"
+    if memory_block:
+        full_hint = f"{full_hint}\n\n{memory_block}"
+
+    if not messages:
+        return [{"role": "system", "content": full_hint}]
+
+    # Already applied? leave alone (chat clients replay the system msg
+    # on every turn; we don't want N copies after N turns). The memory
+    # block lives next to the marker so re-injecting it is also gated
+    # by the same idempotency check.
+    if messages and messages[0].get("role") == "system":
+        head = messages[0].get("content", "")
+        if isinstance(head, list):
+            head_text = " ".join(
+                b.get("text", "") for b in head if isinstance(b, dict)
+            )
+        else:
+            head_text = head or ""
+        if marker in head_text:
+            return messages
+        out = list(messages)
+        out[0] = {"role": "system", "content": f"{head_text}\n\n{full_hint}"}
+        return out
+
+    # No system message — prepend one
+    return [{"role": "system", "content": full_hint}, *messages]