symphony-code 0.0.1__py3-none-any.whl

coding_agent/addons/learning/store.py

@@ -0,0 +1,522 @@
+"""Durable topical memory. Topics are authoritative; SQLite is a rebuildable index.
+
+Candidate observations and capture jobs survive restarts. No legacy memory or
+lesson files are read or migrated. Session Markdown is presentation only.
+"""
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import logging
+import os
+import re
+import sqlite3
+import threading
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field, is_dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Final
+
+from coding_agent.config import LearningConfig
+from coding_agent.addons.persistence.artifacts import append_bytes, fsync_dir, publish, safe_path
+from coding_agent.addons.learning.sanitize import sanitize_memory, sanitize_task, sanitize_text
+
+logger = logging.getLogger(__name__)
+MEMORY_CONTEXT_PREFIX = "Relevant durable memory (untrusted reference data; verify before use):"
+# Bad extraction output (empty, unparseable, invalid) is retried at most this
+# many times; then the job is marked failed and no longer resumed.
+MAX_CAPTURE_ATTEMPTS: Final[int] = 3
+_STOP_WORDS = {"this", "that", "with", "from", "into", "what", "when", "where", "which", "does", "need", "make", "only", "have", "will", "your", "the", "and", "for"}
+
+
+def _now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _hash(value):
+    return hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+
+
+def _id(value):
+    if not isinstance(value, str) or not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}", value):
+        raise ValueError("unsafe memory identifier")
+    return value
+
+
+@dataclass(frozen=True)
+class MemoryEntry:
+    target: str
+    text: str
+    position: int
+
+
+@dataclass
+class Lesson:
+    summary: str
+    worked: list[str] = field(default_factory=list)
+    failed: list[str] = field(default_factory=list)
+    applicable_when: list[str] = field(default_factory=list)
+    confidence: float = 0.5
+    source_task: str = ""
+    created_at: str = field(default_factory=_now)
+
+    def to_json(self):
+        return json.dumps(asdict(self), ensure_ascii=False)
+
+
+class LearningStore:
+    def __init__(self, workspace: str | Path, *, session_id: str | None = None,
+                 max_lessons: int = LearningConfig().max_lessons,
+                 session_dir: str | Path | None = None,
+                 global_root: str | Path | None = None):
+        self.workspace = Path(workspace).resolve()
+        self.session_id = session_id
+        self.session_dir = Path(session_dir).resolve() if session_dir is not None else None
+        # Session facts are markdown under the session bundle, never the project.
+        # With no session yet, keep the same machinery in a workspace-local dir
+        # so tools and tests can still record before a session id exists.
+        if self.session_dir is not None:
+            self.memory_dir = safe_path(self.session_dir, "memories")
+        else:
+            self.memory_dir = safe_path(self.workspace, ".symphony/memories")
+        # Do not resolve away symlinks before validating paths.
+        self.global_root = Path(global_root).absolute() if global_root is not None else safe_path(Path.home(), ".symphony/memories/global")
+        self.roots = {"workspace": self.memory_dir, "global": self.global_root}
+        self.path = safe_path(self.memory_dir, "lessons.jsonl")
+        # Markdown fact files. These are the session (and global) record.
+        self.memory_path = safe_path(self.memory_dir, "MEMORY.md")
+        self.user_path = safe_path(self.global_root, "USER.md")
+        self.max_lessons = max_lessons
+        self._lock = threading.RLock()
+        self._lock_depth = 0
+        for root in self.roots.values():
+            # Validate every ancestor, including a supplied global root.
+            for parent in (root, *root.parents):
+                if parent.is_symlink():
+                    raise ValueError("unsafe memory root")
+            for relative in ("topics", "observations/_inbox", "observations/archive", "jobs"):
+                safe_path(root, relative).mkdir(parents=True, exist_ok=True)
+        self.archive_memory_snapshot()
+
+    def _root(self, scope):
+        if scope not in self.roots:
+            raise ValueError("scope must be workspace or global")
+        return self.roots[scope]
+
+    @contextmanager
+    def _locked(self):
+        with self._lock:
+            if self._lock_depth:
+                yield
+                return
+            handles = []
+            try:
+                for root in sorted(set(self.roots.values()), key=str):
+                    path = safe_path(root, ".lock")
+                    fd = os.open(path, os.O_CREAT | os.O_RDWR | getattr(os, "O_NOFOLLOW", 0), 0o600)
+                    handles.append(fd)
+                    fcntl.flock(fd, fcntl.LOCK_EX)
+                self._lock_depth = 1
+                yield
+            finally:
+                self._lock_depth = 0
+                for fd in reversed(handles):
+                    fcntl.flock(fd, fcntl.LOCK_UN)
+                    os.close(fd)
+
+    @staticmethod
+    def _read(path):
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    @staticmethod
+    def _write(path, value):
+        publish(path, (json.dumps(value, ensure_ascii=False, sort_keys=True) + "\n").encode())
+
+    def _topic_records(self, scope):
+        root = self._root(scope)
+        for path in sorted(safe_path(root, "topics").glob("*.json")):
+            yield self._read(safe_path(root, "topics", _id(path.stem) + ".json"))
+
+    def _facts(self):
+        for scope in self.roots:
+            for topic in self._topic_records(scope):
+                for fact in topic.get("facts", []):
+                    yield {"id": topic["id"], "title": topic.get("title", topic["id"]),
+                           "text": sanitize_text(fact["text"], max_chars=2000),
+                           "scope": scope, "fact_id": fact["id"]}
+
+    def _candidate(self, text, topic="general", scope="workspace", sources=None):
+        _id(topic)
+        self._root(scope)
+        text = sanitize_text(str(text), max_chars=2000)
+        if not text:
+            raise ValueError("observation requires non-empty text")
+        sources = [sanitize_text(str(s), max_chars=500) for s in (sources or [])[:20]]
+        key = _hash([scope, topic, text.casefold(), sources])
+        return {"id": key, "text": text, "topic": topic, "scope": scope,
+                "sources": sources, "created_at": _now()}
+
+    def _record(self, candidate):
+        root = self._root(candidate["scope"])
+        name = candidate["id"] + ".json"
+        path = safe_path(root, "observations/_inbox", name)
+        if not path.exists() and not safe_path(root, "observations/archive", name).exists():
+            self._write(path, candidate)
+        return candidate["id"]
+
+    def record_observation(self, text, topic="general", scope="workspace", sources=None):
+        candidate = self._candidate(text, topic, scope, sources)
+        with self._locked():
+            return self._record(candidate)
+
+    def enqueue_capture(self, task, messages, session_id):
+        def clean(value):
+            if is_dataclass(value):
+                value = asdict(value)
+            elif hasattr(value, "model_dump"):
+                value = value.model_dump(mode="json")
+            if isinstance(value, dict):
+                return {str(k): clean(v) for k, v in value.items()}
+            if isinstance(value, (list, tuple)):
+                return [clean(v) for v in value]
+            if isinstance(value, str):
+                return sanitize_memory(value, max_chars=16000)
+            if value is None or isinstance(value, (int, float, bool)):
+                return value
+            return sanitize_text(str(value), max_chars=16000)
+        payload = {"task": sanitize_task(task), "messages": clean(messages),
+                   "session_id": sanitize_text(str(session_id or ""), max_chars=128)}
+        job_id = _hash(payload)
+        with self._locked():
+            path = safe_path(self.memory_dir, "jobs", job_id + ".json")
+            if not path.exists():
+                self._write(path, {"id": job_id, **payload, "status": "pending", "created_at": _now()})
+        self._archive_record("learning/captures.jsonl", {"job_id": job_id, "status": "queued"})
+        return job_id
+
+    def pending_jobs(self):
+        with self._locked():
+            jobs = [self._read(safe_path(self.memory_dir, "jobs", _id(p.stem) + ".json"))
+                    for p in sorted(safe_path(self.memory_dir, "jobs").glob("*.json"))]
+            return [job for job in jobs if job.get("status") not in {"complete", "failed"}]
+
+    def record_capture_failure(self, id, error):
+        """Count one bad extraction; return True once the job is marked failed."""
+        path = safe_path(self.memory_dir, "jobs", _id(id) + ".json")
+        with self._locked():
+            job = self._read(path)
+            attempts = int(job.get("attempts", 0)) + 1
+            status = "failed" if attempts >= MAX_CAPTURE_ATTEMPTS else job.get("status", "pending")
+            error = sanitize_text(str(error), max_chars=400)
+            self._write(path, {**job, "attempts": attempts, "status": status, "last_error": error})
+        self._archive_record("learning/captures.jsonl", {"job_id": id, "status": status,
+                                                          "attempts": attempts, "error": error})
+        return status == "failed"
+
+    def complete_job(self, id, observations):
+        path = safe_path(self.memory_dir, "jobs", _id(id) + ".json")
+        with self._locked():
+            job = self._read(path)
+            if job.get("status") == "complete":
+                return
+            # Validate the entire batch before publishing any candidate.
+            candidates = [self._candidate(o["text"], o.get("topic", "general"),
+                                          o.get("scope", "workspace"), o.get("sources", [id]))
+                          for o in observations]
+            ids = [self._record(c) for c in candidates]
+            self._write(path, {**job, "status": "complete", "observation_ids": ids, "completed_at": _now()})
+        self._archive_record("learning/captures.jsonl", {"job_id": id, "status": "complete", "observation_ids": ids})
+
+    def _consolidate(self):
+        stats = {"processed": 0, "added": 0, "duplicates": 0, "archived": 0}
+        for scope, root in self.roots.items():
+            known = {f["text"].casefold() for t in self._topic_records(scope) for f in t.get("facts", [])}
+            for file in sorted(safe_path(root, "observations/_inbox").glob("*.json")):
+                inbox = safe_path(root, "observations/_inbox", _id(file.stem) + ".json")
+                record = self._read(inbox)
+                topic_id = _id(record["topic"])
+                path = safe_path(root, "topics", topic_id + ".json")
+                topic = self._read(path) if path.exists() else {"id": topic_id, "title": topic_id.replace("-", " "), "scope": scope, "facts": []}
+                text = sanitize_text(record["text"], max_chars=2000)
+                stats["processed"] += 1
+                if text.casefold() not in known:
+                    topic["facts"].append({"id": _hash([scope, text.casefold()]), "text": text,
+                                           "sources": record.get("sources", []), "created_at": record["created_at"]})
+                    topic["updated_at"] = _now()
+                    self._write(path, topic)  # Commit precedes inbox archival, always.
+                    known.add(text.casefold())
+                    stats["added"] += 1
+                else:
+                    # Repeated knowledge still belongs to every session that
+                    # supplied it; merge evidence links without duplicating text.
+                    for existing in self._topic_records(scope):
+                        for fact in existing.get("facts", []):
+                            if fact["text"].casefold() == text.casefold():
+                                sources = sorted(set(fact.get("sources", [])) | set(record.get("sources", [])))
+                                if sources != fact.get("sources", []):
+                                    fact["sources"] = sources
+                                    self._write(safe_path(root, "topics", existing["id"] + ".json"), existing)
+                    stats["duplicates"] += 1
+                archive = safe_path(root, "observations/archive", file.name)
+                os.replace(inbox, archive)
+                fsync_dir(archive.parent)
+                fsync_dir(inbox.parent)
+                stats["archived"] += 1
+        return stats
+
+    def consolidate(self):
+        with self._locked():
+            return self._consolidate()
+
+    @staticmethod
+    def _query_words(text):
+        return {w for w in re.findall(r"[a-z0-9][a-z0-9_-]{2,}", sanitize_memory(text, max_chars=1200).casefold()) if w not in _STOP_WORDS}
+
+    def search(self, query, limit=6):
+        if limit <= 0:
+            return []
+        words = sorted(self._query_words(query))
+        if not words:
+            return []
+        with self._locked():
+            facts = list(self._facts())
+            # Rebuild on every read: durable topics, including other processes'
+            # writes, are always authoritative. No embeddings or model calls.
+            index = safe_path(self.memory_dir, "index.sqlite3")
+            with sqlite3.connect(index) as db:
+                try:
+                    db.execute("CREATE VIRTUAL TABLE IF NOT EXISTS facts USING fts5(id UNINDEXED, title, text, scope UNINDEXED)")
+                    db.execute("DELETE FROM facts")
+                    db.executemany("INSERT INTO facts VALUES (?,?,?,?)", [(f["id"], f["title"], f["text"], f["scope"]) for f in facts])
+                    rows = db.execute("SELECT id,title,text,scope,bm25(facts) FROM facts WHERE facts MATCH ? ORDER BY bm25(facts),rowid LIMIT ?", (' OR '.join('"' + w + '"' for w in words), limit)).fetchall()
+                    return [dict(id=r[0], title=r[1], text=r[2], scope=r[3], score=-r[4]) for r in rows]
+                except sqlite3.OperationalError as exc:
+                    if "no such module" not in str(exc):
+                        raise
+            ranked = [{k: f[k] for k in ("id", "title", "text", "scope")} | {"score": len(set(words) & self._query_words(f["title"] + " " + f["text"]))} for f in facts]
+            return sorted([r for r in ranked if r["score"]], key=lambda r: r["score"], reverse=True)[:limit]
+
+    def get_topic(self, id, scope="workspace"):
+        path = safe_path(self._root(scope), "topics", _id(id) + ".json")
+        with self._locked():
+            if not path.exists():
+                return ""
+            topic = self._read(path)
+            return sanitize_memory("# " + topic.get("title", id) + "\n\n" + "\n".join("- " + f["text"] for f in topic.get("facts", [])), max_chars=20000)
+
+    def memory_operation(self, action, *, target="memory", text="", match=""):
+        try:
+            return self._memory_operation(action, target=target, text=text, match=match)
+        except ValueError as exc:
+            self._archive_record("memory/operations.jsonl", {"action": sanitize_text(action), "target": sanitize_text(target),
+                "text": sanitize_text(text, max_chars=600), "match": sanitize_text(match), "status": "error", "result": sanitize_text(str(exc))})
+            raise
+
+    def _memory_operation(self, action, *, target="memory", text="", match=""):
+        action = action.strip().lower()
+        if target not in {"memory", "user"}:
+            raise ValueError("target must be memory or user")
+        if action not in {"add", "replace", "remove"}:
+            raise ValueError("action must be add, replace, or remove")
+        scope, topic_id = ("global", "preferences") if target == "user" else ("workspace", "general")
+        clean = sanitize_text(text.strip(), max_chars=600)
+        with self._locked():
+            if action == "add":
+                if not clean:
+                    raise ValueError("add requires non-empty text")
+                self._record(self._candidate(clean, topic_id, scope, ["explicit-user", _now()]))
+                stats = self._consolidate()
+                result = "added memory entry" if stats["added"] else f"{target} unchanged: duplicate entry"
+            else:
+                # Drain pending facts first so mutations cannot be undone by a
+                # candidate that existed before the explicit edit.
+                self._consolidate()
+                topics = list(self._topic_records(scope))
+                found = [(t, i) for t in topics for i, f in enumerate(t["facts"]) if match and match in f["text"] and (target != "user" or t["id"] == "preferences")]
+                if len(found) != 1:
+                    raise ValueError(f"match must identify exactly one entry; matches: {len(found)}")
+                topic, position = found[0]
+                if action == "remove":
+                    topic["facts"].pop(position)
+                else:
+                    if not clean:
+                        raise ValueError("replace requires non-empty text")
+                    topic["facts"][position] = {**topic["facts"][position], "id": _hash([scope, clean.casefold()]), "text": clean}
+                topic["updated_at"] = _now()
+                self._write(safe_path(self._root(scope), "topics", topic["id"] + ".json"), topic)
+                result = f"{target} updated: {action}"
+        self.archive_memory_snapshot()
+        self._archive_record("memory/operations.jsonl", {"action": action, "target": target, "text": clean, "match": sanitize_text(match), "status": "ok", "result": result})
+        return result
+
+    def _query_entries(self):
+        with self._locked():
+            return [MemoryEntry("user" if f["scope"] == "global" and f["id"] == "preferences" else "memory", f["text"], i) for i, f in enumerate(self._facts())]
+
+    def _query(self, task, *, limit=6, max_chars=1400, recent_context="", include_preferences=False):
+        if limit <= 0 or max_chars <= len(MEMORY_CONTEXT_PREFIX) + 1:
+            return ""
+        current = self.search(task, limit=max(100, limit))
+        recent = self.search(recent_context, limit=max(100, limit)) if recent_context else []
+        # Current task matches outrank recent-context-only matches.
+        candidates = current + recent
+        preferences = []
+        if include_preferences:
+            with self._locked():
+                preferences = [f for f in self._facts() if f["scope"] == "global" and f["id"] == "preferences"][:2]
+        selected, seen = [], set()
+        used = len(MEMORY_CONTEXT_PREFIX) + 1
+        preference_budget = min(400, (max_chars - used) // 3)
+        for fact in preferences + candidates:
+            text = sanitize_memory(fact["text"], max_chars=max_chars)
+            line = "- " + text
+            pref = fact in preferences
+            if not text or text.casefold() in seen or len(selected) >= limit:
+                continue
+            if used + len(line) + 1 > max_chars or (pref and len(line) + 1 > preference_budget):
+                continue
+            selected.append(line)
+            seen.add(text.casefold())
+            used += len(line) + 1
+            if pref:
+                preference_budget -= len(line) + 1
+        return MEMORY_CONTEXT_PREFIX + "\n" + "\n".join(selected) if selected else ""
+
+    def query(self, task, *, limit=6, max_chars=1400, recent_context="", include_preferences=False):
+        context = self._query(task, limit=limit, max_chars=max_chars, recent_context=recent_context, include_preferences=include_preferences)
+        self.archive_memory_snapshot()
+        self.archive_context("queried", task, context)
+        return context
+
+    def context_for(self, task, *, limit=6, max_chars=1400):
+        return self.query(task, limit=limit, max_chars=max_chars)
+
+    def snapshot(self, *, max_chars=1400):
+        if max_chars <= len(MEMORY_CONTEXT_PREFIX) + 1:
+            return ""
+        with self._locked():
+            facts = list(self._facts())
+        if not facts:
+            return ""
+        return sanitize_memory(MEMORY_CONTEXT_PREFIX + "\n" + "\n".join("- " + f["text"] for f in facts), max_chars=max_chars)
+
+    def append_legacy_summary(self, summary, *, source_task=""):
+        self.append(Lesson(summary=summary, source_task=source_task))
+
+    def append(self, lesson):
+        clean = Lesson(summary=sanitize_text(lesson.summary, max_chars=240),
+                       worked=[sanitize_text(s, max_chars=180) for s in lesson.worked[:6]],
+                       failed=[sanitize_text(s, max_chars=180) for s in lesson.failed[:6]],
+                       applicable_when=[sanitize_text(s, max_chars=120) for s in lesson.applicable_when[:6]],
+                       confidence=max(0, min(1, lesson.confidence)), source_task=sanitize_task(lesson.source_task),
+                       created_at=sanitize_text(lesson.created_at, max_chars=80))
+        with self._locked():
+            lessons = [lesson for lesson in self.load() if lesson.summary.casefold() != clean.summary.casefold()] + [clean]
+            self._rewrite(lessons[-self.max_lessons:])
+        self._archive_record("learning/lessons.jsonl", asdict(clean))
+
+    def load(self):
+        lessons = []
+        with self._locked():
+            if not self.path.exists():
+                return []
+            for line in self.path.read_text(encoding="utf-8").splitlines():
+                try:
+                    lessons.append(Lesson(**json.loads(line)))
+                except (ValueError, TypeError):
+                    continue
+        return lessons
+
+    def _rewrite(self, lessons):
+        publish(self.path, ("".join(lesson.to_json() + "\n" for lesson in lessons)).encode())
+
+    def to_markdown(self):
+        with self._locked():
+            facts = list(self._facts())
+        lessons = self.load()
+        jobs = self.pending_jobs()
+        with self._locked():
+            inbox = sum(len(list(safe_path(root, "observations/_inbox").glob("*.json"))) for root in self.roots.values())
+        if not facts and not lessons and not jobs and not inbox:
+            return "# Agent learnings\n\n_No lessons stored yet for this workspace._\n"
+        lines = ["# Agent learnings", "", "_Durable topics in this session's `memories/`. Global preferences live in `~/.symphony/memories/global/`._", "",
+                 f"Pending capture jobs: {len(jobs)}; observations awaiting consolidation: {inbox}", ""]
+        lines.extend(f"- Capture `{job['id']}` · session `{job.get('session_id', '')}`" for job in jobs)
+        lines.extend(f"- [{f['scope']}/{f['id']}] {f['text']}" for f in facts)
+        for lesson in reversed(lessons):
+            lines.extend(["", "## " + lesson.summary, f"- **Confidence:** {lesson.confidence:.2f}", "- **Source task:** " + lesson.source_task])
+        return sanitize_memory("\n".join(lines), max_chars=100000) + "\n"
+
+    def scoped_markdown(self, scope, *, session_id=None):
+        """Present actual source provenance, never label workspace facts as session facts."""
+        if scope not in {"session", "global"}:
+            raise ValueError("view must be session or global")
+        session_id = session_id or self.session_id
+        lines = ["# Global memory" if scope == "global" else "# Session memory", ""]
+        with self._locked():
+            if scope == "global":
+                topics = list(self._topic_records("global"))
+                facts = [(topic, fact) for topic in topics for fact in topic.get("facts", [])]
+                jobs = []
+            else:
+                jobs = [self._read(safe_path(self.memory_dir, "jobs", _id(path.stem) + ".json"))
+                        for path in sorted(safe_path(self.memory_dir, "jobs").glob("*.json"))]
+                jobs = [job for job in jobs if session_id and job.get("session_id") == session_id]
+                job_ids = {job["id"] for job in jobs}
+                facts = [(topic, fact) for topic in self._topic_records("workspace")
+                         for fact in topic.get("facts", []) if job_ids.intersection(fact.get("sources", []))]
+                lines.extend([f"Session: {session_id or '(no active session)'}", "",
+                              f"Captures: {len(jobs)} · pending: {sum(job.get('status') != 'complete' for job in jobs)}", ""])
+                # Explicit session memory edits have provenance in the session audit,
+                # not in an extraction job. Include those separately from captured facts.
+                if self.session_dir is not None and session_id == self.session_id:
+                    audit = safe_path(self.session_dir, "memory/operations.jsonl")
+                    if audit.is_file():
+                        for raw in audit.read_text(encoding="utf-8").splitlines():
+                            try:
+                                operation = json.loads(raw)
+                            except ValueError:
+                                continue
+                            if operation.get("status") == "ok" and operation.get("target") == "memory":
+                                lines.append(f"- Memory edit ({operation.get('action', '')}): {sanitize_text(operation.get('text') or operation.get('match', ''), max_chars=600)}")
+            for topic, fact in facts:
+                lines.extend([f"## {topic.get('title', topic['id'])}", "", sanitize_memory(fact["text"], max_chars=2000), ""])
+            if not facts:
+                lines.append("No global facts saved yet." if scope == "global" else "No curated facts captured from this session yet.")
+            for job in jobs:
+                lines.append(f"- Capture {job['id'][:12]} · {job.get('status', 'pending')}")
+        return sanitize_memory("\n".join(lines), max_chars=100000) + "\n"
+
+    def _archive_record(self, relative_path, record):
+        if self.session_dir is None:
+            return
+        try:
+            append_bytes(safe_path(self.session_dir, relative_path), (json.dumps({"created_at": _now(), **record}, ensure_ascii=False) + "\n").encode())
+        except (OSError, ValueError):
+            logger.warning("Could not archive session memory record", exc_info=True)
+
+    def archive_memory_snapshot(self):
+        if self.session_dir is None:
+            return
+        try:
+            with self._locked():
+                facts = list(self._facts())
+            for target, scope, root, limit in (
+                ("MEMORY.md", "workspace", self.memory_dir, 3000),
+                ("USER.md", "global", self.global_root, 1500),
+            ):
+                raw = "\n".join("- " + f["text"] for f in facts if f["scope"] == scope)
+                publish(safe_path(root, target), sanitize_memory(raw, max_chars=limit).encode())
+        except (OSError, ValueError, UnicodeError):
+            logger.warning("Could not archive session memory snapshot", exc_info=True)
+
+    def archive_context(self, kind, task, context):
+        self._archive_record("learning/context.jsonl", {"kind": kind, "source": "durable topical memory (untrusted reference data)", "task": sanitize_task(task), "context": sanitize_memory(context, max_chars=max(1400, len(context)))})
+
+    def bind_session(self, session_id, session_dir=None):
+        self.session_id = session_id
+        if session_dir is not None:
+            self.session_dir = Path(session_dir).resolve()
+        self.archive_memory_snapshot()

coding_agent/addons/manager/__init__.py

@@ -0,0 +1,18 @@
+"""User addons from ``~/.symphony/addons`` merged into the coding agent."""
+
+from coding_agent.addons.manager.bridge import AddonSurface, build_surface
+from coding_agent.addons.manager.discovery import BUILTIN_ADDON_NAMES, load_user_addons, user_addons_root
+from coding_agent.addons.manager.report import addons_report
+from coding_agent.addons.manager.runtime import UserAddonRuntime
+from coding_agent.addons.manager.tool_changes import tool_change_notice
+
+__all__ = [
+    "BUILTIN_ADDON_NAMES",
+    "AddonSurface",
+    "UserAddonRuntime",
+    "addons_report",
+    "build_surface",
+    "load_user_addons",
+    "tool_change_notice",
+    "user_addons_root",
+]

coding_agent/addons/manager/bridge.py

@@ -0,0 +1,74 @@
+"""Merge a user-addon snapshot with the built-in tools and commands.
+
+Built-in names always win. A user tool or command that reuses one, or
+that another user addon already took, is dropped with a notice.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Collection
+
+from core_harness import Tool
+from core_harness.extensions import CommandSpec, ExtensionSnapshot
+
+from coding_agent.commands.catalog import SLASH_COMMANDS, SlashCommand
+
+
+@dataclass(frozen=True)
+class AddonSurface:
+    """What the agent actually exposes from one snapshot."""
+
+    snapshot: ExtensionSnapshot
+    tools: tuple[Tool, ...]
+    commands: tuple[CommandSpec, ...]
+    notices: tuple[str, ...]
+
+    @property
+    def tool_names(self) -> frozenset[str]:
+        return frozenset(tool.name for tool in self.tools)
+
+    @property
+    def slash_commands(self) -> tuple[SlashCommand, ...]:
+        return tuple(SlashCommand(item.name, item.description, item.argument) for item in self.commands)
+
+    def command(self, name: str) -> CommandSpec | None:
+        for item in self.commands:
+            if item.name == name:
+                return item
+        return None
+
+
+BUILTIN_COMMAND_NAMES: frozenset[str] = frozenset(
+    {item.name for item in SLASH_COMMANDS} | {"exit", "extensions", "plugins", "skills"}
+)
+
+
+def build_surface(
+    snapshot: ExtensionSnapshot,
+    *,
+    builtin_tool_names: Collection[str],
+    builtin_command_names: Collection[str] = BUILTIN_COMMAND_NAMES,
+) -> AddonSurface:
+    notices = list(snapshot.notices)
+    tools: list[Tool] = []
+    commands: list[CommandSpec] = []
+    taken_tools = set(builtin_tool_names)
+    taken_commands = set(builtin_command_names)
+    for addon in snapshot.loaded:
+        for tool in addon.tools:
+            if tool.name in taken_tools:
+                notices.append(f"addon {addon.name!r}: tool {tool.name!r} is already taken and was not added")
+                continue
+            taken_tools.add(tool.name)
+            tools.append(tool)
+        for command in addon.commands:
+            if command.name in taken_commands:
+                notices.append(f"addon {addon.name!r}: /{command.name} is already taken and was not added")
+                continue
+            taken_commands.add(command.name)
+            commands.append(command)
+    return AddonSurface(snapshot, tuple(tools), tuple(commands), tuple(notices))
+
+
+__all__ = ["BUILTIN_COMMAND_NAMES", "AddonSurface", "build_surface"]

coding_agent/addons/manager/discovery.py

@@ -0,0 +1,34 @@
+"""Where user addons live and which names they may not take.
+
+Only ``<symphony home>/addons/<name>/`` is scanned (``SYMPHONY_HOME``
+overrides the home). There is no project-local addon folder.
+"""
+
+from __future__ import annotations
+
+import pkgutil
+from pathlib import Path
+from typing import Collection
+
+import coding_agent.addons as builtin_addons
+from core_harness.extensions import ExtensionSnapshot, load_addons
+
+from coding_agent.config import symphony_dir
+
+BUILTIN_ADDON_NAMES: frozenset[str] = frozenset(
+    module.name for module in pkgutil.iter_modules(builtin_addons.__path__)
+)
+
+
+def user_addons_root() -> Path:
+    return symphony_dir() / "addons"
+
+
+def load_user_addons(reserved_names: Collection[str] = ()) -> ExtensionSnapshot:
+    return load_addons(
+        (user_addons_root(),),
+        reserved_names=BUILTIN_ADDON_NAMES | frozenset(reserved_names),
+    )
+
+
+__all__ = ["BUILTIN_ADDON_NAMES", "load_user_addons", "user_addons_root"]