symphony-code 0.0.1__tar.gz

symphony_code-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarthak Chauhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

symphony_code-0.0.1/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: symphony-code
+Version: 0.0.1
+Summary: Symphony coding agent: workspace tools, JSONL sessions, and a Textual TUI on top of symphony-harness (import as coding_agent; run as `symphony`)
+Author: Sarthak Chauhan
+Author-email: Sarthak Chauhan <sarthakchauhann@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: symphony-core
+Requires-Dist: symphony-harness
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: textual>=8.2.8
+Requires-Dist: textual-image>=0.12.0
+Requires-Dist: termaid>=0.9.0
+Requires-Dist: sounddevice>=0.5.1
+Requires-Dist: langfuse>=3.0.0 ; extra == 'langfuse'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Sarthakischauhan/symphony
+Project-URL: Documentation, https://github.com/Sarthakischauhan/symphony/blob/main/docs/packages/symphony-code.md
+Project-URL: Source, https://github.com/Sarthakischauhan/symphony/tree/main/coding_agent
+Provides-Extra: langfuse
+Description-Content-Type: text/markdown
+
+# symphony-code
+
+Run an AI coding agent in your terminal, or import the coding-agent API from the Symphony workspace. Package import name: `coding_agent`.
+
+**Availability:** this package is not currently published on PyPI. To run it today, use a checkout of the repository:
+
+```sh
+git clone https://github.com/Sarthakischauhan/symphony.git
+cd symphony
+uv sync
+uv run --package symphony-code symphony --workspace /path/to/project
+```
+
+`symphony`, `symphony-code`, and `coding-agent-tui` are aliases for the same terminal application. Configure a provider on first launch, or set credentials beforehand. See the [installation guide](../docs/getting-started/installation.md) and [quickstart](../docs/getting-started/quickstart.md).
+
+## Use the library
+
+From the repository workspace:
+
+```python
+from core_ai import build_default_registry, default_model_id
+from coding_agent import CodingAgent
+
+registry = build_default_registry()
+agent = CodingAgent(
+    registry=registry,
+    model_id=default_model_id(registry),
+    workspace=".")
+result = await agent.run("Fix the failing test")
+print(result.output_text)
+```
+
+## Next steps
+
+- [Terminal UI and controls](../docs/user-guide/tui.md)
+- [Configuration and approvals](../docs/user-guide/configuration.md)
+- [Tools and workspace access](../docs/user-guide/tools.md)
+- [Sessions and resume](../docs/user-guide/sessions.md)
+- [Package API guide](../docs/packages/symphony-code.md)
+
+**Safety:** tools run with the current user's permissions; approval prompts do not sandbox commands or restrict paths. Read the [security policy](../SECURITY.md) before use.

symphony_code-0.0.1/README.md

@@ -0,0 +1,41 @@
+# symphony-code
+
+Run an AI coding agent in your terminal, or import the coding-agent API from the Symphony workspace. Package import name: `coding_agent`.
+
+**Availability:** this package is not currently published on PyPI. To run it today, use a checkout of the repository:
+
+```sh
+git clone https://github.com/Sarthakischauhan/symphony.git
+cd symphony
+uv sync
+uv run --package symphony-code symphony --workspace /path/to/project
+```
+
+`symphony`, `symphony-code`, and `coding-agent-tui` are aliases for the same terminal application. Configure a provider on first launch, or set credentials beforehand. See the [installation guide](../docs/getting-started/installation.md) and [quickstart](../docs/getting-started/quickstart.md).
+
+## Use the library
+
+From the repository workspace:
+
+```python
+from core_ai import build_default_registry, default_model_id
+from coding_agent import CodingAgent
+
+registry = build_default_registry()
+agent = CodingAgent(
+    registry=registry,
+    model_id=default_model_id(registry),
+    workspace=".")
+result = await agent.run("Fix the failing test")
+print(result.output_text)
+```
+
+## Next steps
+
+- [Terminal UI and controls](../docs/user-guide/tui.md)
+- [Configuration and approvals](../docs/user-guide/configuration.md)
+- [Tools and workspace access](../docs/user-guide/tools.md)
+- [Sessions and resume](../docs/user-guide/sessions.md)
+- [Package API guide](../docs/packages/symphony-code.md)
+
+**Safety:** tools run with the current user's permissions; approval prompts do not sandbox commands or restrict paths. Read the [security policy](../SECURITY.md) before use.

