From 2da047a3c045d7f6a574cd75914120f74ba62fef Mon Sep 17 00:00:00 2001 From: Aryan Date: Sun, 8 Nov 2026 20:57:09 +0530 Subject: [PATCH] feat(chat): ask in the chat before Agent mode changes anything Agent mode could only read, because the server had no way to ask before writing files or running commands. Add approvals in the conversation and let the agent use those tools once the user allows them. - New server/approvals.py classifies each tool call as read (never asks), change (asks) or run (always asks, including anything marked requires_confirmation). Unknown tools ask. - For a risky call the agent's thread pauses and the stream sends approval_required. POST /v1/chat/approvals/{id} answers with approve, approve_tool (that tool for the rest of the run) or deny. No answer in 5 minutes, or a request that can't ask, is a no. - Each stream starts with agent_run. POST /v1/chat/runs/{run_id}/stop, or closing the stream, ends the run at its next tool call. - Agent mode always uses its own orchestrator, which carries the hook, instead of the server's configured agent. It adds file_write, shell_exec and read-only git tools, stays in the home folder, runs tools one at a time and gets at least 25 turns. - The tool card shows Allow, Allow for this task and Deny, with the command or path in words. Stop ends the agent run, not only the reply. - The assistant preset stays read-only, since locus serve builds its agent without the approval hook. --- configs/locus/examples/assistant.toml | 13 +- docs/design/2026-11-08-agent-mode-plan.md | 8 + frontend/src/components/Chat/InputArea.tsx | 68 +++- .../src/components/Chat/ToolCallCard.test.ts | 26 ++ frontend/src/components/Chat/ToolCallCard.tsx | 90 ++++- frontend/src/lib/api.ts | 21 ++ frontend/src/types/index.ts | 7 +- src/locus/server/approvals.py | 218 ++++++++++++ src/locus/server/models.py | 5 + src/locus/server/routes.py | 98 +++++- src/locus/server/task_agent.py | 43 ++- tests/server/test_agent_approvals.py | 319 ++++++++++++++++++ tests/server/test_agent_mode.py | 41 ++- 13 files changed, 897 insertions(+), 60 deletions(-) create mode 100644 frontend/src/components/Chat/ToolCallCard.test.ts create mode 100644 src/locus/server/approvals.py create mode 100644 tests/server/test_agent_approvals.py diff --git a/configs/locus/examples/assistant.toml b/configs/locus/examples/assistant.toml index df06193..b7469c4 100644 --- a/configs/locus/examples/assistant.toml +++ b/configs/locus/examples/assistant.toml @@ -1,9 +1,9 @@ # Assistant — an agent that uses tools to do tasks, not only chat # Copy to ~/.locus/config.toml # -# The same tool set the desktop app's Agent mode uses. Every tool here only -# reads, or writes to Locus's own memory: writing files, running commands and -# network access are left out until they can ask you in the chat first. +# An agent with tools that only read, or write to Locus's own memory. For +# writing files and running commands, turn on Agent mode in the desktop app or +# browser GUI: it asks you in the chat before each of those calls. # # Usage: # locus ask "How many PDFs are in my Downloads folder?" @@ -18,7 +18,7 @@ default_model = "qwen3.5:9b" # Small models often miss tool calls [agent] default_agent = "orchestrator" # Multi-turn with tool selection -max_turns = 10 +max_turns = 25 [server] agent = "orchestrator" @@ -26,7 +26,10 @@ host = "127.0.0.1" port = 8000 [tools] -enabled = ["think", "calculator", "file_read", "pdf_extract", "memory_manage"] +enabled = [ + "think", "calculator", "file_read", "pdf_extract", "memory_manage", + "git_status", "git_diff", "git_log", +] [security] allowed_dirs = ["~"] # File tools stay in your home folder diff --git a/docs/design/2026-11-08-agent-mode-plan.md b/docs/design/2026-11-08-agent-mode-plan.md index fcdd7d8..fea6a03 100644 --- a/docs/design/2026-11-08-agent-mode-plan.md +++ b/docs/design/2026-11-08-agent-mode-plan.md @@ -79,6 +79,14 @@ Most of the agent machinery is in the repo. The gap is mostly wiring and UX. **Goal:** the user sees what the agent plans, what it's doing and what it needs approved, without leaving the chat. +> **Status (2026-11-08): approvals, risk levels and Stop are implemented. The plan checklist and Undo are not done yet.** As built: +> - **Broker:** `src/locus/server/approvals.py`. The Agent mode agent's `before_tool_call` hook classifies each call as `read` (never asks), `change` (asks) or `run` (always asks; covers anything marked `requires_confirmation`). Unknown tools count as `change`, so new tools ask by default. +> - **Asking:** for a risky call, the agent's thread pauses, the stream sends `approval_required`, and the run waits up to 5 minutes for `POST /v1/chat/approvals/{id}` with `approve`, `approve_tool` (this tool for the rest of the run) or `deny`. No answer counts as a no. Requests that can't ask (non-streaming) deny risky calls. +> - **Stop:** each stream starts with an `agent_run` event. Stop calls `POST /v1/chat/runs/{run_id}/stop`, which ends the run at its next tool call (`AgentCancelled`), and the answer becomes "Stopped." Closing the stream does the same. +> - **Agent:** Agent mode now always uses its own `orchestrator`, not the server's configured agent, since only that agent has the hook. It adds `file_write`, `shell_exec`, `git_status`, `git_diff` and `git_log`, is kept to the home folder, runs tools one at a time (approvals are tracked per run on the agent's thread), and gets at least 25 turns. +> - **UI:** the tool card shows **Allow**, **Allow for this task** and **Deny**, with the command or path in words. The `assistant` preset stays read-only, because `locus serve` builds its agent without the hook. +> - **Not done yet:** a plan checklist before multi-step tasks, Undo for file changes, "always allow" rules that last beyond one run, and resuming a stopped run. + - **Plan step:** for multi-step requests, the agent first emits a short plan (a new stream event type in `stream_bridge.py`); the UI shows it as a checklist that ticks off as steps finish. - **Inline approvals:** when a tool needs approval, stream an `approval_required` event carrying the action from `ApprovalStore`; render Approve, Deny and "Always allow for this folder/command" buttons in the message. Keep `ApprovalBell` for background agents. - **Risk levels:** classify tools as read-only (no prompt), reversible write (prompt once per session or per folder) or irreversible/outward (always prompt: delete, send, purchase, system settings). Reuse `severity_policy.py` and `capabilities.py`. diff --git a/frontend/src/components/Chat/InputArea.tsx b/frontend/src/components/Chat/InputArea.tsx index 7a01c8b..8da9535 100644 --- a/frontend/src/components/Chat/InputArea.tsx +++ b/frontend/src/components/Chat/InputArea.tsx @@ -3,7 +3,7 @@ import { Send, Square, Paperclip, Search, Globe, Bot } from 'lucide-react'; import { toast } from 'sonner'; import { useAppStore, generateId } from '../../lib/store'; import { streamChat, streamResearch } from '../../lib/sse'; -import { fetchSavings, getBase } from '../../lib/api'; +import { fetchSavings, getBase, stopAgentRun } from '../../lib/api'; import { listConnectors, getSyncStatus } from '../../lib/connectors-api'; import { serializeToolCallArguments } from '../../lib/tool-call'; import { isSmallForAgent } from '../../lib/model-capabilities'; @@ -103,6 +103,8 @@ export function InputArea() { const [input, setInput] = useState(''); const textareaRef = useRef(null); const abortRef = useRef(null); + // Agent mode run being streamed, so Stop can end it on the server too. + const agentRunRef = useRef(null); const timerRef = useRef | null>(null); const activeId = useAppStore((s) => s.activeId); @@ -260,6 +262,10 @@ export function InputArea() { }, [input]); const stopStreaming = useCallback(() => { + if (agentRunRef.current) { + void stopAgentRun(agentRunRef.current).catch(() => {}); + agentRunRef.current = null; + } abortRef.current?.abort(); if (timerRef.current) { clearInterval(timerRef.current); @@ -343,6 +349,7 @@ export function InputArea() { const controller = new AbortController(); abortRef.current = controller; + agentRunRef.current = null; let accumulatedContent = ''; let usage: TokenUsage | undefined; @@ -538,6 +545,41 @@ export function InputArea() { : `Web search found ${sources.length} source(s)`, }); } catch {} + } else if (eventName === 'agent_run') { + try { + agentRunRef.current = JSON.parse(sseEvent.data).run_id ?? null; + } catch {} + } else if (eventName === 'approval_required') { + try { + const data = JSON.parse(sseEvent.data); + toolCalls.push({ + id: generateId(), + tool: data.tool, + arguments: serializeToolCallArguments(data.arguments), + status: 'awaiting_approval', + approvalId: data.id, + risk: data.risk, + }); + setStreamState({ + phase: 'Waiting for your approval...', + activeToolCalls: [...toolCalls], + }); + updateLastAssistant(convId, accumulatedContent, [...toolCalls]); + } catch {} + } else if (eventName === 'approval_resolved') { + try { + const data = JSON.parse(sseEvent.data); + const tc = toolCalls.find((t) => t.approvalId === data.id); + if (tc) { + tc.status = data.approved ? 'approved' : 'denied'; + if (data.timed_out) tc.result = 'No answer in time, so the agent skipped this step.'; + } + setStreamState({ + phase: data.approved ? `Calling ${data.tool}...` : 'Agent thinking...', + activeToolCalls: [...toolCalls], + }); + updateLastAssistant(convId, accumulatedContent, [...toolCalls]); + } catch {} } else if (eventName === 'agent_turn_start') { setStreamState({ phase: 'Agent thinking...' }); } else if (eventName === 'inference_start') { @@ -549,13 +591,18 @@ export function InputArea() { } else if (eventName === 'tool_call_start') { try { const data = JSON.parse(sseEvent.data); - const tc: ToolCallInfo = { - id: generateId(), - tool: data.tool, - arguments: serializeToolCallArguments(data.arguments), - status: 'running', - }; - toolCalls.push(tc); + // An approved call is already on screen; it starts running now. + const approved = toolCalls.find((t) => t.tool === data.tool && t.status === 'approved'); + if (approved) { + approved.status = 'running'; + } else { + toolCalls.push({ + id: generateId(), + tool: data.tool, + arguments: serializeToolCallArguments(data.arguments), + status: 'running', + }); + } setStreamState({ phase: `Calling ${data.tool}...`, activeToolCalls: [...toolCalls], @@ -627,6 +674,11 @@ export function InputArea() { // numbers don't get stuck on the last sample. useAppStore.getState().setLiveEnergy(null); } finally { + agentRunRef.current = null; + // A stopped run leaves no step waiting for an answer. + for (const tc of toolCalls) { + if (tc.status === 'awaiting_approval' || tc.status === 'approved') tc.status = 'denied'; + } if (!accumulatedContent) { accumulatedContent = 'No response was generated. Please try again.'; } diff --git a/frontend/src/components/Chat/ToolCallCard.test.ts b/frontend/src/components/Chat/ToolCallCard.test.ts new file mode 100644 index 0000000..fea84ab --- /dev/null +++ b/frontend/src/components/Chat/ToolCallCard.test.ts @@ -0,0 +1,26 @@ +import { describe, expect, it } from 'vitest'; + +import { describeToolCall } from './ToolCallCard'; + +describe('describeToolCall', () => { + it('shows the command for shell_exec', () => { + expect(describeToolCall('shell_exec', JSON.stringify({ command: 'dir' }))).toBe('Run `dir`'); + expect( + describeToolCall('shell_exec', JSON.stringify({ command: 'ls', working_dir: 'C:/x' })), + ).toBe('Run `ls` in C:/x'); + }); + + it('shows the path for file_write', () => { + expect(describeToolCall('file_write', JSON.stringify({ path: 'a.txt', content: 'x' }))).toBe( + 'Write a.txt', + ); + expect( + describeToolCall('file_write', JSON.stringify({ path: 'a.txt', mode: 'append' })), + ).toBe('Add to a.txt'); + }); + + it('falls back to the tool name', () => { + expect(describeToolCall('git_commit', '{"message":"m"}')).toBe('Use git_commit'); + expect(describeToolCall('shell_exec', 'not json')).toBe('Use shell_exec'); + }); +}); diff --git a/frontend/src/components/Chat/ToolCallCard.tsx b/frontend/src/components/Chat/ToolCallCard.tsx index 0341967..ac56e62 100644 --- a/frontend/src/components/Chat/ToolCallCard.tsx +++ b/frontend/src/components/Chat/ToolCallCard.tsx @@ -1,7 +1,9 @@ import { useState } from 'react'; -import { ChevronDown, ChevronRight, Loader2, CheckCircle2, XCircle } from 'lucide-react'; +import { ChevronDown, ChevronRight, Loader2, CheckCircle2, XCircle, ShieldQuestion, Ban } from 'lucide-react'; +import { toast } from 'sonner'; import type { ToolCallInfo } from '../../types'; import { serializeToolCallArguments } from '../../lib/tool-call'; +import { answerApproval, type ApprovalDecision } from '../../lib/api'; interface Props { toolCall: ToolCallInfo; @@ -11,8 +13,82 @@ const statusConfig = { running: { icon: Loader2, color: 'var(--color-accent)' }, success: { icon: CheckCircle2, color: 'var(--color-success)' }, error: { icon: XCircle, color: 'var(--color-error)' }, + awaiting_approval: { icon: ShieldQuestion, color: 'var(--color-warning, var(--color-accent))' }, + approved: { icon: Loader2, color: 'var(--color-accent)' }, + denied: { icon: Ban, color: 'var(--color-text-tertiary)' }, }; +/** What the agent wants to do, in words, for the approval prompt. */ +export function describeToolCall(tool: string, argumentsText: string): string { + let args: Record = {}; + try { + const parsed = JSON.parse(argumentsText); + if (parsed && typeof parsed === 'object') args = parsed; + } catch { + /* fall through */ + } + const text = (key: string) => (typeof args[key] === 'string' ? (args[key] as string) : ''); + if (tool === 'shell_exec' && text('command')) { + const where = text('working_dir'); + return where ? `Run \`${text('command')}\` in ${where}` : `Run \`${text('command')}\``; + } + if (tool === 'file_write' && text('path')) { + return text('mode') === 'append' ? `Add to ${text('path')}` : `Write ${text('path')}`; + } + return `Use ${tool}`; +} + +function ApprovalPrompt({ toolCall, argumentsText }: { toolCall: ToolCallInfo; argumentsText: string }) { + const [sending, setSending] = useState(false); + const answer = async (decision: ApprovalDecision) => { + if (!toolCall.approvalId) return; + setSending(true); + try { + const waiting = await answerApproval(toolCall.approvalId, decision); + if (!waiting) toast.error('This request is no longer waiting for an answer.'); + } catch (err: any) { + toast.error(err?.message || 'Could not send your answer.'); + } finally { + setSending(false); + } + }; + const button = (label: string, decision: ApprovalDecision, primary = false) => ( + + ); + return ( +
+
+ {toolCall.risk === 'run' ? 'Locus wants to run a command:' : 'Locus wants to make a change:'}{' '} + {describeToolCall(toolCall.tool, argumentsText)} +
+
+ {button('Allow', 'approve', true)} + {button(`Allow ${toolCall.tool} for this task`, 'approve_tool')} + {button('Deny', 'deny')} +
+
+ ); +} + function previewArgs(raw: string): string { if (!raw) return ''; try { @@ -34,7 +110,7 @@ function previewArgs(raw: string): string { export function ToolCallCard({ toolCall }: Props) { const [expanded, setExpanded] = useState(false); - const config = statusConfig[toolCall.status]; + const config = statusConfig[toolCall.status] ?? statusConfig.running; const StatusIcon = config.icon; // Persisted conversations may contain the pre-fix object payload despite // the TypeScript contract, so normalize again at the final render boundary. @@ -64,7 +140,7 @@ export function ToolCallCard({ toolCall }: Props) { )}
+ {toolCall.status === 'denied' && ( + + Denied + + )} {toolCall.latency != null && ( )} + {toolCall.status === 'awaiting_approval' && toolCall.approvalId && ( + + )} {expanded && (
=> setInferenceSource(src, { pending: true }); + +// ── Agent mode approvals ────────────────────────────────────── + +export type ApprovalDecision = 'approve' | 'approve_tool' | 'deny'; + +/** Answer an Agent mode approval. Returns false if it's no longer waiting. */ +export async function answerApproval(id: string, decision: ApprovalDecision): Promise { + const res = await apiFetch(`/v1/chat/approvals/${encodeURIComponent(id)}`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ decision }), + }); + if (res.status === 404) return false; + if (!res.ok) throw new Error(`Approval failed: ${res.status}`); + return true; +} + +/** Stop a running Agent mode task. */ +export async function stopAgentRun(runId: string): Promise { + await apiFetch(`/v1/chat/runs/${encodeURIComponent(runId)}/stop`, { method: 'POST' }); +} diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts index 1c08064..dff2663 100644 --- a/frontend/src/types/index.ts +++ b/frontend/src/types/index.ts @@ -39,9 +39,14 @@ export interface ToolCallInfo { id: string; tool: string; arguments: string; - status: 'running' | 'success' | 'error'; + /** `awaiting_approval` and `approved`/`denied` come from Agent mode approvals. */ + status: 'running' | 'success' | 'error' | 'awaiting_approval' | 'approved' | 'denied'; result?: string; latency?: number; + /** Id to answer with `answerApproval`, while the agent waits for the user. */ + approvalId?: string; + /** `change` writes something, `run` runs a command or code. */ + risk?: 'change' | 'run'; } export interface TokenUsage { diff --git a/src/locus/server/approvals.py b/src/locus/server/approvals.py new file mode 100644 index 0000000..c179c09 --- /dev/null +++ b/src/locus/server/approvals.py @@ -0,0 +1,218 @@ +"""In-chat approvals for Agent mode. + +Before the agent runs a tool that changes something, :func:`before_tool_call` +pauses the agent's thread, the chat stream sends an ``approval_required`` +event, and the agent waits until the user answers through +``POST /v1/chat/approvals/{id}`` (or the request is stopped). + +Each streamed agent run gets an :class:`ApprovalSession`, set in +:data:`current_session` before the run starts on its worker thread. Runs with +no session (non-streaming requests) can't ask, so risky tools are denied. +``POST /v1/chat/runs/{run_id}/stop`` cancels a session's run. +""" + +from __future__ import annotations + +import contextvars +import threading +import time +import uuid +from dataclasses import dataclass, field +from typing import Any, Callable, Dict, Literal, Optional + +Risk = Literal["read", "change", "run"] +Decision = Literal["approve", "approve_tool", "deny"] + +#: Tools that only read, or write to Locus's own memory. They never ask. +READ_ONLY_TOOLS = frozenset( + { + "think", + "calculator", + "file_read", + "pdf_extract", + "memory_manage", + "memory_search", + "memory_retrieve", + "knowledge_search", + "git_status", + "git_diff", + "git_log", + } +) + +#: Tools that run code or commands. Every call asks. +RUN_TOOLS = frozenset( + { + "shell_exec", + "docker_shell_exec", + "code_interpreter", + "code_interpreter_docker", + "repl", + } +) + +#: How long the agent waits for an answer before treating it as a no. +APPROVAL_TIMEOUT_SECONDS = 300.0 + + +def tool_risk(name: str, tool: Any = None) -> Risk: + """Classify a tool call. Unknown tools ask, so new tools fail closed.""" + spec = getattr(tool, "spec", None) + if name in RUN_TOOLS or getattr(spec, "requires_confirmation", False): + return "run" + if name in READ_ONLY_TOOLS: + return "read" + return "change" + + +class AgentCancelled(BaseException): + """Raised on the agent's thread to stop a run the user stopped. + + A ``BaseException`` so the orchestrator's ``except Exception`` around the + tool hook can't turn it into an ordinary denial and keep looping. + """ + + +@dataclass +class _Pending: + id: str + tool: str + answered: threading.Event = field(default_factory=threading.Event) + decision: Optional[Decision] = None + + +_pending: Dict[str, _Pending] = {} +_sessions: Dict[str, "ApprovalSession"] = {} +_pending_lock = threading.Lock() + + +def resolve(approval_id: str, decision: Decision) -> bool: + """Answer a pending approval. Returns ``False`` if it isn't waiting.""" + with _pending_lock: + pending = _pending.get(approval_id) + if pending is None or pending.answered.is_set(): + return False + pending.decision = decision + pending.answered.set() + return True + + +def stop_run(run_id: str) -> bool: + """Stop the run with *run_id*. Returns ``False`` if it isn't running.""" + with _pending_lock: + session = _sessions.get(run_id) + if session is None: + return False + session.cancel() + return True + + +class ApprovalSession: + """Approvals for one agent run. + + *emit* sends an SSE event (name, data) to this run's chat stream; it must + be safe to call from the agent's thread. + """ + + def __init__( + self, + emit: Callable[[str, dict], None], + *, + tools: Optional[Dict[str, Any]] = None, + timeout: float = APPROVAL_TIMEOUT_SECONDS, + ) -> None: + self._emit = emit + self._tools = tools or {} + self._timeout = timeout + self._allowed_tools: set[str] = set() + self._ids: set[str] = set() + self.cancelled = threading.Event() + self.run_id = uuid.uuid4().hex + + def __enter__(self) -> "ApprovalSession": + with _pending_lock: + _sessions[self.run_id] = self + return self + + def __exit__(self, *exc: Any) -> None: + with _pending_lock: + _sessions.pop(self.run_id, None) + + def cancel(self) -> None: + """Stop the run: deny anything waiting and every later tool call.""" + self.cancelled.set() + with _pending_lock: + waiting = [_pending[i] for i in self._ids if i in _pending] + for pending in waiting: + pending.answered.set() + + def check(self, tool_name: str, arguments: dict) -> bool: + """Return whether *tool_name* may run, asking the user if needed.""" + if self.cancelled.is_set(): + raise AgentCancelled() + risk = tool_risk(tool_name, self._tools.get(tool_name)) + if risk == "read" or tool_name in self._allowed_tools: + return True + + pending = _Pending(id=uuid.uuid4().hex, tool=tool_name) + with _pending_lock: + _pending[pending.id] = pending + self._ids.add(pending.id) + try: + self._emit( + "approval_required", + { + "id": pending.id, + "tool": tool_name, + "arguments": arguments, + "risk": risk, + "timeout_seconds": self._timeout, + }, + ) + deadline = time.monotonic() + self._timeout + while not pending.answered.wait(timeout=0.5): + if time.monotonic() >= deadline: + break + finally: + with _pending_lock: + _pending.pop(pending.id, None) + self._ids.discard(pending.id) + + if self.cancelled.is_set(): + raise AgentCancelled() + decision = pending.decision + approved = decision in ("approve", "approve_tool") + if decision == "approve_tool": + self._allowed_tools.add(tool_name) + self._emit( + "approval_resolved", + { + "id": pending.id, + "tool": tool_name, + "approved": approved, + "timed_out": decision is None, + }, + ) + return approved + + +current_session: contextvars.ContextVar[Optional[ApprovalSession]] = ( + contextvars.ContextVar("locus_approval_session", default=None) +) + + +def before_tool_call(tool_name: str, arguments: dict) -> bool: + """Orchestrator hook for the Agent mode agent.""" + session = current_session.get() + if session is None: + return tool_risk(tool_name) == "read" + return session.check(tool_name, arguments) + + +def confirm_after_approval(prompt: str) -> bool: + """Executor confirmation for tools marked ``requires_confirmation``. + + :func:`before_tool_call` has already asked the user (it runs first and + treats these tools as ``run``), so confirm only inside an approval session. + """ + return current_session.get() is not None diff --git a/src/locus/server/models.py b/src/locus/server/models.py index 5703865..8c8feee 100644 --- a/src/locus/server/models.py +++ b/src/locus/server/models.py @@ -49,6 +49,11 @@ class ChatCompletionRequest(BaseModel): mode: Optional[Literal["chat", "agent"]] = None +class ApprovalAnswer(BaseModel): + # "approve_tool" also approves later calls to the same tool in this run. + decision: Literal["approve", "approve_tool", "deny"] + + # --------------------------------------------------------------------------- # Response models # --------------------------------------------------------------------------- diff --git a/src/locus/server/routes.py b/src/locus/server/routes.py index 9a2c217..e1a367e 100644 --- a/src/locus/server/routes.py +++ b/src/locus/server/routes.py @@ -15,8 +15,10 @@ from locus.core.paths import get_config_dir from locus.core.types import Message, Role, ToolCall +from locus.server.approvals import AgentCancelled, ApprovalSession, current_session from locus.server.model_capabilities import is_embed_only_model from locus.server.models import ( + ApprovalAnswer, ChatCompletionChunk, ChatCompletionRequest, ChatCompletionResponse, @@ -514,6 +516,26 @@ async def chat_completions(request_body: ChatCompletionRequest, request: Request return response +@router.post("/v1/chat/approvals/{approval_id}") +async def answer_approval(approval_id: str, body: ApprovalAnswer): + """Answer an ``approval_required`` event from an Agent mode stream.""" + from locus.server.approvals import resolve + + if not resolve(approval_id, body.decision): + raise HTTPException(status_code=404, detail="No approval is waiting") + return {"id": approval_id, "decision": body.decision} + + +@router.post("/v1/chat/runs/{run_id}/stop") +async def stop_agent_run(run_id: str): + """Stop the agent run announced by an ``agent_run`` event.""" + from locus.server.approvals import stop_run + + if not stop_run(run_id): + raise HTTPException(status_code=404, detail="That run isn't running") + return {"run_id": run_id, "stopped": True} + + def _response_content(response) -> str: """Extract assistant text from an OpenAI-compatible response object.""" content = "" @@ -814,6 +836,12 @@ def _handle_agent( ) +def _sse_event(name: str, data: dict) -> str: + import json + + return f"event: {name}\ndata: {json.dumps(data, default=str)}\n\n" + + def _forward_agent_events(bus, agent, loop, queue: asyncio.Queue): """Queue *agent*'s turn and tool events from *bus* as SSE strings. @@ -849,8 +877,7 @@ def callback(event): # The UI expects arguments as JSON text, as the bus carries # them parsed for trace consumers. data = {**data, "arguments": json.dumps(data.get("arguments"))} - sse = f"event: {name}\ndata: {json.dumps(data, default=str)}\n\n" - loop.call_soon_threadsafe(queue.put_nowait, sse) + loop.call_soon_threadsafe(queue.put_nowait, _sse_event(name, data)) return callback @@ -906,24 +933,60 @@ async def generate(): loop = asyncio.get_running_loop() live_events: asyncio.Queue = asyncio.Queue() unsubscribe = _forward_agent_events(bus, agent, loop, live_events) - task = asyncio.ensure_future( - asyncio.to_thread( - _handle_agent, - agent, - model, - req, - complexity_info, - trace_store=trace_store, - bus=bus, - ) - ) - task.add_done_callback( - lambda _f: loop.call_soon_threadsafe(live_events.put_nowait, None) - ) + + # Tool calls that change something wait here for the user's answer. + def emit(name: str, data: dict) -> None: + loop.call_soon_threadsafe(live_events.put_nowait, _sse_event(name, data)) + + tools = { + spec.name: tool + for tool in getattr(agent, "_tools", None) or [] + if (spec := getattr(tool, "spec", None)) is not None + } + session = ApprovalSession(emit, tools=tools) + + def run_agent(): + with session: + token = current_session.set(session) + try: + return _handle_agent( + agent, + model, + req, + complexity_info, + trace_store=trace_store, + bus=bus, + ) + finally: + current_session.reset(token) + + yield _sse_event("agent_run", {"run_id": session.run_id}) + task = asyncio.ensure_future(asyncio.to_thread(run_agent)) + + def on_done(future): + if not future.cancelled(): + future.exception() # retrieved here; re-raised by result() + loop.call_soon_threadsafe(live_events.put_nowait, None) + + task.add_done_callback(on_done) try: while (event := await live_events.get()) is not None: yield event response = task.result() + except AgentCancelled: + stopped_chunk = ChatCompletionChunk( + id=chunk_id, + model=model, + choices=[ + StreamChoice( + delta=DeltaMessage(content="Stopped."), + finish_reason="stop", + ) + ], + ) + yield f"data: {stopped_chunk.model_dump_json()}\n\n" + yield "data: [DONE]\n\n" + return except Exception as exc: logging.getLogger("locus.server").error( "Agent stream error: %s", @@ -947,6 +1010,9 @@ async def generate(): return finally: unsubscribe() + # The client stopped or went away: end the run at its next tool call. + if not task.done(): + session.cancel() content = _response_content(response) if content: diff --git a/src/locus/server/task_agent.py b/src/locus/server/task_agent.py index 03bff0f..3913ac6 100644 --- a/src/locus/server/task_agent.py +++ b/src/locus/server/task_agent.py @@ -1,9 +1,9 @@ """The tool-using agent behind the chat's Agent mode. -When the server's configured agent already has tools, Agent mode uses it. -Otherwise (the desktop app serves with ``--agent simple``) a separate -``orchestrator`` is built on first use with :data:`ASSISTANT_TOOLS` and cached -on ``app.state``. +Agent mode always uses its own ``orchestrator``, built on first use with +:data:`ASSISTANT_TOOLS` and cached on ``app.state``, rather than the server's +configured agent: only this agent asks the user before tools that change +something (see ``server/approvals.py``). """ from __future__ import annotations @@ -15,30 +15,31 @@ logger = logging.getLogger("locus.server") -# Tools that can't change anything outside Locus's own memory. Writing files, -# running commands and network access wait for in-chat approvals. +# Tools that change something (writing files, running commands) ask in the +# chat before each call; see ``server/approvals.py``. Network access waits. ASSISTANT_TOOLS = ( "think", "calculator", "file_read", "pdf_extract", "memory_manage", + "git_status", + "git_diff", + "git_log", + "file_write", + "shell_exec", ) +#: Agent mode tasks take more steps than chat; ``agent.max_turns`` can raise it. +MIN_MAX_TURNS = 25 + ASSISTANT_AGENT_ID = "assistant" _build_lock = threading.Lock() -def has_tools(agent: Any) -> bool: - return agent is not None and bool(getattr(agent, "_tools", None)) - - def get_task_agent(state: Any) -> Optional[Any]: - """Return a tool-using agent for *state* (``app.state``), or ``None``.""" - configured = getattr(state, "agent", None) - if has_tools(configured): - return configured + """Return the Agent mode agent for *state* (``app.state``), or ``None``.""" cached = getattr(state, "task_agent", None) if cached is not None: return cached @@ -73,7 +74,7 @@ def _assistant_tools(config: Any) -> list: kwargs = file_tool_kwargs(name, config) # An empty allow-list means "anywhere"; keep Agent mode in the home # folder unless the user configured something narrower or wider. - if name == "file_read" and not kwargs.get("allowed_dirs"): + if name in ("file_read", "file_write") and not kwargs.get("allowed_dirs"): kwargs["allowed_dirs"] = [str(Path.home())] tools.append(tool_cls(**kwargs)) return tools @@ -85,6 +86,7 @@ def _build_task_agent(state: Any) -> Any: import locus.agents # noqa: F401 # trigger registration from locus.core.registry import AgentRegistry from locus.security.runtime import agent_security_kwargs, wire_agent_security + from locus.server.approvals import before_tool_call, confirm_after_approval config = getattr(state, "config", None) bus = getattr(state, "bus", None) @@ -96,9 +98,18 @@ def _build_task_agent(state: Any) -> Any: "bus": bus, "tools": _assistant_tools(config), "agent_id": ASSISTANT_AGENT_ID, + "max_turns": MIN_MAX_TURNS, + "before_tool_call": before_tool_call, + # The hook asks the user first, so the executor may run tools marked + # requires_confirmation (shell_exec) once they're approved. + "interactive": True, + "confirm_callback": confirm_after_approval, + # Approvals are tracked per run on the agent's thread; parallel tool + # threads wouldn't see the run's approval session. + "parallel_tools": False, } if config is not None: - kwargs["max_turns"] = config.agent.max_turns + kwargs["max_turns"] = max(config.agent.max_turns, MIN_MAX_TURNS) if "prompt_builder" in inspect.signature(agent_cls.__init__).parameters: from locus.prompt.builder import SystemPromptBuilder diff --git a/tests/server/test_agent_approvals.py b/tests/server/test_agent_approvals.py new file mode 100644 index 0000000..7ccdf3b --- /dev/null +++ b/tests/server/test_agent_approvals.py @@ -0,0 +1,319 @@ +"""In-chat approvals for Agent mode (``server/approvals.py``).""" + +from __future__ import annotations + +import json +import threading +from types import SimpleNamespace + +import pytest + +fastapi = pytest.importorskip("fastapi") + +from fastapi.testclient import TestClient # noqa: E402 + +from locus.agents._stubs import AgentResult # noqa: E402 +from locus.server import approvals, task_agent # noqa: E402 +from locus.server.app import create_app # noqa: E402 +from locus.server.approvals import ( # noqa: E402 + AgentCancelled, + ApprovalSession, + before_tool_call, + confirm_after_approval, + tool_risk, +) + + +def _config(): + from locus.core.config import JarvisConfig + + cfg = JarvisConfig() + cfg.analytics.enabled = False + cfg.traces.enabled = False + cfg.security.enabled = False + cfg.agent.context_from_memory = False + return cfg + + +class Recorder: + """An ``emit`` that records events and can answer approvals as they come.""" + + def __init__(self, answer=None): + self.events: list[tuple[str, dict]] = [] + self.answer = answer + + def __call__(self, name, data): + self.events.append((name, data)) + if name == "approval_required" and self.answer is not None: + approvals.resolve(data["id"], self.answer) + + def names(self): + return [name for name, _ in self.events] + + +# ── Risk levels ────────────────────────────────────────────────── + + +@pytest.mark.parametrize( + "name, risk", + [ + ("file_read", "read"), + ("think", "read"), + ("git_status", "read"), + ("file_write", "change"), + ("git_commit", "change"), + ("some_new_tool", "change"), + ("shell_exec", "run"), + ("code_interpreter", "run"), + ], +) +def test_tool_risk(name, risk): + assert tool_risk(name) == risk + + +def test_tools_marked_requires_confirmation_always_run_level(): + tool = SimpleNamespace(spec=SimpleNamespace(requires_confirmation=True)) + assert tool_risk("file_read", tool) == "run" + + +def test_without_a_session_only_read_tools_run(): + assert before_tool_call("file_read", {}) is True + assert before_tool_call("file_write", {"path": "a"}) is False + assert before_tool_call("shell_exec", {"command": "ls"}) is False + assert confirm_after_approval("Allow shell_exec?") is False + + +# ── Approval sessions ──────────────────────────────────────────── + + +def test_read_tools_never_ask(): + emit = Recorder() + assert ApprovalSession(emit).check("file_read", {"path": "a"}) is True + assert emit.events == [] + + +@pytest.mark.parametrize( + "answer, allowed", [("approve", True), ("approve_tool", True), ("deny", False)] +) +def test_answer_decides_the_call(answer, allowed): + emit = Recorder(answer=answer) + session = ApprovalSession(emit) + + assert session.check("shell_exec", {"command": "ls"}) is allowed + + assert emit.names() == ["approval_required", "approval_resolved"] + required, resolved = emit.events[0][1], emit.events[1][1] + assert required["tool"] == "shell_exec" + assert required["arguments"] == {"command": "ls"} + assert required["risk"] == "run" + assert resolved == { + "id": required["id"], + "tool": "shell_exec", + "approved": allowed, + "timed_out": False, + } + + +def test_approve_tool_covers_later_calls_in_the_same_run(): + emit = Recorder(answer="approve_tool") + session = ApprovalSession(emit) + + assert session.check("file_write", {"path": "a"}) is True + assert session.check("file_write", {"path": "b"}) is True + assert emit.names().count("approval_required") == 1 + # Other tools, and other runs, still ask. + emit.answer = "deny" + assert session.check("shell_exec", {"command": "ls"}) is False + assert ApprovalSession(emit).check("file_write", {"path": "c"}) is False + + +def test_approve_covers_only_that_call(): + emit = Recorder(answer="approve") + session = ApprovalSession(emit) + + session.check("file_write", {"path": "a"}) + session.check("file_write", {"path": "b"}) + + assert emit.names().count("approval_required") == 2 + + +def test_no_answer_in_time_is_a_no(): + emit = Recorder() + session = ApprovalSession(emit, timeout=0.05) + + assert session.check("file_write", {"path": "a"}) is False + assert emit.events[-1][1]["timed_out"] is True + # Nothing is left waiting. + assert approvals.resolve(emit.events[0][1]["id"], "approve") is False + + +def test_stopping_while_waiting_ends_the_run(): + emit = Recorder() + session = ApprovalSession(emit) + raised = [] + + def run(): + try: + session.check("shell_exec", {"command": "ls"}) + except AgentCancelled: + raised.append(True) + + worker = threading.Thread(target=run) + worker.start() + while not emit.events: + worker.join(0.01) + with session: + assert approvals.stop_run(session.run_id) is True + worker.join(2) + + assert raised == [True] + with pytest.raises(AgentCancelled): + session.check("file_read", {}) + + +def test_unknown_ids_are_not_waiting(): + assert approvals.resolve("nope", "approve") is False + assert approvals.stop_run("nope") is False + + +# ── Through the chat stream ────────────────────────────────────── + + +class AskingAgent: + """Calls the approval hook the way the orchestrator does before each tool.""" + + agent_id = "asking" + + def __init__(self, calls): + # Streams only go to agents that have tools. + self._tools = [object()] + self._model = "test-model" + self._calls = calls + self.results: list[bool] = [] + + def run(self, input, context=None): + for name, args in self._calls: + self.results.append(before_tool_call(name, args)) + return AgentResult(content=f"allowed={self.results}") + + +def _app(monkeypatch, agent): + monkeypatch.setattr(task_agent, "_build_task_agent", lambda state: agent) + engine = SimpleNamespace(engine_id="mock", health=lambda: True) + return create_app(engine, "test-model", config=_config()) + + +def _stream(client): + """Run an Agent mode stream; return its event names and answer text.""" + body = { + "model": "test-model", + "messages": [{"role": "user", "content": "do it"}], + "stream": True, + "mode": "agent", + } + resp = client.post("/v1/chat/completions", json=body) + names, content, name = [], "", None + for line in resp.text.split("\n"): + if line.startswith("event: "): + name = line[7:].strip() + elif line.startswith("data: ") and line[6:] != "[DONE]": + data = json.loads(line[6:]) + if name: + names.append(name) + else: + for choice in data.get("choices", []): + content += choice.get("delta", {}).get("content") or "" + name = None + return names, content + + +def _when_waiting(action): + """Call ``action(approval_id, run_id)`` once an approval is waiting. + + The test client buffers the whole response, so answers come from another + thread, the way the UI answers while the stream is open. + """ + import time + + def watch(): + deadline = time.monotonic() + 5 + while time.monotonic() < deadline: + with approvals._pending_lock: + pending = next(iter(approvals._pending), None) + run_id = next(iter(approvals._sessions), None) + if pending and run_id: + action(pending, run_id) + return + time.sleep(0.01) + + thread = threading.Thread(target=watch, daemon=True) + thread.start() + return thread + + +@pytest.mark.parametrize("decision, allowed", [("approve", True), ("deny", False)]) +def test_stream_asks_and_waits_for_the_answer(monkeypatch, decision, allowed): + agent = AskingAgent([("file_read", {}), ("file_write", {"path": "a.txt"})]) + client = TestClient(_app(monkeypatch, agent)) + answers = [] + watcher = _when_waiting( + lambda approval_id, _run: answers.append( + client.post( + f"/v1/chat/approvals/{approval_id}", json={"decision": decision} + ).status_code + ) + ) + + names, content = _stream(client) + watcher.join(5) + + assert answers == [200] + assert names[0] == "agent_run" + assert names.count("approval_required") == 1 + assert "approval_resolved" in names + assert agent.results == [True, allowed] + assert content == f"allowed={[True, allowed]}" + + +def test_stop_ends_the_run(monkeypatch): + agent = AskingAgent([("shell_exec", {"command": "ls"}), ("file_read", {})]) + client = TestClient(_app(monkeypatch, agent)) + stops = [] + watcher = _when_waiting( + lambda _approval, run_id: stops.append( + (run_id, client.post(f"/v1/chat/runs/{run_id}/stop").status_code) + ) + ) + + _, content = _stream(client) + watcher.join(5) + + assert [code for _, code in stops] == [200] + assert content == "Stopped." + assert agent.results == [] + assert client.post(f"/v1/chat/runs/{stops[0][0]}/stop").status_code == 404 + + +def test_answering_a_finished_approval_is_404(monkeypatch): + client = TestClient(_app(monkeypatch, AskingAgent([]))) + resp = client.post("/v1/chat/approvals/gone", json={"decision": "approve"}) + assert resp.status_code == 404 + resp = client.post("/v1/chat/approvals/gone", json={"decision": "maybe"}) + assert resp.status_code == 422 + + +def test_non_streaming_agent_mode_denies_changes(monkeypatch): + agent = AskingAgent([("file_read", {}), ("file_write", {"path": "a.txt"})]) + client = TestClient(_app(monkeypatch, agent)) + + resp = client.post( + "/v1/chat/completions", + json={ + "model": "test-model", + "messages": [{"role": "user", "content": "do it"}], + "mode": "agent", + }, + ) + + assert resp.status_code == 200 + assert agent.results == [True, False] diff --git a/tests/server/test_agent_mode.py b/tests/server/test_agent_mode.py index 90959c9..ae6989f 100644 --- a/tests/server/test_agent_mode.py +++ b/tests/server/test_agent_mode.py @@ -125,14 +125,22 @@ def test_chat_mode_skips_the_configured_tool_agent(): assert _content(resp) == "Hi!" -def test_agent_mode_reuses_a_configured_tool_agent(): +def test_agent_mode_uses_its_own_agent_even_when_the_configured_one_has_tools( + monkeypatch, +): + # Only the Agent mode agent asks before tools that change something. bus = EventBus() - agent = FakeAgent(bus=bus) - app = create_app(_engine([]), "test-model", agent=agent, bus=bus, config=_config()) + configured = FakeAgent(bus=bus) + built = FakeAgent(bus=bus) + monkeypatch.setattr(task_agent, "_build_task_agent", lambda state: built) + app = create_app( + _engine([]), "test-model", agent=configured, bus=bus, config=_config() + ) resp = _post(TestClient(app), mode="agent") - assert agent.inputs == ["read a.txt"] + assert configured.inputs == [] + assert built.inputs == ["read a.txt"] assert _content(resp) == "Done." @@ -158,10 +166,11 @@ def test_agent_mode_builds_an_agent_when_the_configured_one_has_none(monkeypatch assert seen -def test_agent_mode_streams_only_its_own_tool_events(): +def test_agent_mode_streams_only_its_own_tool_events(monkeypatch): bus = EventBus() agent = FakeAgent(bus=bus) - app = create_app(_engine([]), "test-model", agent=agent, bus=bus, config=_config()) + monkeypatch.setattr(task_agent, "_build_task_agent", lambda state: agent) + app = create_app(_engine([]), "test-model", bus=bus, config=_config()) events = _events(_post(TestClient(app), mode="agent")) @@ -209,13 +218,15 @@ def broken(state): assert _content(resp) == "Hi!" -def test_built_agent_uses_read_only_tools_kept_in_home(monkeypatch): +def test_built_agent_asks_before_changes_and_stays_in_home(monkeypatch): # The shared conftest clears registries between tests. from locus.agents.orchestrator import OrchestratorAgent from locus.core.registry import AgentRegistry, ToolRegistry from locus.tools.calculator import CalculatorTool from locus.tools.file_read import FileReadTool from locus.tools.file_write import FileWriteTool + from locus.tools.http_request import HttpRequestTool + from locus.tools.shell_exec import ShellExecTool from locus.tools.think import ThinkTool AgentRegistry.register_value("orchestrator", OrchestratorAgent) @@ -224,6 +235,8 @@ def test_built_agent_uses_read_only_tools_kept_in_home(monkeypatch): ("calculator", CalculatorTool), ("file_read", FileReadTool), ("file_write", FileWriteTool), + ("shell_exec", ShellExecTool), + ("http_request", HttpRequestTool), ]: ToolRegistry.register_value(name, cls) @@ -240,10 +253,16 @@ def test_built_agent_uses_read_only_tools_kept_in_home(monkeypatch): agent = task_agent._build_task_agent(state) + from locus.server.approvals import before_tool_call + names = {tool.spec.name for tool in agent._tools} assert names <= set(task_agent.ASSISTANT_TOOLS) - assert {"think", "calculator", "file_read"} <= names - assert not names & {"file_write", "shell_exec", "web_search", "http_request"} - file_read = next(t for t in agent._tools if t.spec.name == "file_read") - assert file_read._allowed_dirs == [Path.home().resolve()] + assert {"think", "calculator", "file_read", "file_write", "shell_exec"} <= names + assert not names & {"web_search", "http_request"} + for name in ("file_read", "file_write"): + tool = next(t for t in agent._tools if t.spec.name == name) + assert tool._allowed_dirs == [Path.home().resolve()] + assert agent._before_tool_call is before_tool_call + assert agent._parallel_tools is False + assert agent._max_turns >= task_agent.MIN_MAX_TURNS assert task_agent.ASSISTANT_AGENT_ID in task_agent.agent_event_ids(agent)