1.1 Answer “why” first

Before reading DeepTutor’s source, read its positioning sentence (assets/README/README_CN.md:60-62):

DeepTutor is an agent-native learning workspace that integrates tutoring, problem-solving, quiz generation, research, visualization, and mastery practice in one extensible system. A unified runtime — Chat, Quiz, Research, Visualize, Solve, and Mastery Path run on the same agent loop; you switch the objective, not the engine, and context always flows with the learner.

This is not “another ChatGPT skin.” The starting point is:

1. Pain: existing AI learning products split “chat / quiz / solve / notes / knowledge base” into tools that do not talk to each other; every time the learner switches a mode they drop context; personalization cannot accumulate across tasks.
2. Insight: real lifelong tutoring needs not more entries, but the same agent runtime + one learning context that can flow.
3. Corollary: the product shape must be a “workspace,” not a “single chat window”; the architecture shape must be “pluggable capabilities,” not “each feature writes its own pipeline.”

flowchart LR
    P["Pain: learning tools isolated from each other
switch mode and drop context"] --> I["Insight: tutoring = the same brain
switch the objective, not the engine"]
    I --> C["Constraint: one UnifiedContext
+ three plugin layers (Tool / Capability / LoopCapability)"]
    C --> D["Corollary: multi-engine knowledge · three-layer memory · progressive tool disclosure
Partners · Subagent · Skills · sandbox"]

1.2 Three verifiable engineering claims

1.3 It is not the same species as the previous twenty in this series

The vast majority of this series answers “how to make AI write code / do tasks for me.” DeepTutor switched the question:

How to make AI accompany me in learning for a long time—the same brain, across chat, quizzes, research, visualization, mastery practice, and it still remembers who I am.

The only thing that matches the “change-of-axis” feeling is MiroFish (crowd simulation). DeepTutor’s axis is the education lifecycle, not a coding session, and not a social rehearsal.

2.1 Motive-evidence table

2.2 Product-manager view: what experience it is selling

🧠 One sentence: others are optimizing “how smart the tool call is”; DeepTutor is optimizing “in the learning lifecycle, can context keep following the person”—and welding that into orchestrator + UnifiedContext + three plugin layers.

3.1 Top-level shape

DeepTutor/
├── deeptutor/           # Python backend core (151,534 lines)
│   ├── runtime/         # Orchestrator · launcher · registry (incl. deferred_tools) · bootstrap
│   ├── core/            # UnifiedContext · StreamBus · agentic loop · tool/capability protocol
│   ├── agents/          # chat / research / question / visualize / math_animator / notebook / vision_solver
│   ├── capabilities/    # solve · mastery · subagent · obsidian · explore_context (LoopCapability layer)
│   ├── services/        # llm · rag · memory · skill · partners · subagent · mcp · sandbox · cli_apps …
│   ├── partners/        # IM bus + 16 channels
│   ├── book/            # Living Book independent engine (parallel to Orchestrator)
│   ├── knowledge/       # KB management face
│   ├── learning/        # mastery engine (mastery / spaced-repetition arithmetic)
│   ├── multi_user/      # identity · authorization · audit (14 modules)
│   ├── api/             # FastAPI 33 routers + unified WebSocket
│   └── tools/           # builtin tool implementations
├── deeptutor_cli/       # Typer CLI (5,147 lines)
├── web/                 # Next.js 16 frontend (108,133 lines TS/TSX)
├── AGENTS.md / SKILL.md # Agent-native manuals (constitution for the model)
└── pyproject.toml       # package name deeptutor · version 1.5.11

Sorted by package bulk (Python, approximate):

3.2 Stack in one sentence

• Backend: Python 3.11–3.13 · FastAPI · homemade agentic loop · 36 provider adapters · 5 RAG engines
• Frontend: Next.js 16 · React 19; the browser only connects to the frontend origin; /api/* and /ws/* are server-side forwarded by web/proxy.ts (the container only needs to expose 3782)
• Entries: deeptutor CLI (PyPI) · Web · Python SDK (DeepTutorApp) · Docker/GHCR
• Config: data/user/settings/*.json, intentionally ignore project-root .env (AGENTS.md:28-30)

3.3 Dependency direction (the compass when reading code)

flowchart TB
    CLI["deeptutor_cli"] --> ORCH["ChatOrchestrator"]
    WS["api/unified_ws
replayable turn protocol"] --> ORCH
    SDK["app.DeepTutorApp"] --> ORCH
    PART["Partners runtime"] --> ORCH
    ORCH --> CAPREG["CapabilityRegistry
7 top-level capabilities"]
    ORCH --> TOOLREG["ToolRegistry"]
    CAPREG --> CAP["BaseCapability.run"]
    CAP --> LOOP["AgentLoop (chat)
run_agentic_loop (deep)"]
    LOOP --> LCAP["LOOP_CAPABILITIES
mastery/solve/obsidian/subagent/explore"]
    LOOP --> TOOLS["BaseTool + deferred loader"]
    LOOP --> BUS["StreamBus"]
    TOOLS --> SBX["Sandbox three-grade isolation"]
    TOOLS --> MCP["MCP manager"]
    CAP --> CTX["UnifiedContext"]
    CTX --> MEM["MemoryStore L1/L2/L3"]
    CTX --> RAG["RAG pipelines ×5"]
    CTX --> SK["SkillService"]
    BOOK["BookEngine"] -.reuse StreamBus/Registry.-> BUS
    MU["multi_user authorization"] --> CTX

BookEngine is deliberately parallel to Orchestrator (book/__init__.py:5-9): it reuses StreamBus / Registry, but is not registered as a capability—what it produces is a book, not one streaming answer.

Part II · Mind map: how one constraint yields a dozen designs

5.1 Motive → constraint

If each learning mode wrote its own “search → think → answer” pipeline, modes could not share tools, memory, streaming UI. The constraint is:

A single action is a Tool; a multi-stage takeover of a turn is a Capability. (AGENTS.md:5-8, core/capability_protocol.py:1-8)

5.2 Rejected alternatives

5.3 Choice: three layers

Level 1 — Tools (core/tool_protocol.py:206 BaseTool). Builtin tools are registered in one BUILTIN_TOOL_TYPES table in tools/builtin/__init__.py:1562-1607, then split into two visibilities:

Level 2 — Capabilities (BaseCapability + CapabilityManifest), 7 of them, registered at runtime/bootstrap/builtin_capabilities.py:3-11:

Level 3 — LoopCapability, 5 of them, registered at capabilities/registry.py:13-19:

LOOP_CAPABILITIES: tuple[LoopCapability, ...] = (
    MasteryLoopCapability(),
    SolveLoopCapability(),
    ObsidianCapability(),
    SubagentCapability(),
    ExploreContextCapability(),
)

Each round, active_loop_capabilities(context) filters the active set in stable registration order (registry.py:22-25).

5.4 Two sharply different plugin semantics

capabilities/protocol.py further splits the third layer into two classes; the difference is “add or replace”:

Exclusivity is decided by class membership, not a per-instance switch: inheriting KnowledgeCapability is equivalent to setting exclusive_tools (protocol.py:98-105). The pipeline uses any_exclusive_capability_active() to decide whether to take the exclusive branch, and incidentally suppresses rag scaffolding (registry.py:28-37).

5.5 Dual identity: why mastery / solve are on both sides

This is the easiest place to misread:

• mastery_path / deep_solve are in the Level 2 table—when the user “selects a mode” in the UI they take this path; the capability itself owns the whole turn;
• MasteryLoopCapability / SolveLoopCapability are in the Level 3 table—when a mastery path / solve session is active on an ordinary chat turn, they only append a few tools and a system block to the chat loop.

In other words: after v1.4, a “mode” is no longer a separately started engine, but a different assembly of the same chat loop. That is the code meaning of the README sentence “switch the objective, not the engine.”

5.6 Cost

• A newcomer has to hold three plugin-layer semantics at once; AGENTS.md only wrote two; the third layer you only know by reading capabilities/registry.py;
• Exclusive strategy needs an exception rule: when selected alongside a LlamaIndex KB, rag / kb_files must coexist (issue #650, tool_composition.py:59-61,132-138).

6.1 Motive

Without a unified context object, CLI args, WebSocket frames, Partner inbound messages would each assemble their own prompt; personalization and permissions would necessarily drift.

6.2 Choice: one dataclass flowing through the whole chain

UnifiedContext (core/context.py:34-84) carries:

6.3 Cost

metadata is an intentional “extension-seam trash can”: protocol-stable fields go into the dataclass; experimental fields go into metadata. Flexible, but cross-capability conventions are maintained by comments (e.g. subagent uses _min_loop_rounds to raise the loop budget, capabilities/subagent/capability.py:56-60).

Part III · Implementation: from constraint to code

7.1 Entry convergence

ChatOrchestrator.handle (runtime/orchestrator.py:36-114):

1. Fill session_id
2. Resolve active_capability or "chat"
3. Take the implementation from CapabilityRegistry; if missing, emit one error event with turn_terminal and finish normally (orchestrator.py:49-67)
4. Build a StreamBus, register it in the global table by turn_id (for WS reconnect subscribe), run capability.run(context, bus) in the background
5. Externally async for fanout StreamEvent
6. In finally always emit DONE and close(), unregister the bus
7. After end, emit CAPABILITY_COMPLETE on the global EventBus (orchestrator.py:116-134)

sequenceDiagram
    participant U as CLI/WS/SDK/Partner
    participant O as ChatOrchestrator
    participant R as CapabilityRegistry
    participant C as Capability
    participant B as StreamBus
    U->>O: handle(UnifiedContext)
    O->>R: get(cap_name)
    O->>B: new StreamBus + register_bus(turn_id)
    O->>C: run(context, bus)
    C-->>B: stage / content / tool / sources
    B-->>U: StreamEvent…
    O->>B: DONE + close + unregister
    O->>O: publish CAPABILITY_COMPLETE

7.2 Why this is load-bearing

CLI deeptutor run, Web unified WS, Partner inbound, SDK calls are ultimately the same face. Switch UI, do not switch behavior—exactly what the architecture diagram in AGENTS.md:12-26 wants to nail.

7.3 Cost

Orchestrator is extremely thin (146 lines); complexity sinks into each Capability / Pipeline. The gain is the entry is always readable; the cost is “the real product logic” is scattered in agents/* and capabilities/*; the reader easily gets lost in the 1,563-line agentic_pipeline.py.

8.1 Track A — Chat AgentLoop: “this round called no tools = the answer is done”

File: agents/chat/agent_loop.py (module comment 1-24, AgentLoop @ 171, run @ 196).

Rules extremely simple:

• Has tool calls → this round’s text is narration (preface of tool work); the loop continues;
• No tool calls → this round’s text is the final answer, finish;
• Every round’s text is streamed to the user as it is generated; at round end, call_role (narration / finish) tells the frontend how to render—no need to guess mid-stream where the text is going (agent_loop.py:20-24);
• ask_user can pause and resume inside the same turn;
• After the exploration budget is exhausted, enter at most 3 settlement rounds (MAX_SETTLEMENT_ROUNDS = 3 @ 64); if still not stopping, _forced_finish (agent_loop.py:492: turn tools off to force the model to close). Total cap is exploration + 4 (the comment at agent_loop.py:60-63 computes it clearly).

Two real fallback details worth copying away:

1. Truncation continue-write: when the provider stops because of a length cap (finish_reason ∈ {length, max_tokens, max_output_tokens}, agent_loop.py:65,73-76), do not treat it as “answered”; leave the visible prefix in the protocol and continue writing;
2. Empty-finish nudge: when finish-round text is empty, first send one nudge for the model to restate, only once (nudged_empty_finish, agent_loop.py:361-386).

ChatCapability is only a thin shell (27 lines); what actually works is AgenticChatPipeline (run @ agentic_pipeline.py:326) + AgentLoop.

Isomorphic with Claude Code / Codex “the model decides whether to stop,” but DeepTutor defines “stop” as the empty set of tool calls, not a special terminate tool—more natural for tutoring: once it has explained clearly, it should stop.

8.2 Track B — run_agentic_loop: a Label-driven protocol state machine

File: core/agentic/loop.py (run_agentic_loop @ 173).

The model must give a double-backtick-wrapped label on the first line of every round (core/agentic/labels.py:3-10). LabelProtocol (loop.py:39-64) declares five sets: allowed / terminal / intermediate / final / tool_label.

The most careful design point: final is orthogonal to terminal—a terminating label need not flow body text (e.g. REPLAN only bubbles the text to the upper layer); an intermediate label can also flow body text (e.g. chat’s PAUSE: narrate to the user without ending the turn) (loop.py:48-56).

The loop body is capability-agnostic; capability-related behavior is all delegated to the LoopHost Protocol (loop.py:79-170): context-window clip, per-round trace metadata, parallel tool dispatch, pause handling, terminate check, protocol-violation repair copy, budget-exhausted forced close. Three of the hooks use getattr to probe existence (before_iteration / on_intermediate); an old host that does not write them will not break—a very restrained extension method.

The label parser itself is also anti-fragile (labels.py:34-95): tolerate one-/three-backtick variants, zero-width-character prefixes, missing separators, and a “bare label + separator” fallback; if more than 64 characters have not matched, fall to UNKNOWN.

Research / Question / Solve take this track—they need explicit stage labels (THINK / TOOL / FINISH / APPEND / REPLAN); they cannot judge stage only by “whether there are tools.”

8.3 Motive → choice → cost

The repo did not force-merge for “architecture looks pretty”—the tutoring main path wants smoothness; the deep-research path wants strictness.

9.1 The problem

Stuffing the full tool schema to the model every round: costs tokens, induces the model to call randomly, and makes Partner scenes unable to do permission subtraction.

9.2 Choice

ToolMountFlags + compose_enabled_tools (agents/_shared/tool_composition.py:82-99 and 101-160). The conditional-mount table is the single source of truth (_CONDITIONAL_MOUNT_FLAGS, tool_composition.py:41-57):

Assembly order (tool_composition.py:117-127): ① user toggles (filtered by optional_whitelist) → ② conditional auto-mount → ③ activated capability’s owned tools → ④ always-on tools (write_memory / web_fetch / github / ask_user / cron).

Then stack three knobs Partner uses (tool_composition.py:140-155): builtin_whitelist (only subtract, never add), forced (unconditional append, bypass allowlist and situational gate), suppressed (final remove). AUTO_MOUNTED_TOOLS is derived directly from CONFIGURABLE_BUILTIN_TOOL_NAMES (tool_composition.py:39), so “what the settings page shows” and “what the pipeline mounts” cannot drift.

9.3 Contrast with this series

DeepTutor’s special point: the tool surface is a function of the learning situation (whether there is a KB / notes / skills / sandbox), not a pure permission function.

10.1 Motive and measured reason

Even with situational flags, MCP servers + 101 CLI Apps will explode the schema surface. runtime/registry/deferred_tools.py:1-16 writes the motive bluntly:

Keep the always-on schema surface small; this measurably improves tool selection on weak models, while every already-connected tool is only one cheap call away.

10.2 Mechanism

1. Tools marked BaseTool.deferred (by default includes all MCP tools) do not enter this round’s initial tool table;
2. The system prompt only carries one summary line (render_deferred_tools_manifest);
3. When the model needs them, builtin load_tools reports exact names;
4. DeferredToolLoader appends the full schema into the live tool_schemas list—run_agentic_loop rereads that list every round, so the tool is immediately callable;
5. Loaded names are persisted by chat session; subsequent turns carry them from the start.

CLI App tools get special handling: each App is its own provider and has only one tool; writing a small heading per provider would waste tokens, so they share one ("cli","") group and write the provider id inline (deferred_tools.py:36-40).

flowchart LR
    A["MCP / CLI App tools
deferred=True"] --> B["system prompt: one summary line"]
    B --> C{model judges it needs them?}
    C -- no --> D["schema surface stays small
weak models select more accurately"]
    C -- yes --> E["load_tools(exact names)"]
    E --> F["schema appended into the live list"]
    F --> G["callable next round"]
    G --> H["names persisted by session"]

10.3 Five-beat

11.1 36 providers are a “capability-bit” table

The PROVIDERS tuple in services/provider_registry.py:118 has 36 ProviderSpecs, of which 11 are gateways (gateway first; order is match priority, provider_registry.py:7,115-118):

The key is the fields of ProviderSpec (provider_registry.py:19-56)—it is not “name + URL,” but per-vendor capability bits: supports_prompt_caching / supports_stream_options / supports_max_completion_tokens / strip_model_prefix / is_oauth / is_local / thinking_style / reasoning_model_patterns / model_overrides. Adding one provider = adding one spec; “env vars, config match, status display are all derived from this” (provider_registry.py:3-5).

There is also an alias table PROVIDER_ALIASES (:77) that normalizes azure / google / claude / openai-compatible / github-copilot / lm-studio / atlas … to canonical names—whatever the user fills in can land.

11.2 Graceful degrade: error-classifier-driven retry

services/llm/request_compat.py:1 titles it in one sentence: “provider-error classifiers used by retry and graceful-degradation paths.” It lowercases the provider’s message body then does substring match, judging three kinds of unsupported:

• is_stream_options_unsupported (stream_options / unknown parameter / extra inputs are not permitted …)
• is_tool_schema_unsupported (→ trigger DSML fallback, next section)
• is_image_input_unsupported (→ multimodal degrade; llm/multimodal.py:327 comment says degrade must persist across iterations, otherwise images would be resent repeatedly)

This “first send optimistically, if refused then precisely degrade and remember” ages better than pre-enumerating every vendor’s quirks.

11.3 DSML: when the provider will not do native tool calling

agents/chat/dsml_tool_calls.py:1-22 is the most concrete “fallback” case I have seen in this series:

Some DeepSeek deployments (especially local / source-started OpenAI-compatible endpoints) do not advertise function calling, so they write tool calls as markup into the content channel, of the form:

<｜｜DSML｜｜tool_calls>
  <｜｜DSML｜｜invoke name="exec">
    <｜｜DSML｜｜parameter name="command" string="true">python -c "..."</｜｜DSML｜｜parameter>
  </｜｜DSML｜｜invoke>
</｜｜DSML｜｜tool_calls>

What happens if you do not parse: this markup streams to the user as the final answer, and the tool never ran (the repo hung issue #666 directly).

The answer is restrained: extract_dsml_tool_calls is a pure function (no I/O, no LLM); tag-prefix matching is loose (<[^>]*?invoke\s+name="); it only depends on the stable invoke name / parameter name structure—does not bet on the exact bytes of those full-width special tokens. Meanwhile DSMLStreamFilter (dsml_tool_calls.py:62) at the streaming stage filters the markup out of the user-visible channel, while the original text is still fed back to the model.

InlineThinkFilter (agent_loop.py:83-95) is its sister design, solving the other half of the same class of problem: some providers write reasoning in content wrapped in <think>, so split in place while streaming—“user-visible content” is fixed once, clean everywhere downstream (live bubble, persisted messages, the loop’s finish judgment), while the tagged original is still fed back to the model.

11.4 Cost

String-matching provider messages is inherently fragile (change the copy and you miss); the capability-bit table has to be maintained by hand; DSML only covers DeepSeek’s dialect; if another vendor invents a new dialect you have to add another branch.

12.1 Layout

services/memory/paths.py:1-8:

trace/<surface>/<YYYY-MM-DD>.jsonl        # L1 append-write
L2/<surface>.md                           # L2 per-surface summary
L3/{recent,profile,scope,preferences}.md  # L3 cross-surface
backup/<timestamp>/...                    # v1 migration archive

Seven surfaces (paths.py:47-56): chat notebook quiz kb book partner cowriter.

12.2 Facade

MemoryStore (store.py:68) is a stateless facade (process-level singleton-safe), write-locked by path:

• emit → L1
• update_l2 / update_l3 → consolidator
• read_l3_concat → for the read_memory tool (when there is no content, return an explicit hint string rather than empty, store.py:53-55)
• overwrite_doc / delete_entry → humans edit directly in the workbench
• apply_ops_payload → “preview → apply” two-step flow (store.py:165-193)

12.3 ⚠️ Correction: who can actually write preferences.md

The previous edition was wrong: it said “preferences must be human-editable; the model cannot secretly rewrite.” After checking source, the accurate statement is:

1. preferences.md does not enter auto-synthesis—update_l3 explicitly refuses (store.py:153-154: raise ValueError("preferences.md is not auto-consolidated"));
2. But the model can write, only through a narrow gate: write_preference (store.py:194-250); the comment states “the write_memory tool is the only caller; trace_id is injected by the runtime”;
3. This narrow gate comes with two protections: op is only add / edit; add is idempotent—duplicate content is not appended again, but reports the already-existing entry (detail="duplicate"). The reason is in the comment: Guided Learning turns are highly tool-driven and long; the model will re-send the same write_memory across turns (issue #647), and preferences.md has no auto-synthesis to clean duplicates.

So the real design intent is not “do not let the model write,” but “let the model write only through a narrow gate with provenance and idempotent protection,” and this class of conclusions is never rewritten by auto-summary.

12.4 The precise shape of footnote provenance

L2/L3 is not free prose, but Markdown with strict invariants (document.py:1-30):

## <section>
- <text> [^1][^2] <!--m_xxx-->

---

[^1]: notebook:abc
[^2]: chat:def

Three details easy to miss:

• Footnote labels are integers, assigned by first-appearance order in the full-text bullet stream; two citations of the same source share a label, so the rendered view has no duplicate footnote lines;
• Entry ids hide in an HTML comment <!--m_xxx--> at the bullet tail; they survive round-trip, for audit / dedup line views and DELETE /entry/{id};
• The parser also accepts the old format ([^m_xxx]: ref1, ref2); next save migrates—existing documents will not become unreadable on upgrade.

12.5 Four user-visible synthesis modes

The previous edition only said “LLM consolidator.” There are actually four (consolidator/modes/__init__.py:1-10):

Concurrency cap also has a clear contract: the same (layer, key) at most one active run; a second throws RunBusyError (consolidator/runs.py:17,174-175).

12.6 Partner memory’s privilege-crossing seam

Partner runtime can use memory_path_service_override (paths.py:27-44) so read_memory / write_memory read the owner’s memory, while other services (rag / skills / notebooks) stay in the partner scope. Without this, the IM companion would forever “not know you.” This is fine work at the intersection of multi-tenant × persona companionship.

12.7 Five-beat

13.1 Five engines

Engine roster in services/rag/factory.py:216-256:

Supporting trio: unified RAGPipeline Protocol (pipelines/base.py:17-37), per-engine engine_preflight (preflight.py:195, never throws), embedding_signature (:43-47 explicitly says a graph-engine mismatch will fail silently, so it needs its own stamp).

13.2 “Knowledge base” is a product-semantics slot, not a data structure

A selected KB can be three heterogeneous objects:

Putting “materials” and “a consultable expert process” into the same slot is the key product decision that distinguishes DeepTutor from a “RAG chatbot.”

14.1 The same sentence, said three times

14.2 Why this is a copy-worthy dividing line

Most Agent projects swing between “let the model improvise” and “hardcode the pipeline.” DeepTutor gives an operable cut:

• The deterministic part sinks into tools: how mastery scores are computed, when spaced repetition is due, which plan step counts as done, how many replans remain—these are arithmetic and a state machine; the model cannot compute them accurately and should not;
• The judgment part is left to the loop: what to teach, how to ask, which step to solve first, whether to look up materials—these are pedagogy and reasoning.

Thus learning/ (4.7k-line mastery engine) is a pure arithmetic module; mastery/tools.py is only the seam between it and the chat loop.

14.3 Contrast with this series

The commonality is the same sentence: whatever can be computed accurately, do not let the model free-heart-certify.

15.1 Two very concrete failure observations

capabilities/explore_context/capability.py:1-30 writes the motive as two bug-level observations:

1. Persona contamination: the chat loop melts “understand the attachment” and “answer the user” into one loop. When the attachment is a conversation log between the user and another AI, the model in the same context reads those ## Assistant turns and then speaks in that agent’s first-person voice. Splitting understanding into an objective (third-person) pre-investigation structurally kills this confusion.
2. Weak models simply do not read: under native tool calling, weak models often never actively call read_source. So let a dedicated pre-pass own the read right, and completely remove that tool from the answer loop—the investigation is forced to happen in front, rather than being skipped.

15.2 Mechanism

• Activation condition: this turn carries any readable (non-image) attachment source—documents, notebook entries, book chapters, quiz-bank entries, or cited session history (the motive case);
• Uses the optional pre_loop hook (capabilities/protocol.py:34-53), runs before the answer loop’s first LLM call;
• It itself is a small agentic loop (from explore_context/explorer.py:149), using read_source to read what should be read;
• The produced objective investigation folds into the loop’s user-message seed (alongside KB seeds, agent_loop.py:205-217);
• It does not own any of the answer loop’s tools, does not contribute a system block—almost invisible.

flowchart LR
    A["turn carries readable attachments
(especially: another AI’s conversation log)"] --> B["ExploreContext pre_loop
read-only · objective · third person"]
    B --> C["investigation conclusion folds into the user-message seed"]
    C --> D["answer loop: no longer has read_source
and will not contaminate into another agent"]

15.3 Five-beat

16.1 What it is

Partners (formerly TutorBot, renamed in v1.4.3 and put on a “production-grade IM pipeline”) = a persistent companion with a Soul persona, hanging IM channels, running on the same chat loop.

16.2 Channel discovery: zero-import scan + diagnosable failure

partners/channels/registry.py:

• discover_channel_names() uses pkgutil to scan the package, zero import, list builtin channel names (:18-26), excluding base / manager / registry;
• load_channel_class() imports the module and takes the first BaseChannel subclass (:29-38);
• External plugins go through entry_points(group="deeptutor.partners.channels"); builtin names take priority; plugins cannot shadow builtins (:55-61);
• discover_all_with_errors() additionally returns an errors dict—“why isn’t X in the UI” is diagnosable, rather than silently dropping a channel (:63-78).

The baseline has 16 builtin channel modules: telegram discord slack feishu wecom weixin dingtalk qq napcat mochat whatsapp matrix mattermost msteams zulip email.

16.3 Relation to the main product

A Partner turn still constructs UnifiedContext and goes through Orchestrator, but three places are tightened:

• allowed_builtin_tools does subtraction (the owner can ban some builtins);
• Force-mount the PARTNER_BUILTIN_TOOL_NAMES three-piece and suppress chat’s read_memory / write_memory (agentic_pipeline.py:64,624-625)—these three are forced, not owner-configurable (builtin/__init__.py:1601-1607);
• Memory path can override to the owner scope (section 12.6).

16.4 Cost

Many optional deps (pip install deeptutor[partners]; Matrix E2EE also needs libolm); each channel’s Markdown / streaming / media semantics have to be ground separately (Telegram has to do Markdown→HTML itself, telegram.py:110). Product breadth is exchanged for ops and test-matrix bloat.

17.1 Reverse the host relationship

In this series Open Design “treats others’ CLIs as the engine”; DeepTutor plugs in differently:

The learning Agent is the host; Claude Code / Codex / Gemini / Kimi / opencode / MiMo are consulted sub-agents, and the entry is the “knowledge-base slot.”

SubagentCapability (capabilities/subagent/capability.py:1-13,32-44):

• Activates when the selected KB is a connected subagent (is_active → connection_for_turn(context) is not None);
• As a KnowledgeCapability exclusive turn: only consult_subagent + ask_user fallback;
• Connection info (which backend, working directory), per-backend config, in-turn budget and session are all server-injected; “the model never provides them”—prevent privilege-crossing random working directories;
• Uses _min_loop_rounds = budget + 2 to raise the loop budget, guaranteeing there are still rounds to write the answer after the last consult (capability.py:25-29,56-60).

17.2 Backend registry and cross-turn continuation

services/subagent/registry.py:24-35 seven backends: ClaudeCode Codex Gemini Kimi Opencode Mimo Partner. The local_cli flag separates “local probe” from “connect from one’s own list”—detect_all() only probes CLIs, and one-by-one failure does not affect the whole (exceptions degrade to available=False + detail, registry.py:51-77).

Cross-turn, the session registry continues the same local agent session (capability.py:88-95: on first consult, seed session id from the cross-turn registry), so sidebar and in-chat consults share context.

Each consult_subagent call hands one question to the local CLI, and forwards its native event stream out through the dispatcher’s event_sink, so the sidebar can see that agent’s real intermediate steps (capabilities/subagent/tools.py:1-8). Multimodal images are only forwarded when the user explicitly turned on forward_images for that backend (capability.py:96-100).

17.3 Why this deserves “signature move”

The coding-agent series teaches “how to build an engine”; DeepTutor demonstrates “how an education product treats an already-there engine as a tool”—isomorphic with Open Design’s socket philosophy, but the socket is plugged into the knowledge-base slot, not a step of a design pipeline.

18.1 MCP: one dedicated connection task per server

services/mcp/manager.py:1-25 tells a pit many people have stepped in: DeepTutor’s chat is a per-turn task in the same event loop, while an MCP session must be opened and closed inside the same task (the SDK’s anyio cancel scope is task-bound). So each server gets a dedicated connection task, end-to-end holding its own AsyncExitStack:

connect → enter transport/session inside that task → publish adapter →
wait for shutdown event → exit stack inside the same task

ensure_started() is lazy (the first turn pays the connection cost, with a per-server timeout cap), then cheap; reload() diffs the persisted config. The module also has oauth.py / secrets.py (credentials moved out of sandbox-reachable range, v1.5.7) / catalog/ / session_state.py / pageindex_server.py—the PageIndex engine itself is exposed to the model through MCP.

MCP tools default deferred (Chapter 10), so connecting a pile of servers will not explode the schema surface.

18.2 CLI Apps: 101, pinned to one reviewed commit

services/cli_apps/:

• The catalog is a shipped-with-the-package snapshot vendor/catalog.json (catalog.py:31), not fetched from the net at runtime—“one upstream failure should not take the whole catalog down” (catalog.py:3-9);
• Baseline snapshot: 101 apps, from HKUDS/CLI-Anything, commit = bc536c9 (2026-07-09), aggregating two registries (registry.json + public_registry.json);
• If the snapshot has no pinned commit, refuse to offer install (catalog.py:57: refusing to offer installs)—supply-chain discipline written into code;
• Each app is its own provider and has only one tool, hence shares the cli group in the deferred manifest (section 10.2).

18.3 Sandbox: three backends, two isolation levels, one policy gate

services/sandbox/backends.py:1-16 three backends, each honestly reporting the isolation level it actually provides:

services/sandbox/service.py:1-13 turns these three grades into product policy:

• exec_capability_available() → decides a skill’s requires.sandbox gate;
• isolation_level() → policy gate: SYSTEM open to everyone, APPLICATION admin-only;
• run() → execute, constrained by per-user quota (UserExecQuota / QuotaExceeded in quota.py).

Contrast with this series: Codex is Seatbelt/Landlock/Windows Token three-platform OS fences; nanobot uses bwrap; DeepTutor’s distinctive move is turning “isolation strength” into a queryable return value and using it for permission grading—rather than pretending every deploy is equally safe.

18.4 Codex OAuth: use your own ChatGPT subscription

services/codex_auth/ (service.py:1 “Codex OAuth orchestration and managed model-catalog integration”) implements the capability from v1.5.5: log into Codex with a ChatGPT plan; from v1.5.10 each account logs into its own Codex; from v1.5.6 supports remote login behind an SSH tunnel. The corresponding provider side is openai_codex (is_oauth=True, section 11.1).

Product meaning: the learner need not buy another API quota—this kind of “plug into the user’s already-there subscription” design is especially important in education scenes.

19.1 One endpoint, eleven message types

api/routers/unified_ws.py:1-30: a single /api/v1/ws, for “turn-based execution and replayable streaming.” Client message types:

Three things carry “restart-safe”: events carry sequence numbers and can replay after_seq; the bus is registered by turn_id and can be re-subscribed (section 7.1); stale state self-heals. README v1.4.0’s “restart-safe turn runtime” lands here.

19.2 pause / resume is first-class

ask_user is not “end this round, wait for the next”; it is same-turn pause: the loop stops in place; after submit_user_reply comes back it continues with an ask_user_resolved instruction (agentic_pipeline.py:873-911), and flattens the answer into a tool message back into the conversation. For a tutoring product this is a necessity—“the teacher asks you one question, you answer, class continues” should not drop context.

19.3 Multi-user: a 14-module authorization matrix

multi_user/ is not merely “optional multi-user”; it is a per-resource authorization matrix:

Partner authorization semantics are written clearly: Partner stays admin-managed (CRUD routes admin-gated); a grant only lets the user see and consult a specified partner (grants.py:22-28). Additionally from v1.4.10 non-admin MCP tools are denied by default.

19.4 Cost

The protocol surface is large (11 message types + 33 REST routers); frontend and backend have to maintain semantics together; multi-user is an optional path; personal-workspace mindset and multi-tenant mindset coexist; when reading code you must constantly ask “whose PathService is this running on.”

20.1 Skills: progressive disclosure + two-layer shadow

services/skill/service.py:8-20 states two things clearly:

1. Progressive disclosure: skills never stuff the whole file into the system prompt—the prompt only has a “one skill, one line” manifest; when the model matches a task it uses read_skill to take the full text; the exception is skills with always: true in frontmatter, whose body is eager-injected (for “house rules” that must take effect every turn);
2. Two layers, user shadows builtin: deeptutor/skills/builtin/ ships with the product, runtime read-only; data/user/workspace/skills/ is created by API. Same name, user layer shadows builtin.

The skill-pack structure is SKILL.md + optional references/ (when the execution sandbox is ready there will also be scripts/); read_skill has a hard cap to prevent huge reference files flooding context (service.py:74), and also path-escape checks (service.py:182). Community skills can be installed from ClawHub (v1.4.4, with a safety gate).

Contrast: Claude Code’s skills, Open Design’s 20-layer prompt banding, Reasonix’s stable prefix—all three are doing the same thing: move “maybe useful” knowledge out of always-on context. DeepTutor did this twice on this line (skills and deferred tools).

20.2 BookEngine: a parallel second runtime

book/__init__.py:5-9: an independent runtime that compiles chat history / notes / knowledge bases / intent into a structured, chunked, interactive “living book”; parallel to ChatOrchestrator, reusing ToolRegistry / CapabilityRegistry / StreamBus.

Stages: Ideation → SourceExplorer → Spine (spine_synthesizer has already replaced the old SpineAgent) → PagePlanner → BookCompiler. The model layer is Pydantic Book / Spine / Chapter / Page / Block / Progress (book/models.py); the compiler is deliberately isolated from the orchestrator (compiler.py:16).

Why not make it a Capability? Because its product is an asset that can be reread, with progress, not one streaming answer—lifecycle, storage (book/storage.py), failure recovery are all different.

20.3 Other load-bearing walls (one-sentence file)

Part IV · Taste and bounds

24.1 🔍 Source pointer table

24.2 Local reproduction (read-only analysis)

cd "参考项目/DeepTutor"
git rev-parse --short HEAD   # expect 456f9c2
git describe --tags          # expect v1.5.11

# re-check several key numbers in this lecture
find deeptutor -name '*.py' -print0 | xargs -0 wc -l | tail -1        # 151534
python3 -c "import re,json;d=json.load(open('deeptutor/services/cli_apps/vendor/catalog.json'));print(len(d['apps']), d['meta']['commit'])"
python3 -c "import re;s=open('deeptutor/services/provider_registry.py').read();b=s[s.index('PROVIDERS: tuple'):];print(len(re.findall(r'ProviderSpec\(\s*name=\"',b)))"   # 36
ls deeptutor/partners/channels/*.py | wc -l                            # 20 (including base/manager/registry/__init__ → 16 channels)

If you actually want to run it (not required for analysis):

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
( cd web && npm ci --legacy-peer-deps )
deeptutor init && deeptutor start --dev

24.3 Handoff to other documents in this series

• Care about “do not write the main loop; treat others’ CLIs as the engine” → contrast Open Design source analysis with this lecture’s Chapter 17 (host-relationship reverse)
• Care about “progressive disclosure / cache-friendly” → contrast DeepSeek-Reasonix’s use_capability with this lecture’s Chapters 10 and 20
• Care about “do not trust the model’s self-report” → contrast MiMo Code’s Goal judge with this lecture’s Chapters 14 and 15
• Care about “sandbox and permissions” → contrast openai-codex’s three-platform fence with this lecture’s section 18.3
• Care about “change-of-axis products” → contrast MiroFish: one switched to social simulation, one switched to lifelong learning