Skip to content

feat(chat): add an Agent mode that uses tools, and the agent-mode plan - #34

Merged
aryanjsx merged 2 commits into
mainfrom
docs/agent-mode-plan
Nov 8, 2026
Merged

aryanjsx merged 2 commits into
mainfrom
docs/agent-mode-plan

Conversation

@aryanjsx

@aryanjsx aryanjsx commented Nov 8, 2026

Copy link
Copy Markdown
Owner

What does this PR do?

The desktop app starts the server with --agent simple, so its chat never calls tools. This PR adds an Agent toggle to the chat, next to Web search and Deep Research. It also adds a six-phase plan for turning Locus into an agent that does tasks; this PR is phase 1.

Plan: docs/design/2026-11-08-agent-mode-plan.md covers what already exists in the repo, the gaps, and six phases with what "done" means for each:

  1. Agent mode in chat
  2. Attachments and web search through the agent
  3. Plans and approvals in the conversation
  4. Desktop control tools
  5. A hands-free voice loop
  6. Developer mode

Phase 1:

  • Request field: /v1/chat/completions takes an optional mode, either "chat" or "agent". Leaving it unset keeps the current routing, so locus gui users on the default orchestrator see no change.
  • Agent: Agent mode reuses the configured agent if it has tools. Otherwise it builds an orchestrator the first time it's needed (src/locus/server/task_agent.py) and caches it on app.state.task_agent.
  • Tools: read-only only: think, calculator, file_read, pdf_extract and memory_manage. file_read stays inside the home folder unless security.allowed_dirs is set. Writing files and running commands wait for phase 3, because the server can't ask for approval yet.
  • Live tool calls: agent streams forward that agent's agent_turn_start, tool_call_start and tool_call_end events while it runs, so the existing tool cards fill in live. Events from other agents on the bus are filtered out.
  • UI: the toggle is remembered between launches, and Agent and Deep Research can't both be on. A one-line notice appears when the selected model is under 4B. If the conversation has web search or attachments, a notice explains that Agent mode can't use them yet (phase 2) and the message gets a chat answer.
  • Preset: a new assistant preset (locus init --preset assistant) uses the same tools. It's listed in the README.

How was this tested?

  • New tests: tests/server/test_agent_mode.py has 7 tests covering:
    • chat mode skipping a tool agent
    • reusing or building the agent
    • streaming only this agent's tool events
    • the web search fallback
    • falling back to chat when the agent can't start
    • the read-only tool set kept to the home folder
  • Frontend: new modelSizeBillions and isSmallForAgent tests. All 128 vitest tests pass and tsc -b is clean.
  • Server suite: tests/server, the preset tests and the CLI tests give 546 passed and 9 failed. The same 9 fail on main without this change. They're in test_api_routes (TestAgentRoutes), test_connectors_router, test_deep_research_tools_wiring and test_security_factory_wiring, and at least one needs the locus_rust extension, which wasn't installed locally.
  • Real model: I checked that the assistant agent builds with all five tools from the real registries. It hasn't been run end to end with a real model yet; Ollama wasn't running.

Checklist

  • Tests pass (uv run pytest tests/ -v): new and related suites pass; the 9 failures above also fail on main
  • Linter passes on changed files (ruff check)
  • Formatter passes on changed files (ruff format --check)
  • New/changed public API has docstrings
  • Follows registry pattern (if adding new component)
  • Documentation updated (if applicable)

Six phases: agent mode in chat, attachments and web search through the
agent, plans and approvals in the conversation, desktop control tools, a
hands-free voice loop, and developer mode. Lists what already exists in
the repo, the gaps, and what "done" means for each phase.
The desktop app serves with --agent simple, so its chat never called
tools. Add an Agent toggle next to Web search and Deep Research.

- Chat requests take an optional mode, "chat" or "agent". Unset keeps
  the existing routing, so the server's configured agent still answers.
- Agent mode reuses the configured agent when it has tools; otherwise
  it builds an orchestrator on first use with read-only tools (think,
  calculator, file_read, pdf_extract, memory_manage). file_read stays in
  the home folder unless security.allowed_dirs is set. Writing files and
  running commands wait for approvals in the chat.
- Agent streams forward that agent's turn and tool events as they
  happen, so tool cards fill in live. Events from other agents on the
  bus are skipped.
- Warn when the selected model is under 4B, and give a chat answer when
  the conversation has web search or attachments, which the agent can't
  use yet.
- Add an "assistant" preset with the same tools.
@aryanjsx
aryanjsx merged commit 913da51 into main Nov 8, 2026
28 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant