refactor: replace LangGraph ReAct agent with Deep Agents architecture by avoidwork · Pull Request #503 · avoidwork/madz

avoidwork · 2026-07-01T15:35:39Z

Description

Refactored the LangGraph-based ReAct agent to use LangChain's Deep Agents architecture. Replaced the process-spawning subAgent tool family with a native orchestrator that manages specialized agents (coding agent, general-purpose agent) for task delegation.

Changes

Deleted src/agent/react.js — replaced by clean deepAgents.js using createDeepAgent
Deleted src/tools/subAgent.js, subAgentLog.js, subAgentMessage.js — process spawning removed
Removed SUB_AGENT_TEMPERATURE env var handling from src/provider/openai.js
Removed old react_agent tests (react.js no longer exists)
Updated index.js to use invokeAgent with Deep Agents streaming API
Added coding-agent and general-purpose-agent subagents with SUB_AGENT.md prompts
Fixed process tool name from processTool to process
Removed middleware duplication that was causing test failures

Architecture

Main Agent (orchestrator)
  ├── Tool: all madz tools (filesystem, terminal, memory, etc.)
  ├── Sub Agent: coding-agent (file editing, debugging, implementation)
  └── Sub Agent: general-purpose-agent (research, file search, multi-step tasks)

Uses createDeepAgent with streamMode: "updates" and subgraphs: true for native streaming from both main agent and subagents.

Testing

All 1128 tests passing
Zero failures
Clean diff: +624 / -2943 lines

Related Issues

Closes #502

…specs, and tasks

- Replace react.js with clean deepAgents.js using createDeepAgent - Delete subAgent tool family (subAgent.js, subAgentLog.js, subAgentMessage.js) - Remove SUB_AGENT_TEMPERATURE env var handling - Remove old react_agent tests - Update index.js to use invokeAgent with Deep Agents streaming - Add coding-agent and utility-agent subagents with SUB_AGENT.md prompts - Fix process tool name from processTool to process - All 1128 tests passing

avoidwork · 2026-07-01T18:59:39Z

Audit Results

Status: Complete
Summary: Deep Agents refactoring implemented and tested.

Verification:

All 1128 tests passing, zero failures
react.js deleted, replaced by clean deepAgents.js using createDeepAgent
subAgent tool family deleted (subAgent.js, subAgentLog.js, subAgentMessage.js)
SUB_AGENT_TEMPERATURE env var handling removed
Process tool name fixed from processTool to process
Coding-agent and utility-agent subagents configured with SUB_AGENT.md prompts
Streaming uses createDeepAgent with streamMode updates and subgraphs true

Diff: +624 / -2943 lines across 23 files

Specs vs Implementation:

All behavioral requirements from specs implemented
Tasks.md all 58 tasks marked complete
No gaps between proposal/design/specs and implementation

Ready for review and merge.

- Remove unused variables from invokeAgent (signal, maxContextLength, maxTokens) - Remove unused namespace variable from stream loop - Auto-format index.js and prompts.test.js

The checkpointer requires thread_id in the configurable property to persist conversation state. Added configurable to streamOptions.

Pass systemPrompt to createDeepAgentsOrchestrator factory. Remove manual SystemMessage prepending from invokeAgent.

- streamMode: ['updates', 'messages'] to get text chunks and tool events - Handle mode === 'messages' for text/reasoning output - Handle mode === 'updates' for tool_start/tool_end/tool_error events

- Fix letconst syntax error from corrupted patch - Add missing variable initializations (currentMessages, compactionActive, etc.) - Restore proper while loop and try/catch structure - System prompt prepending restored in invokeAgent for new threads

avoidwork · 2026-07-01T20:01:16Z

Deep Agents Overlap Analysis

deepagents provides built-in middleware that includes these tool categories:

createFilesystemMiddleware — read_file, write_file, patch, search_files
createMemoryMiddleware — memory management
createSkillsMiddleware — skill discovery and management
createSummarizationMiddleware — context summarization/compaction

Overlapping Tools (can be removed from madz)

Madz Tool	Permission	Deep Agents Equivalent
`readFile`	filesystem:read	`createFilesystemMiddleware`
`writeFile`	filesystem:write	`createFilesystemMiddleware`
`patch`	filesystem:write	`createFilesystemMiddleware`
`searchFiles`	filesystem:read	`createFilesystemMiddleware`
`memory`	filesystem:read, filesystem:write	`createMemoryMiddleware`
`skillView`	filesystem:read	`createSkillsMiddleware`
`createSkill`	filesystem:write	`createSkillsMiddleware`
`compactContext`	none	`createSummarizationMiddleware`
`compaction`	none	`createSummarizationMiddleware`

