honcho/agentic_fde.md

Agentic FDE: Self-Adapting Honcho

Vision

The software market is bifurcating: massive enterprise vs solopreneur vibe-coders. Enterprise requires human FDEs; vibe-coders won't pay for human help but also won't pay for one-size-fits-all SaaS. The solution: make Honcho itself an "Agentic FDE" that adapts to each developer's use case.

Honcho observes usage patterns, engages in meta-cognition about developer goals, and adapts its behavior accordingly. A companion app needs emotional memory extraction and biographical recall. A coding agent needs preference/constraint extraction and should ignore stack traces. An email ingestion pipeline needs RAG, not conversation memory.

The same primitives (workspaces, peers, sessions, messages, documents) can achieve any memory pattern - but the prompts and retrieval strategies must adapt.

Core Principles

1. Stable API, stable schema - Honcho adapts its behavior, not its interface
2. Developer feedback is highest priority - Observed patterns can be overridden
3. Two adaptation questions:
   • How should I handle the next marginal message? (deriver)
   • How should I handle the next marginal .chat query? (dialectic)
4. Constraints: No touching deletion endpoints, workspace isolation, or the core reasoning model

The 5-Phase Plan

Phase 1: Instrumentation ✅

Goal: Log dialectic interactions so the dreamer can analyze performance.

Built:

• DialecticTrace model: workspace, session, observer, observed, query, retrieved_doc_ids, tool_calls, response, reasoning_level, duration, tokens, timestamps
• CRUD operations: create_dialectic_trace(), get_dialectic_traces(), get_dialectic_trace_stats()
• Abstention detection via regex patterns
• Integration: traces written at end of DialecticAgent._log_response_metrics()

Files: src/models.py, src/crud/dialectic_trace.py, src/dialectic/core.py, tests/test_dialectic_trace.py

Phase 2: Prompt Injection Points ✅

Goal: Enable workspace-level prompt customization without changing default behavior.

Built:

• WorkspaceAgentConfig schema with deriver_rules and dialectic_rules fields
• Storage in workspace.metadata["_agent_config"]
• CRUD helpers: get_workspace_agent_config(), set_workspace_agent_config()
• Deriver prompt injection: custom_rules parameter in minimal_deriver_prompt()
• Dialectic prompt injection: custom_rules parameter in agent_system_prompt()
• Config threading through deriver and dialectic paths

Files: src/schemas.py, src/crud/workspace.py, src/deriver/prompts.py, src/deriver/deriver.py, src/dialectic/prompts.py, src/dialectic/core.py, src/dialectic/chat.py, tests/test_workspace_agent_config.py

Phase 3: Meta-Cognitive Dreamer ✅

Goal: Dreamer analyzes logs and generates configuration suggestions.

Built:

• DreamType.INTROSPECTION enum value
• IntrospectionSignals, IntrospectionSuggestion, IntrospectionReport schemas
• gather_introspection_context() - collects dialectic stats, observation counts, peer/session patterns
• build_introspection_prompt() - formats signals for LLM analysis
• run_introspection() - calls LLM, parses structured suggestions
• store_introspection_report() - saves reports as documents in _system/_introspection collection
• get_latest_introspection_report() - retrieves most recent report
• Wired into DreamType.INTROSPECTION in orchestrator

Files: src/schemas.py, src/dreamer/introspection.py, src/dreamer/orchestrator.py, tests/test_introspection.py

Phase 4: Developer Feedback Channel ✅

Goal: Developers can talk to Honcho about Honcho.

Built:

• POST /workspaces/{id}/feedback endpoint
• FeedbackRequest, ConfigChange, FeedbackResponse schemas
• process_feedback() - handles natural language feedback
• build_feedback_prompt() - formats context for LLM
• Interview mode: empty config + greeting triggers onboarding questions
• Incremental updates: preserves existing rules when adding new ones
• Introspection context: optionally includes latest report
• Uses settings.DREAM for LLM calls (not billed as dialectic)

Files: src/schemas.py, src/feedback.py, src/routers/workspaces.py, src/dreamer/introspection.py, tests/test_feedback.py

Phase 5: Closed Loop (Future)

Goal: Automatic adaptation with developer oversight.

To build:

• Dreamer introspection generates draft config changes
• Surfaces to developer via webhook or dashboard
• Developer approves/rejects/modifies
• Approved changes written to config
• Optional: workspace.meta.auto_adapt = true for brave workspaces

Summary Statistics

Phase	Lines Added	Test Coverage
1	~500	376 lines (13 tests)
2	~200	246 lines (15 tests)
3	~500	423 lines (10 tests)
4	~350	514 lines (23 tests)
Total	~2,950	1,559 lines (61 tests)

Testing

Unit Tests

• Run full test suite: uv run pytest tests/
• Test Phase 1: Create a dialectic query, verify trace is logged
• Test Phase 2: Set workspace agent config, verify rules appear in prompts
• Test Phase 3: Trigger introspection dream, verify report generated
• Test Phase 4: Submit feedback, verify config updated
• Test interview flow: New workspace + greeting triggers questions
• Test incremental updates: Existing rules preserved when adding new ones

Unified End-to-End Tests

New actions added to the unified test system (tests/unified/):

Action	Description
set_agent_config	Set custom deriver_rules and/or dialectic_rules
submit_feedback	Submit natural language feedback to configure Honcho
trigger_introspection	Trigger meta-cognitive introspection dream
query_introspection	Query the latest introspection report

Test cases for agentic FDE:

• agentic_fde_custom_deriver_rules.json - Verifies custom deriver rules filter observation extraction
• agentic_fde_custom_dialectic_rules.json - Verifies custom dialectic rules change response format
• agentic_fde_feedback_updates_config.json - Verifies feedback endpoint updates configuration

Run unified tests:

python -m tests.unified.run --test-dir tests/unified/test_cases

API Endpoints

New endpoints added:

Endpoint	Method	Description
/workspaces/{id}/feedback	POST	Developer feedback channel
/workspaces/{id}/introspection	GET	Get latest introspection report