symphony_code-0.0.1/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "symphony-code"
+version = "0.0.1"
+description = "Symphony coding agent: workspace tools, JSONL sessions, and a Textual TUI on top of symphony-harness (import as coding_agent; run as `symphony`)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+    "symphony-core",
+    "symphony-harness",
+    "pillow>=12.3.0",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0.3",
+    "textual>=8.2.8",
+    "textual-image>=0.12.0",
+    "termaid>=0.9.0",
+    "sounddevice>=0.5.1",
+]
+
+[[project.authors]]
+name = "Sarthak Chauhan"
+email = "sarthakchauhann@gmail.com"
+
+[project.optional-dependencies]
+langfuse = ["langfuse>=3.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/Sarthakischauhan/symphony"
+Documentation = "https://github.com/Sarthakischauhan/symphony/blob/main/docs/packages/symphony-code.md"
+Source = "https://github.com/Sarthakischauhan/symphony/tree/main/coding_agent"
+
+[project.scripts]
+symphony = "coding_agent.tui.__main__:main"
+symphony-code = "coding_agent.tui.__main__:main"
+coding-agent-tui = "coding_agent.tui.__main__:main"
+
+[tool.uv.sources.symphony-core]
+workspace = true
+
+[tool.uv.sources.symphony-harness]
+workspace = true
+
+[tool.uv.build-backend]
+module-name = "coding_agent"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.10.0"]
+build-backend = "uv_build"

symphony_code-0.0.1/pyproject.toml.orig

@@ -0,0 +1,52 @@
+[project]
+name = "symphony-code"
+version = "0.0.1"
+description = "Symphony coding agent: workspace tools, JSONL sessions, and a Textual TUI on top of symphony-harness (import as coding_agent; run as `symphony`)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Sarthak Chauhan", email = "sarthakchauhann@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "symphony-core",
+    "symphony-harness",
+    "pillow>=12.3.0",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0.3",
+    "textual>=8.2.8",
+    "textual-image>=0.12.0",
+    "termaid>=0.9.0",
+    "sounddevice>=0.5.1",
+]
+
+[project.optional-dependencies]
+langfuse = ["langfuse>=3.0.0"]
+[project.urls]
+Homepage = "https://github.com/Sarthakischauhan/symphony"
+Documentation = "https://github.com/Sarthakischauhan/symphony/blob/main/docs/packages/symphony-code.md"
+Source = "https://github.com/Sarthakischauhan/symphony/tree/main/coding_agent"
+
+[project.scripts]
+# `symphony` is the primary command; the other two are aliases kept for
+# compatibility and all resolve to the same entry point.
+symphony = "coding_agent.tui.__main__:main"
+symphony-code = "coding_agent.tui.__main__:main"
+coding-agent-tui = "coding_agent.tui.__main__:main"
+
+[tool.uv.sources]
+symphony-core = { workspace = true }
+symphony-harness = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "coding_agent"

symphony_code-0.0.1/src/coding_agent/__init__.py

@@ -0,0 +1,20 @@
+from coding_agent.agent import CodingAgent, build_agent
+from coding_agent.addons.learning import LearningAddon, LearningLoop, LearningReview, LearningStore, Lesson
+from coding_agent.addons.persistence import JsonlPersistence, SessionSummary
+from coding_agent.config.prompts import SUBAGENT_SYSTEM_PROMPT, SYSTEM_PROMPT
+from coding_agent.tools import (
+    AskUserArgs, AskUserTool, BashArgs, BashTool,
+    GenerateImageArgs, GenerateImageTool, PatchArgs, PatchTool, ReadFileArgs, ReadFileTool,
+    SearchArgs, SearchTool, TOOL_CLASSES, ToolArgsModel, WebSearchArgs, WebSearchTool, WorkspaceTool,
+    WriteFileArgs, WriteFileTool, build_tools,
+)
+
+__all__ = [
+    "AskUserArgs", "AskUserTool", "BashArgs", "BashTool", "CodingAgent",
+    "GenerateImageArgs", "GenerateImageTool", "LearningAddon", "LearningLoop", "LearningReview",
+    "LearningStore", "Lesson", "PatchArgs", "PatchTool", "ReadFileArgs",
+    "ReadFileTool", "SUBAGENT_SYSTEM_PROMPT", "SYSTEM_PROMPT", "SearchArgs", "SearchTool",
+    "JsonlPersistence", "SessionSummary", "TOOL_CLASSES", "ToolArgsModel", "WebSearchArgs", "WebSearchTool",
+    "WorkspaceTool",
+    "WriteFileArgs", "WriteFileTool", "build_agent", "build_tools",
+]