Non-Overlapping Tools (unique to madz — keep)

Madz Tool	Permission	Notes
`terminal`	filesystem:exec, process:spawn	Shell execution
`process`	process:spawn	Background process management
`todo`	filesystem:read, filesystem:write	Task queue
`sessionSearch`	filesystem:read	Session history search
`clarify`	none	User clarification prompts
`webSearch`	network:outbound	Web search
`webExtract`	network:outbound	Web page extraction
`visionAnalyze`	none	Image analysis
`imageGenerate`	network:outbound	Image generation
`executeCode`	none	Code execution sandbox
`cronJob`	network:outbound	Cron scheduling
`textToSpeech`	none	TTS
`mixtureOfAgents`	none	MoA routing
`sampling`	none	Ephemeral memory sampling
`date`	none	Date/time
`scanAgents`	none	AGENTS.md scanning

Summary: 9 of 25 tools overlap with deepagents middleware. The remaining 16 are unique to madz and should stay.

Want me to remove the overlapping tools and wire up the deepagents middleware instead?

…apping tools - Create FileBackend implementing BackendProtocolV2 for file storage - Wire up createFilesystemMiddleware, createMemoryMiddleware, createSkillsMiddleware, createSummarizationMiddleware - Remove 9 overlapping tools from madz (readFile, writeFile, patch, searchFiles, memory, skillView, createSkill, compactContext, compaction) - Remove LRU caching from deepAgents.js - Remove unused compaction logic, constants, and imports - Remaining 16 tools are madz-specific and stay

- Delete obsolete tests for removed compactContext and compaction tools - Update tool_index.test.js to reflect current tool registry (16 tools) - Update tool_registration.test.js assertions for removed tools

…ware

…gents

The TUI's handleChat callback expects events with { type, text } shape, but callProvider was passing raw strings. This caused assistant response text to never render in the conversation panel.

- Pass middleware array to createDeepAgent (was built but never wired in) - Fix streaming callback to pass structured {type, text} events instead of raw strings - Remove unused RECURSION_LIMIT_MESSAGE constant - Remove unnecessary try/catch re-throw wrapper in callProvider - Prefix unused namespace variable with _ to satisfy linter

- README.md: Agent section, tools table, env vars, directory structure - docs/OVERVIEW.md: Replace Sub-Agent section with Deep Agents, remove Sub-Agent Log/Message sections - docs/FLOWS.md: Replace Sub-Agent flows with Deep Agents orchestration flow - docs/TUTORIAL.md: Update built-in tools section

- README.md: remove subAgent config entries, change 'specialized sub-agents' to 'specialized agents' - docs/OVERVIEW.md: remove sub-agent references, rephrase code identifiers - docs/FLOWS.md: change section titles and references

- README.md: remove subAgent, subAgentLog, subAgentMessage from tools table - docs/FLOWS.md: remove subAgentLog from file dependencies - docs/TUTORIAL.md: remove subAgent tool mention

- Split tools into Deep Agents middleware (filesystem, memory, skills, summarization) - and built-in LangChain tools gated by sandbox permissions - Omitted compactContext as requested

Removed filesystem.js, memory.js, skills.js, compact_context.js, compaction.js and their tests — these are now handled by deepagents middleware.

- Delete prompts/COMPACTION.md - Rename SUB_AGENT.md → CODE_AGENT.md - Update deepAgents.js to load CODE_AGENT.md - Rewrite CODE_AGENT.md as a tight, deliverables-focused coding agent prompt

…s memory parameter for AGENTS.md

…and AGENTS.md internally

…trator

…ator

avoidwork · 2026-07-02T18:20:51Z

Issue #502 Audit: Refactor LangGraph to Deep Agents

Completed ✅

