agentram 0.1.5 → 0.1.7

package/README.md

@@ -358,12 +358,20 @@ Minimum usage pattern:
 
 AgentRAM can bind multiple coding model endpoints and let Claude Code or MCP clients orchestrate them in parallel. This keeps the `free-code` style command registry, but adds project RAM, Goal Stack, and multi-agent model routing.
 
-Bind models:
-
-```bash
-agentram bind-model claude claude-3-5-sonnet-latest --role reviewer --api-key-env ANTHROPIC_API_KEY
-agentram bind-model openai-compatible qwen2.5-coder --role coder --base-url http://localhost:8000/v1 --api-key-env OPENAI_API_KEY
-```
+Bind models:
+
+```bash
+agentram bind-model claude-subagent agentram-reviewer --role reviewer
+agentram bind-model claude claude-3-5-sonnet-latest --role reviewer --api-key-env ANTHROPIC_API_KEY
+agentram bind-model openai-compatible qwen2.5-coder --role coder --base-url http://localhost:8000/v1 --api-key-env OPENAI_API_KEY
+```
+
+Claude Code subagent endpoint uses your local Claude CLI entrypoint. `model` is the subagent name from `.claude/agents`, for example `agentram-reviewer` or `agentram-planner`. Default command is `claude -p`. Override command when needed:
+
+```bash
+set AGENTRAM_CLAUDE_COMMAND=claude
+agentram bind-model claude-subagent agentram-reviewer --role reviewer
+```
 
 Build a dry-run orchestration plan:
 
@@ -388,10 +396,11 @@ agentram_run_coding_orchestration
 
 TUI slash commands. Plain text only records/retrieves RAM; use `/ask` to call bound models:
 
-```text
-/bind-model claude claude-3-5-sonnet-latest role=reviewer api_key_env=ANTHROPIC_API_KEY
-/models
-/orchestrate review CLI orchestration
+```text
+/bind-model claude-subagent agentram-reviewer role=reviewer
+/bind-model claude claude-3-5-sonnet-latest role=reviewer api_key_env=ANTHROPIC_API_KEY
+/models
+/orchestrate review CLI orchestration
 /ask xin chào
 ```
 
@@ -882,3 +891,110 @@ pip install agentram[tui]
 ```
 
 Without `prompt_toolkit`, AgentRAM still works with basic terminal input; `/` then Enter opens the full slash palette.
+
+
+### Fix Bad Model Endpoints
+
+If `/ask` shows `base_url is required`, old model endpoints were bound without a URL. Remove or clear them:
+
+```text
+/models
+/remove-model model_xxx
+# or
+/clear-models
+```
+
+If `/ask` shows connection refused, the configured OpenAI-compatible server is not running at `base_url`:
+
+```text
+/bind-model openai-compatible Agentic --role coder --base-url http://localhost:8000/v1 --api-key-env OPENAI_API_KEY
+/ask xin chào
+```
+
+Start your local server first, or change `--base-url` to the provider URL.
+
+## Prompt Router Model
+
+AgentRAM can use a separate small router model before normal prompts. The router classifies each prompt, then sends it to the right path.
+
+```text
+coding   -> bound coding endpoints / Claude subagents
+planning -> Goal Stack and drift check
+memory   -> AgentRAM note ingest
+chat     -> RAM retrieve only
+```
+
+Bind a router model:
+
+```text
+/bind-router openai-compatible qwen2.5:1.5b base_url=http://localhost:8000/v1 api_key_env=OPENAI_API_KEY
+/route on
+```
+
+Then prompt without slash:
+
+```text
+fix adapter.py
+c?p nh?t goal stack
+ghi nh? d�ng Claude subagent
+```
+
+Disable auto routing:
+
+```text
+/route off
+```
+
+## Supervisor + Small Agent Workflow
+
+AgentRAM can run as a two-flow coding agent system, not only as a flat multi-model router.
+
+```text
+agentram
+  |
+  v
+Parse User Request
+  |
+  v
+Supervisor Memory
+  |
+  v
+Task Classifier / Supervisor Plan
+  |----------------------|
+  v                      v
+Main Agent               Small Agent
+(GPT-5.5 Codex)          (Qwen Codex)
+planning/coding/fix      notes/RAM/coding facts
+  |                      |
+  |----------|-----------|
+             v
+Merge + Update Memory
+             |
+             v
+Return Result
+```
+
+Bind workflow agents:
+
+```text
+/bind-agent supervisor claude-subagent agentram-planner
+/bind-agent main openai-compatible gpt-5.5-codex base_url=https://api.example.com/v1 api_key_env=MAIN_AGENT_KEY
+/bind-agent small openai-compatible qwen-codex base_url=http://localhost:8001/v1 api_key_env=SMALL_AGENT_KEY
+/workflow
+```
+
+Then use normal prompts without slash:
+
+```text
+refactor orchestration workflow
+fix bug in adapter.py
+plan next milestone
+```
+
+Runtime behavior:
+
+```text
+Supervisor creates plan -> Main agent executes -> Small agent records RAM notes -> AgentRAM merges result
+```
+
+Small agent should not own big direction. It records plans, decisions, files, risks, next tasks, and coding facts into RAM.

package/agentram/cli.py

@@ -1,15 +1,19 @@
 from __future__ import annotations
 
-import argparse
-import os
-import shlex
-import shutil
-import textwrap
+import argparse
+from concurrent.futures import ThreadPoolExecutor
+import json
+import os
+import shlex
+import shutil
+import textwrap
+import time
 from pathlib import Path
 from typing import Any
 