symphony_code-0.0.1/src/coding_agent/_lazy.py

@@ -0,0 +1,17 @@
+"""Defer an attribute until the module that owns it has finished importing."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+
+def resolve(module_globals: dict[str, Any], name: str, exports: dict[str, tuple[str, str]]) -> Any:
+    target = exports.get(name)
+    if target is None:
+        module_name = module_globals.get("__name__", "module")
+        raise AttributeError(f"module {module_name!r} has no attribute {name!r}")
+    source, attr = target
+    value = getattr(import_module(source), attr)
+    module_globals[name] = value
+    return value

symphony_code-0.0.1/src/coding_agent/addons/__init__.py

@@ -0,0 +1,35 @@
+"""Product harness add-ons.
+
+Feature packages keep each add-on's hooks and supporting machinery together.
+This package exports the add-ons that ``CodingAgent`` mounts.
+"""
+
+from coding_agent.addons.approvals import ApprovalAddon, ApprovalPolicy
+from coding_agent.addons.compaction.addon import AiCompactionAddon, ai_compaction_from_config
+from coding_agent.addons.evaluation.addon import JevAddon, jev_from_config
+from coding_agent.addons.langfuse.addon import LangfuseAddon, langfuse_from_config
+from coding_agent.addons.learning.addon import (
+    LEARNING_IDLE_DELAY_SECONDS,
+    LearningAddon,
+    SessionMemoryAddon,
+    inject_memory,
+    strip_memory_context,
+)
+from coding_agent.addons.skills.addon import SkillsAddon
+
+__all__ = [
+    "AiCompactionAddon",
+    "ApprovalAddon",
+    "ApprovalPolicy",
+    "JevAddon",
+    "LEARNING_IDLE_DELAY_SECONDS",
+    "LangfuseAddon",
+    "LearningAddon",
+    "SessionMemoryAddon",
+    "SkillsAddon",
+    "ai_compaction_from_config",
+    "inject_memory",
+    "jev_from_config",
+    "langfuse_from_config",
+    "strip_memory_context",
+]

symphony_code-0.0.1/src/coding_agent/addons/approvals.py

@@ -0,0 +1,224 @@
+"""Product approval rules, independent of the TUI.
+
+The harness calls ``Addon.before_tool`` before running a tool. This add-on
+implements symphony-code policy: durable deny/allow rules, which tools need
+a prompt, how answers map to allow/deny, and that children do not inherit
+the gate (except the deny rules in unattended runs). The TUI only renders the
+question and returns the answer. Unattended runs never prompt: each decision a
+human would have made is emitted as an ``auto_decision`` event instead.
+"""
+
+from __future__ import annotations
+
+import os
+from fnmatch import fnmatchcase
+from pathlib import Path
+from typing import Any, Dict, Optional, Sequence, Union
+
+from core_harness import Addon, EventSink
+
+from coding_agent.config import ApprovalConfig, ensure_spawn_settings
+
+ALLOW_ONCE = "Allow once"
+ALLOW_ALWAYS = "Always allow"
+DENY = "Deny"
+APPROVAL_CHOICES = (ALLOW_ONCE, ALLOW_ALWAYS, DENY)
+AUTO_DECISION = "auto_decision"
+RULE_SUBJECTS = {
+    "bash": "command", "write_file": "path", "patch": "path", "generate_image": "path",
+    "web_search": "query",
+}
+
+
+def rule_subjects(tool_name: str, arguments: Dict[str, Any], workspace: Path) -> set[str]:
+    """The bash command, ``web_search:<query>``, or a path normalized so ``../`` and symlinks cannot dodge a rule."""
+    field = RULE_SUBJECTS.get(tool_name)
+    raw = str(arguments.get(field) or "").strip() if field else ""
+    if not raw or field == "command":
+        return {raw} if raw else set()
+    if field == "query":
+        # Prefixed so a bash rule such as ``git *`` cannot allow a search.
+        return {f"{tool_name}:{raw}"}
+    joined = os.path.join(workspace, os.path.expanduser(raw))
+    absolute, resolved = os.path.normpath(joined), str(Path(joined).resolve())
+    return {absolute, resolved, os.path.relpath(absolute, workspace)}
+
+
+def matching_rule(
+    patterns: Sequence[str], tool_name: str, arguments: Dict[str, Any], workspace: Path
+) -> Optional[str]:
+    """First pattern matching the bash command, the prefixed query, or any normalized form of the path."""
+    subjects = rule_subjects(tool_name, arguments, workspace)
+    return next((p for p in patterns if any(fnmatchcase(s, p) for s in subjects)), None)
+
+
+class ApprovalPolicy:
+    """Path-aware rules. Callers pass the current ``ApprovalConfig``."""
+
+    def __init__(self, workspace: Union[str, Path]) -> None:
+        self.workspace = Path(workspace).expanduser().resolve()
+
+    def prompt_for(
+        self,
+        config: ApprovalConfig,
+        tool_name: str,
+        arguments: Dict[str, Any],
+    ) -> str:
+        """Return the question to ask, or ``""`` if the call is allowed.
+
+        Deny rules are not a prompt; ``ApprovalAddon`` checks them first.
+        """
+        if config.mode == "always_allow" or matching_rule(config.allow, tool_name, arguments, self.workspace):
+            return ""
+        if tool_name == "bash" and config.require_for_bash:
+            command = str(arguments.get("command") or "").strip()
+            return f"Allow bash command once?\n`{command}`"
+        if tool_name == "web_search" and config.require_for_web_search:
+            query = str(arguments.get("query") or "").strip()
+            return f"Allow web search once?\n`{query}`"
+        if tool_name in {"write_file", "generate_image"}:
+            path = str(arguments.get("path") or "").strip()
+            if config.require_for_overwrite and path and self._exists(path):
+                return f"Overwrite existing file `{path}`?"
+            return ""
+        if tool_name == "patch" and config.require_for_broad_patch:
+            path = str(arguments.get("path") or "").strip()
+            old = str(arguments.get("old_str") or arguments.get("old_string") or "")
+            replace_all = bool(arguments.get("replace_all"))
+            if replace_all or len(old) > config.broad_patch_chars:
+                kind = "global" if replace_all else "large"
+                return f"Apply a {kind} patch to `{path}`?"
+        return ""
+
+    def interpret(
+        self,
+        config: ApprovalConfig,
+        answer: str,
+    ) -> tuple[bool, bool]:
+        """Map a UI answer to ``(allowed, promote_to_always_allow)``."""
+        if config.mode == "always_allow":
+            return True, False
+        normalized = answer.strip().lower()
+        if normalized == ALLOW_ALWAYS.lower():
+            return True, True
+        return normalized in config.allow_answers, False
+
+    def _exists(self, path: str) -> bool:
+        try:
+            candidate = Path(path).expanduser()
+            target = (
+                candidate.resolve()
+                if candidate.is_absolute()
+                else (self.workspace / candidate).resolve()
+            )
+            return target.exists()
+        except OSError:
+            return False
+
+
+class ApprovalAddon(Addon):
+    """Gate tools through deny rules, then :class:`ApprovalPolicy` prompts.
+
+    The live approval state is ``approvals`` on this add-on, the same for
+    every client. ``set_mode`` changes it and reports ``config_changed``.
+
+    Deny rules apply in every mode. ``fork_for_child`` returns ``None`` so
+    spawned children skip this gate, except in unattended runs where children
+    get a deny-only fork. That is product policy, documented in ``SECURITY.md``.
+    """
+
+    name = "approval"
+
+    def __init__(
+        self,
+        workspace: Union[str, Path],
+        plane: EventSink,
+        *,
+        approvals: Optional[ApprovalConfig] = None,
+        unattended: bool = False,
+        deny_only: bool = False,
+    ) -> None:
+        self.policy = ApprovalPolicy(workspace)
+        self.plane = plane
+        self.approvals = approvals
+        self.unattended = unattended
+        self.deny_only = deny_only
+
+    def fork_for_child(self, parent_harness: Any) -> Optional["ApprovalAddon"]:
+        del parent_harness
+        if not self.unattended:
+            return None
+        return ApprovalAddon(
+            self.policy.workspace, self.plane,
+            approvals=self.approvals, unattended=True, deny_only=True,
+        )
+
+    async def before_tool(
+        self,
+        *,
+        tool_name: str,
+        arguments: Dict[str, Any],
+        sink: Optional[EventSink] = None,
+        emit: Any = None,
+        tool_call: Any = None,
+        **_: Any,
+    ) -> Optional[str]:
+        approvals = self.approvals
+        if approvals is None:
+            return None
+        emit = emit or self.plane.emit
+        rule = matching_rule(approvals.deny, tool_name, arguments, self.policy.workspace)
+        if rule:
+            await emit(AUTO_DECISION, {"kind": "approval", "tool": tool_name, "decision": "deny", "rule": rule})
+            return f"tool call denied by rule {rule!r}"
+        if self.unattended and tool_name == "ask_user":
+            await emit(AUTO_DECISION, {"kind": "ask_user", "question": str(arguments.get("question") or "")})
+        if self.deny_only:
+            return None
+        prompt = self.policy.prompt_for(approvals, tool_name, arguments)
+        if not prompt:
+            return None
+        if self.unattended:
+            await emit(AUTO_DECISION, {"kind": "approval", "tool": tool_name, "decision": "allow", "rule": "unattended"})
+            return None
+        ask_on = sink or self.plane
+        answer = await ask_on.interaction.request_user_input(
+            question=prompt,
+            choices=APPROVAL_CHOICES,
+            default=ALLOW_ONCE,
+            kind="approval",
+            metadata={"tool_name": tool_name, "tool_call_id": str(getattr(tool_call, "id", "") or "")},
+        )
+        allowed, promote = self.policy.interpret(approvals, answer)
+        if promote:
+            await self.set_mode("always_allow", emit=emit)
+        if not allowed:
+            return "tool call denied by user"
+        return None
+
+    async def set_mode(self, mode: str, *, persist: bool = False, emit: Any = None) -> None:
+        """Change the approval mode for this agent and tell every client.
+
+        ``persist`` also writes it to the workspace settings.
+        """
+        current = self.approvals or ApprovalConfig()
+        self.approvals = ApprovalConfig.model_validate({**current.model_dump(), "mode": mode})
+        if persist:
+            config = ensure_spawn_settings(self.policy.workspace)
+            ensure_spawn_settings(
+                self.policy.workspace,
+                config=config.model_copy(update={"approvals": self.approvals}),
+            )
+        await (emit or self.plane.emit)("config_changed", {"approvals": {"mode": mode}})
+
+
+__all__ = [
+    "ALLOW_ALWAYS",
+    "ALLOW_ONCE",
+    "APPROVAL_CHOICES",
+    "AUTO_DECISION",
+    "ApprovalAddon",
+    "ApprovalPolicy",
+    "DENY",
+    "matching_rule",
+]

symphony_code-0.0.1/src/coding_agent/addons/compaction/__init__.py

@@ -0,0 +1,36 @@
+"""Model-backed conversation compaction for the coding agent.
+
+The harness owns the ``Compactor`` protocol and the keep/drop rule
+(``plan_keep_drop``). ``InferenceCompactor`` implements that protocol and
+writes the compacted-context message with the active model. The add-on that
+mounts it lives in ``coding_agent.addons.compaction.addon`` so this package does not
+import the add-on layer while it is still loading.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from coding_agent._lazy import resolve
+from coding_agent.addons.compaction.compactor import InferenceCompactor
+from coding_agent.addons.compaction.transcript import (
+    build_compacted_message,
+    render_dropped_turns,
+)
+
+_ADDON_EXPORTS = {
+    "AiCompactionAddon": ("coding_agent.addons.compaction.addon", "AiCompactionAddon"),
+    "ai_compaction_from_config": ("coding_agent.addons.compaction.addon", "ai_compaction_from_config"),
+}
+
+__all__ = [
+    "AiCompactionAddon",
+    "InferenceCompactor",
+    "ai_compaction_from_config",
+    "build_compacted_message",
+    "render_dropped_turns",
+]
+
+
+def __getattr__(name: str) -> Any:
+    return resolve(globals(), name, _ADDON_EXPORTS)