src/agent/react.js → Deleted (528 lines)
src/tools/subAgent.js → Deleted (472 lines)
src/tools/subAgentLog.js → Deleted (184 lines)
src/tools/subAgentMessage.js → Deleted (97 lines)
prompts/SUB_AGENT.md → Deleted (127 lines)
src/tools/index.js → subAgent tool registrations removed
index.js → Uses createDeepAgentsOrchestrator
src/agent/deepAgents.js → Added (106 lines)
src/agent/coreBackend.js → Added
src/agent/contextBackend.js → Added
src/agent/subAgentsBackend.js → Added
tests/unit/react_agent.test.js → Deleted (1074 lines)
tests/unit/tools/subAgent.test.js → Deleted (221 lines)
tests/unit/tools_compact_context.test.js → Deleted (319 lines)
tests/unit/tools_compaction.test.js → Deleted (123 lines)
tests/unit/provider.test.js → Deleted (56 lines)
tests/unit/react_agent_checkpoint.test.js → Deleted (64 lines)
config.yaml → Added deepAgents.codingAgent config section

Partially Done ⚠️

prompts/SYSTEM_PROMPT.md → Delegation section updated but still references "sub-agent" terminology — needs cleanup
config.yaml → Has deepAgents config but need to verify turnHashWindow and turnBufferMax are removed

Missing ❌

src/tui/app.js → Streaming callback still uses old event types (text, reasoning, tool_start, tool_end, etc.) — not adapted for Deep Agents event model
index.js → Streaming pipeline not adapted for Deep Agents event model
Interruption → Still uses AbortController pattern, not Deep Agents native interruption
Loop detection → Need to verify turn hash tracking is fully removed
Compaction → Need to verify it is wired into Deep Agents flow
src/memory/prompts.js → Still has subAgent flag handling for deleted SUB_AGENT.md
src/provider/openai.js → Still has SUB_AGENT_TEMPERATURE env var handling
src/tools/terminal.js → processTracker may still be present — verify if needed for process tool
Docs (FLOWS.md, OVERVIEW.md, TUTORIAL.md, README.md) → May still reference old architecture

…gents)

feat: refactor-langgraph-to-deep-agents — OpenSpec proposal, design, …

c5167a7

…specs, and tasks

avoidwork self-assigned this Jul 1, 2026

avoidwork changed the title ~~feat: refactor-langgraph-to-deep-agents — OpenSpec proposal, design, specs, and tasks~~ feat: refactor to Deep Agents architecture Jul 1, 2026

avoidwork added 6 commits July 1, 2026 15:07

fix: resolve lint errors and formatting issues

a0257b8

- Remove unused variables from invokeAgent (signal, maxContextLength, maxTokens) - Remove unused namespace variable from stream loop - Auto-format index.js and prompts.test.js

fix: pass configurable thread_id to Deep Agents stream call

15b5473

The checkpointer requires thread_id in the configurable property to persist conversation state. Added configurable to streamOptions.

fix: use systemPrompt from agent instance, not message array

36886ef

Pass systemPrompt to createDeepAgentsOrchestrator factory. Remove manual SystemMessage prepending from invokeAgent.

fix: use both updates and messages stream modes for Deep Agents

ce945e9

- streamMode: ['updates', 'messages'] to get text chunks and tool events - Handle mode === 'messages' for text/reasoning output - Handle mode === 'updates' for tool_start/tool_end/tool_error events

fix: remove systemPrompt prepending — agent instance handles it

fcd91a7

avoidwork added 18 commits July 1, 2026 16:02

fix: remove unused namespace variable from stream loop

8ab3010

fix: update tests for deepagents middleware integration

d067be4

- Delete obsolete tests for removed compactContext and compaction tools - Update tool_index.test.js to reflect current tool registry (16 tools) - Update tool_registration.test.js assertions for removed tools

fix: pass permissions as [{ paths }] to createFilesystemMiddleware

7c28463

fix: resolve permission paths to absolute paths for deepagents middle…

0b5ba25

…ware

fix: filter out !node_modules exclusion from deepagents permissions

ff23ee3

fix: remove explicit middleware — deepagents adds it automatically

248194e

chore: remove unused invokeAgent and streamAgent functions from deepA…

1f2625d

…gents

fix: use agent.stream() with proper await and messages stream mode

7925a28

WIP

fd4b1b1

fix: wrap streaming callback text in structured event object

6c6fb87

The TUI's handleChat callback expects events with { type, text } shape, but callProvider was passing raw strings. This caused assistant response text to never render in the conversation panel.

docs: remove all remaining Sub Agent references

4753b10

- README.md: remove subAgent config entries, change 'specialized sub-agents' to 'specialized agents' - docs/OVERVIEW.md: remove sub-agent references, rephrase code identifiers - docs/FLOWS.md: change section titles and references

docs: remove all subAgent tool references

80eb388

