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)