From 8faa03889d508f54e56c8afecaf9a4288c94856f Mon Sep 17 00:00:00 2001 From: CREDO23 Date: Thu, 4 Jun 2026 13:47:10 +0200 Subject: [PATCH] docs(agents): refresh comments that referenced the deleted single-agent stack (bucket B6) After deleting app/agents/new_chat/, several shared-kernel comments still cited new_chat paths/cycles. Update the two lazy-import comments in middleware to state the real reason (tools.registry <-> shared.middleware cycle), and repoint dangling ``new_chat/tools/hitl.py`` / ``chat_deepagent`` doc references to their shared locations. Comment-only; suite unaffected. --- .../app/agents/shared/deliverable_wait.py | 10 +++++----- .../app/agents/shared/middleware/action_log.py | 6 +++--- .../app/agents/shared/middleware/doom_loop.py | 2 +- .../app/agents/shared/middleware/permission.py | 4 ++-- .../app/agents/shared/middleware/tool_call_repair.py | 6 +++--- surfsense_backend/app/agents/shared/tools/hitl.py | 4 ++-- 6 files changed, 16 insertions(+), 16 deletions(-) diff --git a/surfsense_backend/app/agents/shared/deliverable_wait.py b/surfsense_backend/app/agents/shared/deliverable_wait.py index abaa017ea..6f00a6c41 100644 --- a/surfsense_backend/app/agents/shared/deliverable_wait.py +++ b/surfsense_backend/app/agents/shared/deliverable_wait.py @@ -1,10 +1,10 @@ """Shared poll-until-terminal helper for Celery-backed deliverables. -Lives in ``app.agents.shared`` (neutral package, no dependencies on either -``new_chat`` or ``multi_agent_chat``) so both the flat single-agent tools -under ``app/agents/new_chat/tools/`` and the multi-agent subagent tools -under ``app/agents/multi_agent_chat/subagents/builtins/deliverables/tools/`` -can import it without creating a circular dependency. +Lives in ``app.agents.shared`` (neutral kernel package, no dependency on +``multi_agent_chat``) so both the shared tools under ``app/agents/shared/tools/`` +and the multi-agent subagent tools under +``app/agents/multi_agent_chat/subagents/builtins/deliverables/tools/`` can import +it without creating a circular dependency. Background ---------- diff --git a/surfsense_backend/app/agents/shared/middleware/action_log.py b/surfsense_backend/app/agents/shared/middleware/action_log.py index f26d78a4e..370b143bf 100644 --- a/surfsense_backend/app/agents/shared/middleware/action_log.py +++ b/surfsense_backend/app/agents/shared/middleware/action_log.py @@ -39,9 +39,9 @@ if TYPE_CHECKING: # pragma: no cover - type-only from langchain.agents.middleware.types import ToolCallRequest from langgraph.types import Command - # Type-only import: keeping it lazy avoids a module-load cycle through the - # frozen single-agent package (new_chat.__init__ -> chat_deepagent -> - # middleware shim). Resolves to app.agents.shared.tools once tools migrate. + # Type-only import: ToolDefinition is only referenced in annotations, and a + # runtime import would close a module-load cycle (tools.registry imports + # shared.middleware.dedup_tool_calls). from app.agents.shared.tools.registry import ToolDefinition diff --git a/surfsense_backend/app/agents/shared/middleware/doom_loop.py b/surfsense_backend/app/agents/shared/middleware/doom_loop.py index a7901c010..4f9b4af1c 100644 --- a/surfsense_backend/app/agents/shared/middleware/doom_loop.py +++ b/surfsense_backend/app/agents/shared/middleware/doom_loop.py @@ -16,7 +16,7 @@ This ships **OFF by default** until the frontend explicitly handles ``context.permission == "doom_loop"`` interrupts. Wire format: uses SurfSense's existing ``interrupt()`` payload shape -(see ``app/agents/new_chat/tools/hitl.py``): +(see ``app/agents/shared/tools/hitl.py``): { "type": "permission_ask", diff --git a/surfsense_backend/app/agents/shared/middleware/permission.py b/surfsense_backend/app/agents/shared/middleware/permission.py index 8601a3296..c277e29c7 100644 --- a/surfsense_backend/app/agents/shared/middleware/permission.py +++ b/surfsense_backend/app/agents/shared/middleware/permission.py @@ -8,7 +8,7 @@ per-thread overrides, and no auto-deny synthesis. This middleware ports OpenCode's ``packages/opencode/src/permission/index.ts`` ruleset model on top of SurfSense's existing ``interrupt({type, action, -context})`` payload shape (see ``app/agents/new_chat/tools/hitl.py``) so +context})`` payload shape (see ``app/agents/shared/tools/hitl.py``) so the frontend keeps working unchanged. Operation: @@ -85,7 +85,7 @@ def _default_pattern_resolver(name: str) -> PatternResolver: # Translation from the LangChain HITL envelope (what ``stream_resume_chat`` # sends) to SurfSense's legacy ``decision_type`` shape. ``edit`` keeps the # original tool args — tools needing argument edits should use -# ``request_approval`` from ``app/agents/new_chat/tools/hitl.py``. +# ``request_approval`` from ``app/agents/shared/tools/hitl.py``. _LC_TYPE_TO_PERMISSION_DECISION: dict[str, str] = { "approve": "once", "reject": "reject", diff --git a/surfsense_backend/app/agents/shared/middleware/tool_call_repair.py b/surfsense_backend/app/agents/shared/middleware/tool_call_repair.py index 966a1c75e..ddf003862 100644 --- a/surfsense_backend/app/agents/shared/middleware/tool_call_repair.py +++ b/surfsense_backend/app/agents/shared/middleware/tool_call_repair.py @@ -118,9 +118,9 @@ class ToolCallNameRepairMiddleware( return call # Stage 2 — invalid fallback - # Local import avoids a module-load cycle through the frozen single-agent - # package (new_chat.__init__ -> chat_deepagent -> middleware shim). - # Resolves to app.agents.shared.tools once tools migrate. + # Local import avoids a module-load cycle: tools.registry imports + # shared.middleware (dedup_tool_calls), so importing tools at module + # scope here would close the loop. from app.agents.shared.tools.invalid_tool import INVALID_TOOL_NAME if INVALID_TOOL_NAME in registered: diff --git a/surfsense_backend/app/agents/shared/tools/hitl.py b/surfsense_backend/app/agents/shared/tools/hitl.py index 287a19014..dd75dab9c 100644 --- a/surfsense_backend/app/agents/shared/tools/hitl.py +++ b/surfsense_backend/app/agents/shared/tools/hitl.py @@ -44,8 +44,8 @@ logger = logging.getLogger(__name__) # change is "no interrupt fires". # # To re-enable prompting, the future per-search-space rules table -# (``agent_permission_rules``) takes precedence — see the ``# (future)`` -# layer-3 comment in :mod:`app.agents.new_chat.chat_deepagent`. +# (``agent_permission_rules``) takes precedence in the permission ruleset +# layering assembled by the agent factory. DEFAULT_AUTO_APPROVED_TOOLS: frozenset[str] = frozenset( { "create_gmail_draft",