- README.md: remove subAgent, subAgentLog, subAgentMessage from tools table - docs/FLOWS.md: remove subAgentLog from file dependencies - docs/TUTORIAL.md: remove subAgent tool mention

docs: update Built-in Tools section to reflect deepagents middleware

b2c7bf9

- Split tools into Deep Agents middleware (filesystem, memory, skills, summarization) - and built-in LangChain tools gated by sandbox permissions - Omitted compactContext as requested

chore: remove redundant tools replaced by deepagents middleware

8bdcbb5

Removed filesystem.js, memory.js, skills.js, compact_context.js, compaction.js and their tests — these are now handled by deepagents middleware.

refactor: rename SUB_AGENT.md to CODE_AGENT.md and rewrite prompt

6965522

- Delete prompts/COMPACTION.md - Rename SUB_AGENT.md → CODE_AGENT.md - Update deepAgents.js to load CODE_AGENT.md - Rewrite CODE_AGENT.md as a tight, deliverables-focused coding agent prompt

avoidwork added 2 commits July 2, 2026 10:46

fix: add subAgentsDir to memory schema and default config

6f68690

chore: remove unused toolsDir from memory schema

4547ebb

avoidwork changed the title ~~feat: refactor to Deep Agents architecture~~ refactor: replace LangGraph ReAct agent with Deep Agents architecture Jul 2, 2026

avoidwork force-pushed the feat/refactor-langgraph-to-deep-agents branch from bdedf4f to 4547ebb Compare July 2, 2026 15:29

avoidwork added 18 commits July 2, 2026 12:01

fix: expose full cwd in coreBackend by disabling virtualMode

d82f02a

chore: remove --cwd CLI arg and process.chdir from index.js

f90b7c2

docs: remove --cwd CLI arg from README

8bb9bfc

refactor: move system prompt loading into orchestrator, use deepagent…

8845761

…s memory parameter for AGENTS.md

refactor: make orchestrator fully self-contained, load system prompt …

b7393f5

…and AGENTS.md internally

feat: wire up deepagents skills middleware, discover skills in orches…

c0e2825

…trator

chore: format index.js

25b653f

refactor: move model and tools loading into orchestrator

1621813

feat: add sessionDir to config.memory, use it in orchestrator

10e6add

refactor: use join with config paths, remove fallbacks

c90870d

fix: rename sessionDir to sessionsDir in config, schema, and orchestr…

6044af5

…ator

fix: await buildToolConfig in orchestrator

32f1666

fix: restore providerConfig in index.js for TUI

26e4ab9

fix: remove duplicate providerName declaration

25ae5eb

fix: use config.memory.contextDir for PROFILE_DIR in profile.js

203aabe

feat: add summarization, todo, and patch middleware to coding subagent

958d0ac

fix: use subAgentsBackend for summarization middleware

1a1cc69

chore: remove unused imports from index.js

5845f33

avoidwork added 5 commits July 2, 2026 14:49

chore: remove compactContext tool and COMPACTION.md (built into deepa…

3e7bcdc

…gents)

docs: remove stale ReAct agent references from architecture docs

e3c0291

fix: remove unused event types from TUI streaming callbacks

ee6113a

fix: use native message event type in TUI streaming

e0b51cb

fix: close if block in TUI streaming callback

ed68282

avoidwork merged commit f8f13c5 into main Jul 2, 2026
2 checks passed

avoidwork deleted the feat/refactor-langgraph-to-deep-agents branch July 2, 2026 21:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: replace LangGraph ReAct agent with Deep Agents architecture#503

refactor: replace LangGraph ReAct agent with Deep Agents architecture#503
avoidwork merged 79 commits into
mainfrom
feat/refactor-langgraph-to-deep-agents

avoidwork commented Jul 1, 2026 •

edited

Loading

Uh oh!

avoidwork commented Jul 1, 2026

Uh oh!

avoidwork commented Jul 1, 2026

Uh oh!

avoidwork commented Jul 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

avoidwork commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Architecture

Testing

Related Issues

Uh oh!

avoidwork commented Jul 1, 2026

Audit Results

Uh oh!

avoidwork commented Jul 1, 2026

Deep Agents Overlap Analysis

Overlapping Tools (can be removed from madz)

Non-Overlapping Tools (unique to madz — keep)

Uh oh!

avoidwork commented Jul 2, 2026

Issue #502 Audit: Refactor LangGraph to Deep Agents

Completed ✅

Partially Done ⚠️

Missing ❌

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

avoidwork commented Jul 1, 2026 •

edited

Loading