symphony_code-0.0.1/src/coding_agent/addons/compaction/addon.py

@@ -0,0 +1,88 @@
+"""Harness add-on that mounts ``InferenceCompactor``."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from core_harness.addons import Addon
+from core_harness.config import HarnessConfig
+
+from coding_agent.addons.compaction.compactor import (
+    DEFAULT_SUMMARY_MAX_OUTPUT_TOKENS,
+    InferenceCompactor,
+)
+from coding_agent.addons.compaction.transcript import DEFAULT_TRANSCRIPT_MAX_CHARS
+from coding_agent.config import CompactionConfig
+
+
+class AiCompactionAddon(Addon):
+    """Mount an ``InferenceCompactor`` on ``harness.state.compactor``.
+
+    Compaction is a before-model hook: the harness runs the mounted compactor
+    from ``maybe_compact`` ahead of each model turn and from ``/compact`` on
+    demand, then fires ``on_compact`` for the other add-ons. This add-on only
+    decides *which* compactor is mounted. It binds the compactor to the
+    harness registry and its *current* ``model_id`` so the summary follows
+    ``/model`` switches.
+
+    It occupies the ``compaction`` add-on slot, so it replaces the harness
+    ``CompactionAddon`` rather than sitting beside it. Children fork a fresh
+    add-on with the same settings; the child then binds to its own registry
+    and model on attach.
+    """
+
+    name = "compaction"
+
+    def __init__(
+        self,
+        *,
+        keep_recent_tools: int = 32,
+        target_tokens: Optional[int] = None,
+        max_output_tokens: int = DEFAULT_SUMMARY_MAX_OUTPUT_TOKENS,
+        max_transcript_chars: int = DEFAULT_TRANSCRIPT_MAX_CHARS,
+        model_id: Optional[str] = None,
+    ) -> None:
+        self.keep_recent_tools = keep_recent_tools
+        self.target_tokens = target_tokens
+        self.max_output_tokens = max_output_tokens
+        self.max_transcript_chars = max_transcript_chars
+        self.model_id = model_id
+        self.compactor: Optional[InferenceCompactor] = None
+
+    def attach(self, harness: Any) -> None:
+        self.compactor = InferenceCompactor(
+            registry=harness.registry,
+            model_id=self.model_id or (lambda: str(harness.model_id)),
+            keep_recent_tools=self.keep_recent_tools,
+            target_tokens=self.target_tokens,
+            max_output_tokens=self.max_output_tokens,
+            max_transcript_chars=self.max_transcript_chars,
+        )
+        harness.state.compactor = self.compactor
+
+    def fork_for_child(self, parent_harness: Any) -> AiCompactionAddon:
+        """Fresh add-on with the same settings; binds to the child on attach."""
+        del parent_harness
+        return AiCompactionAddon(
+            keep_recent_tools=self.keep_recent_tools,
+            target_tokens=self.target_tokens,
+            max_output_tokens=self.max_output_tokens,
+            max_transcript_chars=self.max_transcript_chars,
+            model_id=self.model_id,
+        )
+
+
+def ai_compaction_from_config(
+    harness_config: HarnessConfig,
+    compaction: CompactionConfig,
+) -> AiCompactionAddon:
+    """Build the add-on from harness keep/drop limits plus summary settings."""
+    return AiCompactionAddon(
+        keep_recent_tools=harness_config.compaction_keep_recent_tools,
+        target_tokens=harness_config.context_target_tokens,
+        max_output_tokens=compaction.max_output_tokens,
+        max_transcript_chars=compaction.max_transcript_chars,
+    )
+
+
+__all__ = ["AiCompactionAddon", "ai_compaction_from_config"]