-from .config import default_ram_root
-from .mcp_server import McpContext, call_tool
+from .config import default_ram_root
+from .mcp_server import McpContext, call_tool
+from .orchestration import AgentModelEndpoint, MultiModelCodingOrchestrator
 
 SUBAGENTS: dict[str, str] = {
     "memory": "Summarize important facts, decisions, files, risks, and next tasks into AgentRAM events. Do not edit code.",
@@ -31,8 +35,15 @@ SLASH_COMMANDS: list[tuple[str, str]] = [
     ("/agents", "List Claude-style subagent presets"),
     ("/agent <name> <task>", "Build Claude Code subagent prompt"),
     ("/models", "List bound coding models"),
-    ("/bind-model provider model", "Bind model endpoint"),
-    ("/orchestrate <task>", "Build multi-model agent plan"),
+    ("/remove-model <id>", "Remove bound coding model"),
+    ("/disable-model <id>", "Disable bound coding model"),
+    ("/clear-models", "Remove all bound coding models"),
+    ("/bind-model provider model", "Bind model endpoint"),
+    ("/bind-router provider model", "Bind intent router model"),
+    ("/bind-agent slot provider model", "Bind supervisor/main/small agent"),
+    ("/workflow", "Show supervisor workflow agents"),
+    ("/route on|off|status", "Toggle auto prompt routing"),
+    ("/orchestrate <task>", "Build multi-model agent plan"),
     ("/ask <prompt>", "Execute bound models and return outputs"),
     ("/claude-install [path]", "Install .claude commands and agents"),
     ("/note <text>", "Save decision note"),
@@ -55,15 +66,22 @@ SLASH_HELP = """Slash commands:
 /agents                       List subagent presets
 /agent <name> <task>          Build Claude Code subagent prompt
 /models                       List bound coding models
-/bind-model provider model    Bind model endpoint
-/orchestrate <task>           Build multi-model agent plan
+/remove-model <id>            Remove bound coding model
+/disable-model <id>           Disable bound coding model
+/clear-models                 Remove all bound coding models
+/bind-model provider model    Bind model endpoint
+/bind-router provider model   Bind intent router model
+/bind-agent slot provider model Bind supervisor/main/small agent
+/workflow                     Show supervisor workflow agents
+/route on|off|status          Toggle auto prompt routing
+/orchestrate <task>           Build multi-model agent plan
 /ask <prompt>                 Execute bound models and return outputs
 /claude-install [path]        Install .claude commands and agents
 /note <text>                  Save decision note
 /clear                        Clear chat
 /exit                         Quit
-Plain text                    Capture coding chat message and retrieve context
-""".strip()
+Plain text                    Capture coding chat message and retrieve context
+""".strip()
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -77,14 +95,39 @@ def build_parser() -> argparse.ArgumentParser:
     subparsers.add_parser("goal", help="Show goal stack.")
     subparsers.add_parser("agents", help="List subagent presets.")
     subparsers.add_parser("models", help="List bound coding model endpoints.")
+    subparsers.add_parser("clear-models", help="Remove all bound coding model endpoints.")
+
+    remove_model = subparsers.add_parser("remove-model", help="Remove one bound coding model endpoint.")
+    remove_model.add_argument("id", help="Endpoint id.")
+
+    disable_model = subparsers.add_parser("disable-model", help="Disable one bound coding model endpoint.")
+    disable_model.add_argument("id", help="Endpoint id.")
 
     bind_model = subparsers.add_parser("bind-model", help="Bind a coding model endpoint.")
-    bind_model.add_argument("provider", help="Provider name, e.g. claude, openai-compatible, groq.")
-    bind_model.add_argument("model", help="Model name.")
+    bind_model.add_argument("provider", help="Provider name, e.g. claude, openai-compatible, groq, claude-subagent.")
+    bind_model.add_argument("model", help="Model name or Claude subagent name.")
     bind_model.add_argument("--role", default="coder", help="Agent role.")
     bind_model.add_argument("--base-url", default="", help="Provider base URL.")
-    bind_model.add_argument("--api-key-env", default="", help="Environment variable containing API key.")
-    bind_model.add_argument("--modalities", default="text", help="Comma-separated modalities.")
+    bind_model.add_argument("--api-key-env", default="", help="Environment variable containing API key.")
+    bind_model.add_argument("--modalities", default="text", help="Comma-separated modalities.")
+
+    bind_router = subparsers.add_parser("bind-router", help="Bind a separate intent router model endpoint.")
+    bind_router.add_argument("provider", help="Provider name, e.g. openai-compatible, groq, claude-subagent.")
+    bind_router.add_argument("model", help="Router model name.")
+    bind_router.add_argument("--base-url", default="", help="Provider base URL or local command for claude-subagent.")
+    bind_router.add_argument("--api-key-env", default="", help="Environment variable containing API key.")
+
+    bind_agent = subparsers.add_parser("bind-agent", help="Bind supervisor/main/small workflow agent.")
+    bind_agent.add_argument("slot", choices=["supervisor", "main", "small"], help="Workflow slot.")
+    bind_agent.add_argument("provider", help="Provider name, e.g. claude-subagent, openai-compatible, groq.")
+    bind_agent.add_argument("model", help="Model or subagent name.")
+    bind_agent.add_argument("--base-url", default="", help="Provider base URL or local command for claude-subagent.")
+    bind_agent.add_argument("--api-key-env", default="", help="Environment variable containing API key.")
+
+    subparsers.add_parser("workflow", help="Show supervisor/main/small workflow agents.")
+
+    route = subparsers.add_parser("route", help="Toggle or show auto prompt routing.")
+    route.add_argument("mode", nargs="?", default="status", choices=["on", "off", "status"], help="Auto route mode.")
 
     orchestrate = subparsers.add_parser("orchestrate", help="Build or run multi-model coding orchestration.")
     orchestrate.add_argument("task", nargs="?", default="", help="Coding task.")
@@ -156,9 +199,30 @@ def run_command(args: argparse.Namespace) -> int:
     if command == "models":
         print(models_text(context))
         return 0
-    if command == "bind-model":
-        print(bind_model_text(context, vars(args)))
+    if command == "remove-model":
+        print(remove_model_text(context, args.id))
+        return 0
+    if command == "disable-model":
+        print(disable_model_text(context, args.id))
+        return 0
+    if command == "clear-models":
+        print(clear_models_text(context))
         return 0
+    if command == "bind-model":
+        print(bind_model_text(context, vars(args)))
+        return 0
+    if command == "bind-router":
+        print(bind_router_text(context, vars(args)))
+        return 0
+    if command == "bind-agent":
+        print(bind_agent_text(context, vars(args)))
+        return 0
+    if command == "workflow":
+        print(workflow_text(context))
+        return 0
+    if command == "route":
+        print(route_text(context, args.mode))
+        return 0
     if command == "orchestrate":
         task = args.task or input("Task > ").strip()
         print(orchestrate_text(context, task, files=args.file, execute=args.execute))
@@ -194,13 +258,24 @@ def run_tui(context: McpContext) -> None:
             user_input = BUTTONS[user_input]
         if user_input:
             messages.append(f"user > {user_input}")
-        response = handle_chat_input(context, user_input, messages)
+        response = run_with_activity(context, messages, user_input)
         if response == "__clear__":
             messages.clear()
             messages.append("system > Chat cleared.")
         elif response:
             messages.append("agentram > " + response)
-        del messages[:-10]
+        del messages[:-10]
+
+def run_with_activity(context: McpContext, messages: list[str], user_input: str) -> str:
+    with ThreadPoolExecutor(max_workers=1) as executor:
+        future = executor.submit(handle_chat_input, context, user_input, messages)
+        frames = ["thinking", "thinking.", "thinking..", "thinking...", "acting", "acting.", "acting..", "acting..."]
+        index = 0
+        while not future.done():
+            draw_screen(context, messages, activity=f"agentram > {frames[index % len(frames)]}")
+            index += 1
+            time.sleep(0.18)
+        return future.result()
 
 
 
@@ -238,20 +313,24 @@ def read_tui_input(prompt_session: Any | None) -> str:
         return input("You > ")
     return prompt_session.prompt("You > ")
 
-def handle_chat_input(context: McpContext, text: str, messages: list[str] | None = None) -> str:
+def handle_chat_input(context: McpContext, text: str, messages: list[str] | None = None) -> str:
     if not text:
         return SLASH_HELP
     if text == "/":
         return slash_palette_text()
     if text.startswith("/"):
         return handle_slash_command(context, text, messages)
-    call_tool(
-        context,
-        "agentram_emit_event",
-        {"type": "USER_MESSAGE", "payload": {"content": text}, "task_id": "codex", "ingest": False},
-    )
-    context_block = retrieve_text(context, text, task_id="codex", limit=6)
-    return "Coding chat captured. Relevant context:\n" + context_block
+    call_tool(
+        context,
+        "agentram_emit_event",
+        {"type": "USER_MESSAGE", "payload": {"content": text}, "task_id": "codex", "ingest": False},
+    )
+    if context.profile_store.list_agents():
+        return supervisor_workflow_text(context, text)
+    if context.profile_store.auto_route_enabled():
+        return route_plain_prompt_text(context, text)
+    context_block = retrieve_text(context, text, task_id="codex", limit=6)
+    return "Coding chat captured. Relevant context:\n" + context_block
 
 
 def handle_slash_command(context: McpContext, text: str, messages: list[str] | None = None) -> str:
@@ -282,10 +361,30 @@ def handle_slash_command(context: McpContext, text: str, messages: list[str] | N
         return agents_text()
     if command == "/models":
         return models_text(context)
-    if command == "/bind-model":
-        if len(rest) < 2:
-            return "Usage: /bind-model <provider> <model> [--role coder] [--base-url URL] [--api-key-env ENV_NAME]"
-        return bind_model_text(context, parse_bind_model_args(rest))
+    if command == "/remove-model":
+        return remove_model_text(context, raw_rest)
+    if command == "/disable-model":
+        return disable_model_text(context, raw_rest)
+    if command == "/clear-models":
+        return clear_models_text(context)
+    if command == "/bind-model":
+        if len(rest) < 2:
+            return "Usage: /bind-model <provider> <model> [--role coder] [--base-url URL_OR_COMMAND] [--api-key-env ENV_NAME]"
+        return bind_model_text(context, parse_bind_model_args(rest))
+    if command == "/bind-router":
+        if len(rest) < 2:
+            return "Usage: /bind-router <provider> <model> [--base-url URL_OR_COMMAND] [--api-key-env ENV_NAME]"
+        return bind_router_text(context, parse_bind_model_args(rest))
+    if command == "/bind-agent":
+        if len(rest) < 3:
+            return "Usage: /bind-agent <supervisor|main|small> <provider> <model> [--base-url URL_OR_COMMAND] [--api-key-env ENV_NAME]"
+        options = parse_bind_model_args(rest[1:])
+        options["slot"] = rest[0]
+        return bind_agent_text(context, options)
+    if command == "/workflow":
+        return workflow_text(context)
+    if command == "/route":
+        return route_text(context, rest[0] if rest else "status")
     if command == "/orchestrate":
         execute = "--execute" in rest
         task = raw_rest.replace("--execute", "").strip()
@@ -439,7 +538,7 @@ def models_text(context: McpContext) -> str:
     data = payload(call_tool(context, "agentram_read_coding_models", {}))
     endpoints = data.get("endpoints", [])
     if not endpoints:
-        return "No coding models bound. Use /bind-model claude claude-3-5-sonnet-latest role=reviewer api_key_env=ANTHROPIC_API_KEY"
+        return "No coding models bound. Use /bind-model claude-subagent agentram-reviewer role=reviewer or /bind-model claude claude-3-5-sonnet-latest role=reviewer api_key_env=ANTHROPIC_API_KEY"
     lines = ["Bound coding models:"]
     for endpoint in endpoints:
         lines.append(f"- {endpoint.get('id')} provider={endpoint.get('provider')} model={endpoint.get('model')} role={endpoint.get('role')} modalities={','.join(endpoint.get('modalities', []))}")
@@ -468,6 +567,28 @@ def parse_bind_model_args(parts: list[str]) -> dict[str, object]:
     return options
 
 
+
+
+def remove_model_text(context: McpContext, endpoint_id: str) -> str:
+    endpoint_id = endpoint_id.strip()
+    if not endpoint_id:
+        return "Usage: /remove-model <id>"
+    data = payload(call_tool(context, "agentram_remove_coding_model", {"id": endpoint_id}))
+    return f"Removed models: {data.get('removed', 0)}"
+
+
+def disable_model_text(context: McpContext, endpoint_id: str) -> str:
+    endpoint_id = endpoint_id.strip()
+    if not endpoint_id:
+        return "Usage: /disable-model <id>"
+    data = payload(call_tool(context, "agentram_disable_coding_model", {"id": endpoint_id}))
+    return f"Disabled models: {data.get('changed', 0)}"
+
+
+def clear_models_text(context: McpContext) -> str:
+    payload(call_tool(context, "agentram_clear_coding_models", {}))
+    return "Cleared all bound coding models."
+
 def bind_model_text(context: McpContext, options: dict[str, object]) -> str:
     api_key_env = str(options.get("api_key_env", ""))
     if api_key_env.startswith(("sk-", "gsk_", "sk_")):
@@ -489,7 +610,194 @@ def bind_model_text(context: McpContext, options: dict[str, object]) -> str:
     return f"Bound model: {endpoint.get('id')} provider={endpoint.get('provider')} model={endpoint.get('model')} role={endpoint.get('role')}"
 
 
-def orchestrate_text(context: McpContext, task: str, files: list[str] | None = None, execute: bool = False) -> str:
+def bind_agent_text(context: McpContext, options: dict[str, object]) -> str:
+    slot = str(options.get("slot", "")).strip().lower()
+    if slot not in {"supervisor", "main", "small"}:
+        return "Usage: /bind-agent <supervisor|main|small> <provider> <model>"
+    api_key_env = str(options.get("api_key_env", ""))
+    if api_key_env.startswith(("sk-", "gsk_", "sk_")):
+        return "Do not paste raw API key into api_key_env. Set env var first, then use api_key_env=ENV_NAME."
+    role = {"supervisor": "supervisor", "main": "coder", "small": "memory"}[slot]
+    endpoint = AgentModelEndpoint(
+        provider=str(options.get("provider", "openai-compatible")),
+        model=str(options.get("model", "")),
+        role=role,
+        base_url=str(options.get("base_url", "")),
+        api_key_env=api_key_env,
+        modalities=["text"],
+    )
+    context.profile_store.set_agent(slot, endpoint)
+    return f"Bound {slot} agent: provider={endpoint.provider} model={endpoint.model} role={endpoint.role}"
+
+def workflow_text(context: McpContext) -> str:
+    agents = context.profile_store.list_agents()
+    if not agents:
+        return "No supervisor workflow agents bound. Use /bind-agent supervisor|main|small <provider> <model>."
+    lines = ["Supervisor workflow agents:"]
+    for slot in ["supervisor", "main", "small"]:
+        endpoint = agents.get(slot)
+        if endpoint:
+            lines.append(f"- {slot}: {endpoint.provider}:{endpoint.model} role={endpoint.role}")
+        else:
+            lines.append(f"- {slot}: not bound")
+    return "\n".join(lines)
+
+def supervisor_workflow_text(context: McpContext, prompt: str) -> str:
+    agents = context.profile_store.list_agents()
+    supervisor = agents.get("supervisor")
+    main_agent = agents.get("main")
+    small_agent = agents.get("small")
+    memory_context = retrieve_text(context, prompt, task_id="codex", limit=8)
+    plan = supervisor_plan(supervisor, prompt, memory_context)
+    outputs: dict[str, str] = {}
+    with ThreadPoolExecutor(max_workers=2) as executor:
+        futures = {}
+        if main_agent:
+            futures[executor.submit(call_agent_endpoint, main_agent, build_main_agent_prompt(prompt, plan, memory_context))] = "main"
+        if small_agent:
+            futures[executor.submit(call_agent_endpoint, small_agent, build_small_agent_prompt(prompt, plan, memory_context))] = "small"
+        for future, slot in list(futures.items()):
+            try:
+                outputs[slot] = future.result()
+            except Exception as error:  # noqa: BLE001 - agent boundary
+                outputs[slot] = f"error: {model_error_hint(str(error))}"
+    if not main_agent:
+        outputs["main"] = "No main agent bound. Use /bind-agent main <provider> <model>."
+    if small_agent and outputs.get("small") and not outputs["small"].startswith("error:"):
+        call_tool(
+            context,
+            "agentram_emit_event",
+            {"type": "DECISION", "payload": {"content": outputs["small"]}, "task_id": "codex", "ingest": True},
+        )
+    return "\n".join(
+        [
+            "Workflow: supervisor -> main + small -> merge",
+            "Supervisor plan:",
+            plan,
+            "",
+            "Main agent result:",
+            outputs.get("main", "-"),
+            "",
+            "Small memory agent notes:",
+            outputs.get("small", "No small agent bound."),
+        ]
+    )
+
+def supervisor_plan(supervisor: AgentModelEndpoint | None, prompt: str, memory_context: str) -> str:
+    if not supervisor:
+        return "No supervisor bound. Fallback plan: handle user request, run main coding agent, ask small agent to update RAM notes."
+    try:
+        return call_agent_endpoint(supervisor, build_supervisor_prompt(prompt, memory_context))
+    except Exception as error:  # noqa: BLE001 - supervisor boundary
+        return f"Supervisor error: {error}\nFallback plan: handle user request, run main coding agent, ask small agent to update RAM notes."
+
+def call_agent_endpoint(endpoint: AgentModelEndpoint, prompt: str) -> str:
+    return MultiModelCodingOrchestrator([endpoint])._call_endpoint(endpoint, prompt)
+
+def build_supervisor_prompt(prompt: str, memory_context: str) -> str:
+    return "\n".join(["You are AgentRAM supervisor. Act like a senior coding-agent boss.", "Create concise plan for main coding agent and small memory agent.", "Return only actionable plan. No markdown table.", "User request:", prompt, "AgentRAM context:", memory_context])
+
+def build_main_agent_prompt(prompt: str, plan: str, memory_context: str) -> str:
+    return "\n".join(["You are AgentRAM main coding agent.", "Follow supervisor plan. Focus on planning, orchestration, coding, refactor, bug fix, and final result.", "Do not invent repo facts. Mention files to inspect/change.", "User request:", prompt, "Supervisor plan:", plan, "AgentRAM context:", memory_context])
+
+def build_small_agent_prompt(prompt: str, plan: str, memory_context: str) -> str:
+    return "\n".join(["You are AgentRAM small memory agent.", "Do not edit code. Note plans, decisions, risks, files, next tasks, and coding facts for RAM.", "Return concise memory notes only.", "User request:", prompt, "Supervisor plan:", plan, "AgentRAM context:", memory_context])
+
+def bind_router_text(context: McpContext, options: dict[str, object]) -> str:
+    api_key_env = str(options.get("api_key_env", ""))
+    if api_key_env.startswith(("sk-", "gsk_", "sk_")):
+        return "Do not paste raw API key into api_key_env. Set env var first, then use api_key_env=ENV_NAME."
+    endpoint = AgentModelEndpoint(
+        provider=str(options.get("provider", "openai-compatible")),
+        model=str(options.get("model", "")),
+        role="router",
+        base_url=str(options.get("base_url", "")),
+        api_key_env=api_key_env,
+        modalities=["text"],
+    )
+    context.profile_store.set_router(endpoint)
+    return f"Bound router: provider={endpoint.provider} model={endpoint.model}"
+
+def route_text(context: McpContext, mode: str) -> str:
+    normalized = mode.strip().lower() or "status"
+    if normalized == "on":
+        context.profile_store.set_auto_route(True)
+    elif normalized == "off":
+        context.profile_store.set_auto_route(False)
+    elif normalized != "status":
+        return "Usage: /route on|off|status"
+    router = context.profile_store.get_router()
+    return "\n".join(
+        [
+            f"Auto route: {'on' if context.profile_store.auto_route_enabled() else 'off'}",
+            f"Router model: {router.provider}:{router.model}" if router else "Router model: heuristic fallback",
+        ]
+    )
+
+def route_plain_prompt_text(context: McpContext, prompt: str) -> str:
+    decision = classify_prompt_intent(context, prompt)
+    intent = str(decision.get("intent", "chat"))
+    confidence = float(decision.get("confidence", 0.0))
+    prefix = f"Route: {intent} confidence={confidence:.2f}"
+    if intent == "coding":
+        if context.profile_store.list_endpoints():
+            return prefix + "\n" + orchestrate_text(context, prompt, execute=True)
+        context_block = retrieve_text(context, prompt, task_id="codex", limit=6)
+        return prefix + "\nNo coding models bound. Use /bind-model.\nCoding chat captured. Relevant context:\n" + context_block
+    if intent == "planning":
+        return prefix + "\n" + drift_text(context, prompt) + "\n\n" + goal_text(context)
+    if intent == "memory":
+        return prefix + "\n" + note_text(context, prompt)
+    context_block = retrieve_text(context, prompt, task_id="codex", limit=6)
+    return prefix + "\nCoding chat captured. Relevant context:\n" + context_block
+
+def classify_prompt_intent(context: McpContext, prompt: str) -> dict[str, object]:
+    router = context.profile_store.get_router()
+    if router:
+        try:
+            response = MultiModelCodingOrchestrator([router])._call_endpoint(router, build_router_prompt(prompt))
+            parsed = json.loads(extract_json_object(response))
+            if isinstance(parsed, dict) and parsed.get("intent") in {"coding", "planning", "memory", "chat"}:
+                return {"intent": parsed.get("intent"), "confidence": float(parsed.get("confidence", 0.0)), "source": "model"}
+        except Exception as error:  # noqa: BLE001 - router fallback boundary
+            return {**heuristic_intent(prompt), "source": "heuristic", "router_error": str(error)}
+    return {**heuristic_intent(prompt), "source": "heuristic"}
+
+def build_router_prompt(prompt: str) -> str:
+    return "\n".join(
+        [
+            "Classify user prompt for AgentRAM routing.",
+            "Return only JSON, no markdown.",
+            "Schema: {\"intent\":\"coding|planning|memory|chat\",\"confidence\":0.0,\"reason\":\"short\"}",
+            "coding = edit/review/debug/refactor/test/code/file requests.",
+            "planning = goal stack, milestone, mission, next task, drift, roadmap.",
+            "memory = remember/note/decision/fact to save.",
+            "chat = other normal conversation.",
+            f"Prompt: {prompt}",
+        ]
+    )
+
+def extract_json_object(text: str) -> str:
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1 or end < start:
+        return "{}"
+    return text[start : end + 1]
+
+def heuristic_intent(prompt: str) -> dict[str, object]:
+    lower = prompt.lower()
+    memory_words = ["ghi nhớ", "remember", "note", "decision", "lưu lại", "save this"]
+    planning_words = ["goal", "kế hoạch", "ke hoach", "milestone", "mission", "drift", "next task", "roadmap", "mục tiêu", "muc tieu"]
+    coding_words = ["sửa", "sua", "fix", "bug", "code", "test", "refactor", "review", "file", ".py", ".js", "endpoint", "class", "function"]
+    if any(word in lower for word in memory_words):
+        return {"intent": "memory", "confidence": 0.75}
+    if any(word in lower for word in planning_words):
+        return {"intent": "planning", "confidence": 0.75}
+    if any(word in lower for word in coding_words):
+        return {"intent": "coding", "confidence": 0.72}
+    return {"intent": "chat", "confidence": 0.55}
+
+def orchestrate_text(context: McpContext, task: str, files: list[str] | None = None, execute: bool = False) -> str:
     if not task.strip():
         return "Usage: /orchestrate <coding task>"
     tool = "agentram_run_coding_orchestration" if execute else "agentram_build_coding_orchestration"
@@ -505,9 +813,24 @@ def orchestrate_text(context: McpContext, task: str, files: list[str] | None = N
         endpoint = result.get("endpoint", {})
         status = "ok" if result.get("ok") else "error"
         output = result.get("output") or result.get("error", "")
-        lines.append(f"- {endpoint.get('id')} {status}: {str(output)[:300]}")
+        lines.append(f"- {endpoint.get('id')} {status}: {model_error_hint(str(output))[:360]}")
     return "\n".join(lines)
 
+
+def model_error_hint(message: str) -> str:
+    lower = message.lower()
+    if "base_url is required" in lower:
+        return message + " | Fix: /remove-model <id> or re-bind with --base-url http://localhost:8000/v1"
+    if "actively refused" in lower or "connection refused" in lower or "winerror 10061" in lower:
+        return message + " | Fix: start your OpenAI-compatible server at base_url, or change --base-url."
+    if "http 404" in lower or "404: not found" in lower:
+        return message + " | Fix: verify base_url includes /v1, provider supports /chat/completions, and model name exists."
+    if "returned non-json" in lower or "expecting value" in lower:
+        return message + " | Fix: endpoint returned empty/HTML/non-JSON. Check base_url, auth key, proxy, and server logs."
+    if "missing api key env" in lower:
+        return message + " | Fix: set environment variable, then bind using --api-key-env ENV_NAME, not raw key."
+    return message
+
 def claude_template_root() -> Path:
     return Path(__file__).resolve().parent.parent / ".claude"
 
@@ -574,7 +897,7 @@ BUTTONS = {
 }
 
 
-def draw_screen(context: McpContext, messages: list[str]) -> None:
+def draw_screen(context: McpContext, messages: list[str], activity: str | None = None) -> None:
     clear_terminal()
     width = min(max(shutil.get_terminal_size((110, 34)).columns, 86), 132)
     left_width = 30
@@ -584,14 +907,16 @@ def draw_screen(context: McpContext, messages: list[str]) -> None:
     print("+" + "-" * (width - 2) + "+")
 
     sidebar = sidebar_lines(context)
-    chat = wrap_messages(messages, right_width - 4)[-22:]
+    display_messages = [*messages, activity] if activity else messages
+    chat = wrap_messages(display_messages, right_width - 4)[-22:]
     rows = max(len(sidebar), len(chat), 22)
     for index in range(rows):
         left = sidebar[index] if index < len(sidebar) else ""
         right = chat[index] if index < len(chat) else ""
         print("| " + left[: left_width - 2].ljust(left_width - 2) + "| " + right[: right_width - 2].ljust(right_width - 2) + "|")
     print("+" + "-" * (left_width - 1) + "+" + "-" * (right_width) + "+")
-    print(box_text("Input: type / for live dropdown. Enter '/' for full palette. /ask calls models.", width))
+    footer = "Thinking/acting..." if activity else "Input: type / for live dropdown. Enter '/' for full palette. /ask calls models."
+    print(box_text(footer, width))
     print("+" + "-" * (width - 2) + "+")
 
 
@@ -626,6 +951,7 @@ def sidebar_lines(context: McpContext) -> list[str]:
         "  /agents",
         "  /claude-install .",
         "  /models",
+        "  /clear-models",
         "  /ask <prompt>",
     ]
 

package/agentram/mcp_server.py

@@ -244,6 +244,29 @@ def tools_list() -> dict[str, Any]:
                     "required": ["provider", "model"],
                 },
             },
+            {
+                "name": "agentram_remove_coding_model",
+                "description": "Remove one bound coding model endpoint by id.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {"id": {"type": "string"}},
+                    "required": ["id"],
+                },
+            },
+            {
+                "name": "agentram_disable_coding_model",
+                "description": "Disable one bound coding model endpoint by id without deleting it.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {"id": {"type": "string"}},
+                    "required": ["id"],
+                },
+            },
+            {
+                "name": "agentram_clear_coding_models",
+                "description": "Remove all bound coding model endpoints from this project RAM.",
+                "inputSchema": {"type": "object", "properties": {}},
+            },
             {
                 "name": "agentram_read_coding_models",
                 "description": "Read coding-agent model endpoints bound to this project RAM.",
@@ -349,6 +372,24 @@ def call_tool(context: McpContext, name: str, arguments: dict[str, Any]) -> dict
         data = context.profile_store.upsert(endpoint)
         return tool_result({"ok": True, "endpoint": endpoint.to_dict(), "profile": data})
 
+    if name == "agentram_remove_coding_model":
+        endpoint_id = str(arguments.get("id", ""))
+        if not endpoint_id.strip():
+            raise ValueError("id is required")
+        data = context.profile_store.remove(endpoint_id)
+        return tool_result({"ok": True, **data})
+
+    if name == "agentram_disable_coding_model":
+        endpoint_id = str(arguments.get("id", ""))
+        if not endpoint_id.strip():
+            raise ValueError("id is required")
+        data = context.profile_store.set_enabled(endpoint_id, False)
+        return tool_result({"ok": True, **data})
+
+    if name == "agentram_clear_coding_models":
+        data = context.profile_store.clear()
+        return tool_result({"ok": True, **data})
+
     if name == "agentram_read_coding_models":
         endpoints = context.profile_store.list_endpoints()
         return tool_result({"endpoints": [endpoint.to_dict() for endpoint in endpoints]})

package/agentram/orchestration.py

@@ -4,6 +4,9 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass, field
 import json
 import os
+import shlex
+import subprocess
+import urllib.error
 import urllib.request
 from typing import Any, Callable
 from uuid import uuid4
@@ -106,6 +109,8 @@ class MultiModelCodingOrchestrator:
             return self._call_openai_compatible(endpoint, prompt)
         if provider in {"anthropic", "claude"}:
             return self._call_anthropic(endpoint, prompt)
+        if provider in {"claude-code", "claude-cli", "claude-subagent", "claude-code-subagent"}:
+            return self._call_claude_code_subagent(endpoint, prompt)
         raise ValueError(f"Unsupported provider for execution: {endpoint.provider}")
 
     def _call_openai_compatible(self, endpoint: AgentModelEndpoint, prompt: str) -> str:
@@ -121,8 +126,20 @@ class MultiModelCodingOrchestrator:
             headers={"Content-Type": "application/json", "Authorization": f"Bearer {api_key}"} if api_key else {"Content-Type": "application/json"},
             method="POST",
         )
-        with urllib.request.urlopen(request, timeout=120) as response:
-            data = json.loads(response.read().decode("utf-8"))
+        url = endpoint.base_url.rstrip("/") + "/chat/completions"
+        try:
+            with urllib.request.urlopen(request, timeout=120) as response:
+                raw = response.read().decode("utf-8")
+        except urllib.error.HTTPError as error:
+            body = error.read().decode("utf-8", errors="replace") if error.fp else ""
+            hint = f"OpenAI-compatible HTTP {error.code} at {url}"
+            if error.code == 404:
+                hint += " | base_url should include /v1 but not /chat/completions; verify provider URL and model name"
+            raise RuntimeError(f"{hint} | response={body[:500]}") from error
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError as error:
+            raise RuntimeError(f"OpenAI-compatible returned non-JSON at {url} | response={raw[:500]}") from error
         return str(data.get("choices", [{}])[0].get("message", {}).get("content", ""))
 
     def _call_anthropic(self, endpoint: AgentModelEndpoint, prompt: str) -> str:
@@ -142,4 +159,32 @@ class MultiModelCodingOrchestrator:
         content = data.get("content", [])
         if content and isinstance(content, list):
             return "\n".join(str(item.get("text", "")) for item in content if isinstance(item, dict))
-        return str(data)
+        return str(data)
+
+    def _call_claude_code_subagent(self, endpoint: AgentModelEndpoint, prompt: str) -> str:
+        command = endpoint.base_url.strip() or os.getenv("AGENTRAM_CLAUDE_COMMAND", "claude")
+        args = shlex.split(command)
+        if not args:
+            raise ValueError("claude command is required")
+        subagent_prompt = "\n".join(
+            [
+                f"Use Claude Code subagent entrypoint: {endpoint.model}",
+                f"Subagent role: {endpoint.role}",
+                "If that subagent exists in .claude/agents, follow it. If not, act as this role.",
+                "Return concise coding-agent output only.",
+                "",
+                prompt,
+            ]
+        )
+        process = subprocess.run(
+            [*args, "-p", subagent_prompt],
+            check=False,
+            capture_output=True,
+            encoding="utf-8",
+            timeout=300,
+        )
+        output = (process.stdout or "").strip()
+        error = (process.stderr or "").strip()
+        if process.returncode != 0:
+            raise RuntimeError(error or f"claude command failed with exit code {process.returncode}")
+        return output or error

package/agentram/storage.py

@@ -80,15 +80,27 @@ class JsonAgentProfileStore:
         self.path = Path(path)
         self.path.parent.mkdir(parents=True, exist_ok=True)
 
-    def load(self) -> dict[str, object]:
-        if not self.path.exists():
-            return {"updated_at": utc_now(), "endpoints": []}
-        return json.loads(self.path.read_text(encoding="utf-8"))
-
-    def save(self, endpoints: list[AgentModelEndpoint]) -> dict[str, object]:
-        payload = {"updated_at": utc_now(), "endpoints": [endpoint.to_dict() for endpoint in endpoints]}
-        self.path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
-        return payload
+    def load(self) -> dict[str, object]:
+        if not self.path.exists():
+            return {"updated_at": utc_now(), "endpoints": [], "router": None, "auto_route": True, "agents": {}}
+        data = json.loads(self.path.read_text(encoding="utf-8"))
+        data.setdefault("endpoints", [])
+        data.setdefault("router", None)
+        data.setdefault("auto_route", True)
+        data.setdefault("agents", {})
+        return data
+
+    def save(self, endpoints: list[AgentModelEndpoint]) -> dict[str, object]:
+        current = self.load()
+        payload = {
+            "updated_at": utc_now(),
+            "endpoints": [endpoint.to_dict() for endpoint in endpoints],
+            "router": current.get("router"),
+            "auto_route": bool(current.get("auto_route", True)),
+            "agents": current.get("agents", {}),
+        }
+        self.path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+        return payload
 
     def list_endpoints(self) -> list[AgentModelEndpoint]:
         data = self.load()
@@ -108,6 +120,86 @@ class JsonAgentProfileStore:
             updated.append(endpoint)
         return self.save(updated)
 
+    def remove(self, endpoint_id: str) -> dict[str, object]:
+        endpoints = self.list_endpoints()
+        kept = [endpoint for endpoint in endpoints if endpoint.id != endpoint_id]
+        payload = self.save(kept)
+        payload["removed"] = len(endpoints) - len(kept)
+        return payload
+
+    def set_enabled(self, endpoint_id: str, enabled: bool) -> dict[str, object]:
+        endpoints = self.list_endpoints()
+        updated: list[AgentModelEndpoint] = []
+        changed = 0
+        for endpoint in endpoints:
+            if endpoint.id == endpoint_id:
+                data = endpoint.to_dict()
+                data["enabled"] = enabled
+                updated.append(AgentModelEndpoint.from_dict(data))
+                changed += 1
+            else:
+                updated.append(endpoint)
+        payload = self.save(updated)
+        payload["changed"] = changed
+        return payload
+
+    def clear(self) -> dict[str, object]:
+        payload = self.save([])
+        payload["cleared"] = True
+        return payload
+
+    def get_router(self) -> AgentModelEndpoint | None:
+        router = self.load().get("router")
+        if not isinstance(router, dict):
+            return None
+        return AgentModelEndpoint.from_dict(router)
+
+    def set_router(self, endpoint: AgentModelEndpoint | None) -> dict[str, object]:
+        current = self.load()
+        current["updated_at"] = utc_now()
+        current["router"] = endpoint.to_dict() if endpoint else None
+        self.path.write_text(json.dumps(current, indent=2, ensure_ascii=False), encoding="utf-8")
+        return current
+
+    def auto_route_enabled(self) -> bool:
+        return bool(self.load().get("auto_route", True))
+
+    def set_auto_route(self, enabled: bool) -> dict[str, object]:
+        current = self.load()
+        current["updated_at"] = utc_now()
+        current["auto_route"] = enabled
+        self.path.write_text(json.dumps(current, indent=2, ensure_ascii=False), encoding="utf-8")
+        return current
+
+    def get_agent(self, slot: str) -> AgentModelEndpoint | None:
+        agents = self.load().get("agents", {})
+        if not isinstance(agents, dict):
+            return None
+        item = agents.get(slot)
+        if not isinstance(item, dict):
+            return None
+        return AgentModelEndpoint.from_dict(item)
+
+    def set_agent(self, slot: str, endpoint: AgentModelEndpoint | None) -> dict[str, object]:
+        current = self.load()
+        agents = current.get("agents", {})
+        if not isinstance(agents, dict):
+            agents = {}
+        if endpoint is None:
+            agents.pop(slot, None)
+        else:
+            agents[slot] = endpoint.to_dict()
+        current["agents"] = agents
+        current["updated_at"] = utc_now()
+        self.path.write_text(json.dumps(current, indent=2, ensure_ascii=False), encoding="utf-8")
+        return current
+
+    def list_agents(self) -> dict[str, AgentModelEndpoint]:
+        agents = self.load().get("agents", {})
+        if not isinstance(agents, dict):
+            return {}
+        return {slot: AgentModelEndpoint.from_dict(item) for slot, item in agents.items() if isinstance(item, dict)}
+
 
 def ensure_ram_storage(root: str | Path) -> dict[str, object]:
     ram_root = Path(root)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentram",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Async, model-agnostic Working RAM for coding agents.",
   "license": "MIT",
   "homepage": "https://github.com/trancongnghia/AGENT_RAM#readme",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentram"
-version = "0.1.5"
+version = "0.1.7"
 description = "Async, model-agnostic RAM layer for agentic coding tools."
 readme = "README.md"
 license = "MIT"