diff --git a/README.md b/README.md index 91827d8..a2cbe37 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,9 @@ Locus is that stack. It is a framework for local-first personal AI, built around - **Attach files and images:** drop documents (PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, HTML, CSV, code, plain text and more) or images into a chat and ask about them. Images need a vision model such as `qwen3.5` or `gemma3`. - **Search the web:** turn on **Web search** and Locus looks up your question online first, reads the top pages, and answers with numbered links to its sources. It's off until you turn it on, since it sends your question to a search engine. - **Work with your files:** read and write files and PDFs, search your own documents, run code in a sandbox, and remember facts between conversations. +- **Control your PC:** in Agent mode, open apps, files and folders, arrange windows, change the volume, brightness and theme, switch Wi-Fi and Bluetooth, lock the screen, use the clipboard, take screenshots, and set reminders. Locus shows its plan, asks in the chat before anything that changes something, and lets you undo file changes. +- **Hands-free voice:** press Ctrl+Shift+L (Cmd+Shift+L on a Mac), speak, and Locus answers aloud when you stop talking. +- **Developer mode:** point Agent mode at a project folder to read and edit code, run tests and fix failures, and work on a git branch, with a diff to approve before each change. - **Connect your apps:** Gmail, Outlook, Google Calendar, Google Drive, Dropbox, Notion, Obsidian, GitHub, Slack and more, each only after you sign in. - **Reply on messaging apps:** run it as a bot on Telegram, Slack, Discord, WhatsApp, Teams, Signal, email, SMS and about 25 other channels. - **Do tasks on its own:** deep research reports, a daily morning digest, and agents that run on a schedule. diff --git a/docs/design/2026-11-08-agent-mode-plan.md b/docs/design/2026-11-08-agent-mode-plan.md index fea6a03..974b67b 100644 --- a/docs/design/2026-11-08-agent-mode-plan.md +++ b/docs/design/2026-11-08-agent-mode-plan.md @@ -69,6 +69,8 @@ Most of the agent machinery is in the repo. The gap is mostly wiring and UX. **Goal:** attachments, images and web search work in agent mode instead of silently falling back to plain chat. +> **Status (2026-11-08): implemented.** `_handle_agent` folds attached documents into each message's text (the same budget as direct chat), and the latest message's images reach the agent through `AgentContext.metadata["input_images"]`, which `BaseAgent._build_messages` puts on the final user message. Web results stay a pre-search, so the UI keeps its numbered sources: the web-context system message joins the agent's single system prompt. In Agent mode, requests with these extras no longer fall back to plain chat. Requests that don't use Agent mode route as before. + - Turn attachments into agent context: attached document text goes in as context or as a `file_read`-style handle; images go to vision models as today. - Expose web search to the agent as its normal `web_search` tool when the toggle is on, rather than pre-injecting results. The agent decides when to search, and the privacy rule stays the same (off unless the user turns it on). - Remove the `has_extras` bypass in `routes.py` once both paths are covered. @@ -79,13 +81,16 @@ 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: +> **Status (2026-11-08): implemented.** 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 checklist:** a `task_plan` tool (never asks) that the agent calls before multi-step work and as steps finish. The chat shows the latest call as a checklist instead of a tool card. +> - **Undo:** Agent mode's `file_write` is `UndoableFileWriteTool` (`tools/undo_journal.py`). It saves the old contents under `~/.locus/undo` and returns an `undo_id`, the tool card shows Undo, and `POST /v1/chat/undo/{id}` puts the file back or deletes a file the agent created, only while it still holds what the agent wrote. Files over 10 MB aren't backed up; the last 100 changes are kept. +> - **"Always allow":** for change-level steps only, keyed by tool or `tool:action`, in `~/.locus/agent_permissions.json`. Settings > Agent mode lists and removes rules (`GET`/`DELETE /v1/chat/permissions`). Commands and code never get lasting rules. Approvals can also carry a `preview` from the tool's `preview_for()`, such as a file diff. +> - **Continue:** a stopped Agent mode reply says what was finished and shows Continue, which turns Agent mode on and asks the agent to pick up where it stopped. - **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. @@ -100,6 +105,23 @@ Most of the agent machinery is in the repo. The gap is mostly wiring and UX. **Goal:** the agent can operate the computer, not only files and the browser. +> **Status (2026-11-08): implemented (Windows fully; macOS and Linux partly).** As built, in `src/locus/tools/desktop/`: +> - **Shared OS layer:** `_os.py` runs commands without a shell. Values from the model reach PowerShell only as `LOCUS_ARG_*` environment variables, or other commands as separate arguments, so a title or name can't inject a command. No new dependencies: Windows uses PowerShell, `ctypes` and `winreg`. +> - **Per-call risk:** tools can define `risk_for(arguments)`, so listing windows doesn't ask but closing an app does. `server/approvals.py` uses it; `requires_confirmation` still forces `run`. +> +> | Tool | Actions | Asks? | Windows | macOS | Linux | +> |---|---|---|---|---|---| +> | `open_path` | Open a file, folder or http(s) link | Files: no. Programs (`.exe`, `.ps1`, `.lnk`…): always. Links: yes | Yes | Yes | Yes (`xdg-open`) | +> | `app_control` | list, open, close (graceful, like clicking X) | list: no. open/close: yes | Yes | Yes | open only | +> | `window_control` | list, focus, minimize, maximize, restore (by title) | No | Yes | Not yet | Not yet | +> | `system_control` | get/set volume, mute, unmute, brightness, dark/light mode, lock screen | get_volume: no. Rest: yes | Yes (brightness on laptops) | No brightness | Volume (`pactl`), lock | +> | `clipboard` | read, write | Yes (reading can expose private text) | Yes | Yes | With `wl-clipboard` or `xclip` | +> | `notify` | Notification now, or a timer/reminder up to 24h | No | Yes (toast) | Yes | Yes (`notify-send`) | +> | `screenshot` | Whole screen to `~/.locus/screenshots` | Yes | Yes | Yes | With `gnome-screenshot` or `grim` | +> +> - **Added later the same day:** Wi-Fi and Bluetooth (`system_control` `get_radios`, `wifi_on/off`, `bluetooth_on/off`; Windows.Devices.Radios without admin rights, `networksetup` and `blueutil` on macOS, `nmcli` and `rfkill` on Linux). Window control on macOS (System Events; needs Accessibility permission) and Linux (`wmctrl`, X11 only). Reminders saved in `~/.locus/reminders.json` and restored when `locus serve` starts, with missed ones shown at once, plus `list_reminders` and `cancel_reminder`. +> - **Not done yet:** moving and snapping windows, window control on Wayland, and sending screenshots to vision models. + New tools under `src/locus/tools/desktop/`, one module per OS behind a common interface (Windows first, since that's where the desktop app is most used, then macOS, then Linux): | Tool | Actions | Risk | @@ -119,6 +141,8 @@ New tools under `src/locus/tools/desktop/`, one module per OS behind a common in ### Phase 5: hands-free voice loop +> **Status (2026-11-08): implemented, except a wake word.** Settings > Speech > Hands-free voice turns on Ctrl+Shift+L (Cmd+Shift+L on a Mac): in the window, and system-wide in the desktop app, which raises its window first (new `core:window` permissions). `lib/vad.ts` learns the noise floor, ends the turn after 1.2 s of quiet, cancels after 8 s of silence, and caps a turn at 30 s. The transcript is sent through the prompt queue and the reply is read aloud even with autoplay off. Pressing the shortcut during a spoken reply interrupts it and listens. Not built: a wake word, voice answers to approvals, and listening for the user talking over a reply (interrupting is by shortcut). + **Goal:** talk to Locus without touching the keyboard. - **Activation:** a global hotkey (Tauri global shortcut) that opens the overlay and starts listening; an optional local wake word (for example openWakeWord) behind a setting, off by default. @@ -132,6 +156,8 @@ New tools under `src/locus/tools/desktop/`, one module per OS behind a common in ### Phase 6: developer mode +> **Status (2026-11-08): implemented.** The Project button beside Agent picks a folder; requests then use `mode: "developer"` with `project_dir` (`server/developer.py`, one cached agent per folder). File, git and shell tools stay in the project, file edits show a diff and can be undone, and `command_risk` lets tests, linters and git status/diff/log/show run without asking while anything else (or anything with shell operators) asks every time. Commits always ask. The prompt asks for a branch before the first change, tests after changes (fixing failures up to 3 times), and no pushes. `apply_patch` isn't included (it has no folder limit); edits use `file_write` with a diff instead. No `developer` preset: it would run without the approval hook under `locus serve`. + **Goal:** a strong local coding agent built on the existing tools. - A `developer` preset: `native_openhands` or `orchestrator` with `shell_exec`, `apply_patch`, `git_tool`, `file_read`/`file_write`, `code_interpreter_docker`, `http_request`, `db_query`, MCP. diff --git a/frontend/src-tauri/capabilities/default.json b/frontend/src-tauri/capabilities/default.json index ec113f3..b37177e 100644 --- a/frontend/src-tauri/capabilities/default.json +++ b/frontend/src-tauri/capabilities/default.json @@ -8,6 +8,9 @@ "notification:default", "global-shortcut:allow-register", "global-shortcut:allow-unregister", + "core:window:allow-show", + "core:window:allow-unminimize", + "core:window:allow-set-focus", "autostart:allow-enable", "autostart:allow-disable", "autostart:allow-is-enabled", diff --git a/frontend/src/components/Chat/AgentPermissionsList.tsx b/frontend/src/components/Chat/AgentPermissionsList.tsx new file mode 100644 index 0000000..19ffdbe --- /dev/null +++ b/frontend/src/components/Chat/AgentPermissionsList.tsx @@ -0,0 +1,88 @@ +import { useCallback, useEffect, useState } from 'react'; +import { toast } from 'sonner'; +import { fetchAgentPermissions, removeAgentPermission, type AgentPermission } from '../../lib/api'; + +const ACTION_WORDS: Record = { + set_volume: 'set the volume', + mute: 'mute', + unmute: 'unmute', + set_brightness: 'set the brightness', + dark_mode: 'switch to dark mode', + light_mode: 'switch to light mode', + lock_screen: 'lock the screen', + wifi_on: 'turn Wi-Fi on', + wifi_off: 'turn Wi-Fi off', + bluetooth_on: 'turn Bluetooth on', + bluetooth_off: 'turn Bluetooth off', + open: 'open', + close: 'close', + read: 'read', + write: 'write', +}; + +/** A rule in words, like "system_control: set the volume". */ +export function describeRule(rule: AgentPermission): string { + if (!rule.action) return `${rule.tool}: any use`; + return `${rule.tool}: ${ACTION_WORDS[rule.action] ?? rule.action}`; +} + +/** Agent mode's "always allow" rules, each with a Remove button. */ +export function AgentPermissionsList() { + const [rules, setRules] = useState(null); + const [error, setError] = useState(null); + + const load = useCallback(() => { + fetchAgentPermissions() + .then((r) => { + setRules(r); + setError(null); + }) + .catch((err) => setError(err?.message || 'Could not load the rules.')); + }, []); + + useEffect(load, [load]); + + const remove = async (key: string) => { + try { + await removeAgentPermission(key); + setRules((prev) => (prev ?? []).filter((r) => r.key !== key)); + } catch (err: any) { + toast.error(err?.message || 'Could not remove the rule.'); + } + }; + + if (error) { + return
{error}
; + } + if (rules === null) { + return
Loading…
; + } + if (rules.length === 0) { + return ( +
+ No steps are always allowed. Choose Always allow on an approval to add one. Commands and code always ask. +
+ ); + } + return ( +
    + {rules.map((rule) => ( +
  • + {describeRule(rule)} + +
  • + ))} +
+ ); +} diff --git a/frontend/src/components/Chat/ChatArea.tsx b/frontend/src/components/Chat/ChatArea.tsx index ed886b0..bdabe19 100644 --- a/frontend/src/components/Chat/ChatArea.tsx +++ b/frontend/src/components/Chat/ChatArea.tsx @@ -62,7 +62,10 @@ export function ChatArea() { streamingConversationRef.current = isCurrentChatStreaming ? activeId : null; if (!justFinished) return; - if (!voiceOutputEnabled || !voiceAutoplay) return; + // A hands-free turn always hears its reply; otherwise follow the settings. + const handsFreeTurn = useAppStore.getState().speakNextReply; + if (handsFreeTurn) useAppStore.getState().setSpeakNextReply(false); + if (!handsFreeTurn && (!voiceOutputEnabled || !voiceAutoplay)) return; if (!last || last.role !== 'assistant' || activeId === null) return; @@ -75,7 +78,7 @@ export function ChatArea() { const currentTts = useTtsStore.getState(); const currentLast = app.messages[app.messages.length - 1]; if (app.activeId !== completedConversationId || app.streamState.isStreaming) return; - if (!app.settings.voiceOutputEnabled || !app.settings.voiceAutoplay) return; + if (!handsFreeTurn && (!app.settings.voiceOutputEnabled || !app.settings.voiceAutoplay)) return; if (currentLast?.id !== completedMessageId || currentTts.available !== true) return; if (currentTts.autoSpokenId === completedMessageId) return; diff --git a/frontend/src/components/Chat/InputArea.tsx b/frontend/src/components/Chat/InputArea.tsx index 8da9535..9ba845d 100644 --- a/frontend/src/components/Chat/InputArea.tsx +++ b/frontend/src/components/Chat/InputArea.tsx @@ -1,12 +1,13 @@ import { useState, useRef, useCallback, useEffect } from 'react'; -import { Send, Square, Paperclip, Search, Globe, Bot } from 'lucide-react'; +import { Send, Square, Paperclip, Search, Globe, Bot, FolderCode, X } from 'lucide-react'; import { toast } from 'sonner'; import { useAppStore, generateId } from '../../lib/store'; import { streamChat, streamResearch } from '../../lib/sse'; -import { fetchSavings, getBase, stopAgentRun } from '../../lib/api'; +import { fetchSavings, getBase, isTauri, stopAgentRun } from '../../lib/api'; import { listConnectors, getSyncStatus } from '../../lib/connectors-api'; import { serializeToolCallArguments } from '../../lib/tool-call'; import { isSmallForAgent } from '../../lib/model-capabilities'; +import { stoppedSummary } from '../../lib/agent-stop'; import { engineFromCompletionChunk, resolveChatEngine, @@ -14,6 +15,7 @@ import { import { MicButton } from './MicButton'; import { AttachmentChip } from './AttachmentChip'; import { useSpeech } from '../../hooks/useSpeech'; +import { useHandsFree } from '../../hooks/useHandsFree'; import { apiAttachmentFields, deletePayloads, @@ -105,6 +107,8 @@ export function InputArea() { const abortRef = useRef(null); // Agent mode run being streamed, so Stop can end it on the server too. const agentRunRef = useRef(null); + // Set when the user stops an Agent mode run (not a model switch). + const stoppedByUserRef = useRef(false); const timerRef = useRef | null>(null); const activeId = useAppStore((s) => s.activeId); @@ -127,6 +131,8 @@ export function InputArea() { const setLastAssistantWebSearch = useAppStore((s) => s.setLastAssistantWebSearch); const agentMode = useAppStore((s) => s.agentMode); const setAgentMode = useAppStore((s) => s.setAgentMode); + const projectDir = useAppStore((s) => s.projectDir); + const setProjectDir = useAppStore((s) => s.setProjectDir); const corpusSync = useResearchCorpusSync(deepResearch); const [pending, setPending] = useState([]); @@ -195,6 +201,26 @@ export function InputArea() { if (!deepResearch && webSearch) setWebSearch(false); if (!deepResearch && agentMode) setAgentMode(false); }; + // Developer mode: Agent mode inside one project folder. + const pickProject = async () => { + let dir: string | null = null; + if (isTauri()) { + try { + const { open } = await import('@tauri-apps/plugin-dialog'); + const picked = await open({ directory: true, title: 'Choose a project folder' }); + dir = typeof picked === 'string' ? picked : null; + } catch { + dir = null; + } + } else { + dir = window.prompt('Full path of the project folder', projectDir ?? '')?.trim() || null; + } + if (!dir) return; + setProjectDir(dir); + if (!agentMode) setAgentMode(true); + if (deepResearch) setDeepResearch(false); + }; + // Agent mode and Deep Research both decide how to answer, so only one is on. const toggleAgentMode = () => { setAgentMode(!agentMode); @@ -208,8 +234,22 @@ export function InputArea() { available: speechAvailable, startRecording, stopRecording, + cancelRecording, } = useSpeech(); + // Hands-free: the transcript goes out through the prompt queue, which + // sends it as soon as no reply is streaming. + const handsFree = useAppStore((s) => s.settings.handsFree); + useHandsFree({ + enabled: handsFree, + available: speechAvailable, + state: speechState, + startRecording, + stopRecording, + cancelRecording, + send: (text) => useAppStore.getState().queuePrompt(text), + }); + // Abort in-flight stream when the user switches models mid-generation. // This prevents errors from trying to continue a stream with a stale model. const prevModelRef = useRef(selectedModel); @@ -265,6 +305,7 @@ export function InputArea() { if (agentRunRef.current) { void stopAgentRun(agentRunRef.current).catch(() => {}); agentRunRef.current = null; + stoppedByUserRef.current = true; } abortRef.current?.abort(); if (timerRef.current) { @@ -274,8 +315,10 @@ export function InputArea() { resetStream(); }, [resetStream]); - const sendMessage = useCallback(async () => { - const content = input.trim(); + // `prompt` sends that text instead of the input box (Continue does this). + const sendMessage = useCallback(async (prompt?: unknown) => { + const fromPrompt = typeof prompt === 'string'; + const content = (fromPrompt ? prompt : input).trim(); const attachments = readyAttachments.map((p) => p.meta!); if ((!content && attachments.length === 0) || streamState.isStreaming) return; if (attachmentsReading) { @@ -292,7 +335,7 @@ export function InputArea() { } const searchWeb = webSearch && !deepResearch; - setInput(''); + if (!fromPrompt) setInput(''); setPending([]); let convId = activeId; @@ -319,17 +362,8 @@ export function InputArea() { ...(m.role === 'user' ? await apiAttachmentFields(m.attachments) : {}), })), ); - // The agent can't use web results or attached files yet, so a - // conversation that has either gets a chat answer. - const hasExtras = - searchWeb || - apiMessages.some( - (m) => ('images' in m && m.images?.length) || ('attachments' in m && m.attachments?.length), - ); - const useAgent = agentMode && !deepResearch && !hasExtras; - if (agentMode && !deepResearch && hasExtras) { - toast.info("Agent mode can't use web search or attached files yet, so this message gets a chat answer."); - } + // The agent gets attached files, images and web results too. + const useAgent = agentMode && !deepResearch; const assistantMsg: ChatMessage = { id: generateId(), @@ -350,6 +384,7 @@ export function InputArea() { const controller = new AbortController(); abortRef.current = controller; agentRunRef.current = null; + stoppedByUserRef.current = false; let accumulatedContent = ''; let usage: TokenUsage | undefined; @@ -514,7 +549,11 @@ export function InputArea() { temperature, max_tokens: maxTokens, ...(searchWeb ? { web_search: true } : {}), - ...(useAgent ? { mode: 'agent' as const } : {}), + ...(useAgent + ? projectDir + ? { mode: 'developer' as const, project_dir: projectDir } + : { mode: 'agent' as const } + : {}), }, controller.signal, )) { @@ -559,6 +598,8 @@ export function InputArea() { status: 'awaiting_approval', approvalId: data.id, risk: data.risk, + canAlways: Boolean(data.can_always), + preview: data.preview || undefined, }); setStreamState({ phase: 'Waiting for your approval...', @@ -604,7 +645,7 @@ export function InputArea() { }); } setStreamState({ - phase: `Calling ${data.tool}...`, + phase: data.tool === 'task_plan' ? 'Planning...' : `Calling ${data.tool}...`, activeToolCalls: [...toolCalls], }); updateLastAssistant(convId, accumulatedContent, [...toolCalls]); @@ -623,6 +664,7 @@ export function InputArea() { tc.status = data.success ? 'success' : 'error'; tc.latency = data.latency; tc.result = data.result; + if (data.metadata?.undo_id) tc.undoId = data.metadata.undo_id; } setStreamState({ phase: 'Generating...', @@ -679,6 +721,13 @@ export function InputArea() { for (const tc of toolCalls) { if (tc.status === 'awaiting_approval' || tc.status === 'approved') tc.status = 'denied'; } + const stoppedAgent = useAgent && stoppedByUserRef.current; + if (stoppedAgent) { + accumulatedContent = stoppedSummary( + toolCalls, + accumulatedContent === '(Generation stopped)' ? '' : accumulatedContent, + ); + } if (!accumulatedContent) { accumulatedContent = 'No response was generated. Please try again.'; } @@ -727,6 +776,7 @@ export function InputArea() { researchTraces.length > 0 ? researchTraces : undefined, researchSourcesByRef.size > 0 ? flushSources() : undefined, ); + if (stoppedAgent) useAppStore.getState().markLastAssistantStopped(convId, true); if (timerRef.current) { clearInterval(timerRef.current); timerRef.current = null; @@ -766,8 +816,16 @@ export function InputArea() { webSearch, setLastAssistantWebSearch, agentMode, + projectDir, ]); + const queuedPrompt = useAppStore((s) => s.queuedPrompt); + useEffect(() => { + if (!queuedPrompt || streamState.isStreaming) return; + useAppStore.getState().queuePrompt(null); + void sendMessage(queuedPrompt); + }, [queuedPrompt, streamState.isStreaming, sendMessage]); + const handleKeyDown = (e: React.KeyboardEvent) => { if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); @@ -835,6 +893,43 @@ export function InputArea() { Agent +
+ + {projectDir && ( + + )} +
{agentMode && selectedModel && isSmallForAgent(selectedModel) && (
{ + const state = useAppStore.getState(); + if (state.activeId) state.markLastAssistantStopped(state.activeId, false); + state.setAgentMode(true); + state.queuePrompt(CONTINUE_PROMPT); + }; + return ( + + ); +} + export function MessageBubble({ message, isLive = false }: Props) { const isUser = message.role === 'user'; const cleanContent = useMemo(() => stripThinkTags(message.content), [message.content]); + const plan = useMemo(() => latestPlan(message.toolCalls), [message.toolCalls]); + const visibleToolCalls = useMemo( + () => (message.toolCalls ?? []).filter((tc) => tc.tool !== 'task_plan'), + [message.toolCalls], + ); // Build a ref→source lookup once per render. Memoized so the rehype plugin // identity stays stable until the source list actually changes. @@ -158,15 +185,21 @@ export function MessageBubble({ message, isLive = false }: Props) { /> )} - {/* Tool calls */} - {message.toolCalls && message.toolCalls.length > 0 && ( + {/* Agent mode plan: the latest task_plan call, shown as a checklist */} + {plan && } + + {/* Tool calls (plan updates are shown by the checklist instead) */} + {visibleToolCalls.length > 0 && (
- {message.toolCalls.map((tc) => ( + {visibleToolCalls.map((tc) => ( ))}
)} + {/* A stopped Agent mode task can pick up where it left off */} + {message.agentStopped && !isLive && } + {/* Audio player (e.g. morning digest) */} {message.audio?.url && } diff --git a/frontend/src/components/Chat/TaskPlan.test.ts b/frontend/src/components/Chat/TaskPlan.test.ts new file mode 100644 index 0000000..7d3b4da --- /dev/null +++ b/frontend/src/components/Chat/TaskPlan.test.ts @@ -0,0 +1,43 @@ +import { describe, expect, it } from 'vitest'; + +import { latestPlan } from './TaskPlan'; +import type { ToolCallInfo } from '../../types'; + +const call = (tool: string, args: unknown, id = Math.random().toString()): ToolCallInfo => ({ + id, + tool, + arguments: typeof args === 'string' ? args : JSON.stringify(args), + status: 'success', +}); + +describe('latestPlan', () => { + it('is null without a task_plan call', () => { + expect(latestPlan(undefined)).toBeNull(); + expect(latestPlan([call('file_read', { path: 'a' })])).toBeNull(); + }); + + it('uses the latest plan', () => { + const plan = latestPlan([ + call('task_plan', { steps: [{ title: 'Find files', status: 'in_progress' }] }), + call('file_read', { path: 'a' }), + call('task_plan', { + steps: [ + { title: 'Find files', status: 'done' }, + { title: 'Move them', status: 'in_progress' }, + ], + }), + ]); + expect(plan).toEqual([ + { title: 'Find files', status: 'done' }, + { title: 'Move them', status: 'in_progress' }, + ]); + }); + + it('skips broken calls and cleans steps', () => { + const plan = latestPlan([ + call('task_plan', { steps: [{ title: 'Good', status: 'weird' }, { title: ' ' }] }), + call('task_plan', 'not json'), + ]); + expect(plan).toEqual([{ title: 'Good', status: 'pending' }]); + }); +}); diff --git a/frontend/src/components/Chat/TaskPlan.tsx b/frontend/src/components/Chat/TaskPlan.tsx new file mode 100644 index 0000000..88354af --- /dev/null +++ b/frontend/src/components/Chat/TaskPlan.tsx @@ -0,0 +1,74 @@ +import { CheckCircle2, Circle, Loader2, MinusCircle } from 'lucide-react'; +import type { ToolCallInfo } from '../../types'; + +export interface PlanStep { + title: string; + status: 'pending' | 'in_progress' | 'done' | 'skipped'; +} + +/** The plan from the latest `task_plan` call, or null if the agent made none. */ +export function latestPlan(toolCalls: ToolCallInfo[] | undefined): PlanStep[] | null { + const calls = (toolCalls ?? []).filter((tc) => tc.tool === 'task_plan'); + for (let i = calls.length - 1; i >= 0; i--) { + try { + const steps = JSON.parse(calls[i].arguments)?.steps; + if (Array.isArray(steps) && steps.length > 0) { + return steps + .filter((s: any) => s && typeof s.title === 'string' && s.title.trim()) + .map((s: any) => ({ + title: s.title.trim(), + status: ['pending', 'in_progress', 'done', 'skipped'].includes(s.status) ? s.status : 'pending', + })); + } + } catch { + /* keep looking at earlier calls */ + } + } + return null; +} + +const icons = { + pending: { icon: Circle, color: 'var(--color-text-tertiary)' }, + in_progress: { icon: Loader2, color: 'var(--color-accent)' }, + done: { icon: CheckCircle2, color: 'var(--color-success)' }, + skipped: { icon: MinusCircle, color: 'var(--color-text-tertiary)' }, +}; + +export function TaskPlan({ steps, isLive }: { steps: PlanStep[]; isLive: boolean }) { + const done = steps.filter((s) => s.status === 'done' || s.status === 'skipped').length; + return ( +
+
+ Plan · {done} of {steps.length} done +
+
    + {steps.map((step, i) => { + const { icon: Icon, color } = icons[step.status]; + return ( +
  1. + + + {step.title} + +
  2. + ); + })} +
+
+ ); +} diff --git a/frontend/src/components/Chat/ToolCallCard.test.ts b/frontend/src/components/Chat/ToolCallCard.test.ts index fea84ab..eb7f8d5 100644 --- a/frontend/src/components/Chat/ToolCallCard.test.ts +++ b/frontend/src/components/Chat/ToolCallCard.test.ts @@ -19,8 +19,21 @@ describe('describeToolCall', () => { ).toBe('Add to a.txt'); }); + it('describes desktop steps in words', () => { + const d = (tool: string, args: object) => describeToolCall(tool, JSON.stringify(args)); + expect(d('open_path', { path: 'C:/x/report.pdf' })).toBe('Open C:/x/report.pdf'); + expect(d('app_control', { action: 'open', name: 'notepad' })).toBe('Open the app notepad'); + expect(d('app_control', { action: 'close', name: 'chrome' })).toBe('Close chrome'); + expect(d('system_control', { action: 'set_volume', level: 30 })).toBe('Set the volume to 30%'); + expect(d('system_control', { action: 'lock_screen' })).toBe('Lock the screen'); + expect(d('system_control', { action: 'wifi_off' })).toBe('Turn Wi-Fi off'); + expect(d('clipboard', { action: 'read' })).toBe('Read the text on your clipboard'); + expect(d('screenshot', {})).toBe('Take a screenshot of your screen'); + }); + it('falls back to the tool name', () => { - expect(describeToolCall('git_commit', '{"message":"m"}')).toBe('Use git_commit'); + expect(describeToolCall('git_commit', '{"message":"m"}')).toBe('Commit "m"'); + expect(describeToolCall('new_tool', '{}')).toBe('Use new_tool'); 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 ac56e62..a56059f 100644 --- a/frontend/src/components/Chat/ToolCallCard.tsx +++ b/frontend/src/components/Chat/ToolCallCard.tsx @@ -1,9 +1,9 @@ import { useState } from 'react'; -import { ChevronDown, ChevronRight, Loader2, CheckCircle2, XCircle, ShieldQuestion, Ban } from 'lucide-react'; +import { ChevronDown, ChevronRight, Loader2, CheckCircle2, XCircle, ShieldQuestion, Ban, Undo2 } 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'; +import { answerApproval, undoChange, type ApprovalDecision } from '../../lib/api'; interface Props { toolCall: ToolCallInfo; @@ -35,9 +35,42 @@ export function describeToolCall(tool: string, argumentsText: string): string { if (tool === 'file_write' && text('path')) { return text('mode') === 'append' ? `Add to ${text('path')}` : `Write ${text('path')}`; } + const action = text('action'); + const level = typeof args.level === 'number' ? `${args.level}%` : ''; + if (tool === 'open_path' && text('path')) return `Open ${text('path')}`; + if (tool === 'app_control' && text('name')) { + if (action === 'open') return `Open the app ${text('name')}`; + if (action === 'close') return `Close ${text('name')}`; + } + if (tool === 'system_control') { + const settings: Record = { + set_volume: `Set the volume to ${level}`, + mute: 'Mute the speakers', + unmute: 'Unmute the speakers', + set_brightness: `Set the screen brightness to ${level}`, + dark_mode: 'Switch to dark mode', + light_mode: 'Switch to light mode', + lock_screen: 'Lock the screen', + wifi_on: 'Turn Wi-Fi on', + wifi_off: 'Turn Wi-Fi off', + bluetooth_on: 'Turn Bluetooth on', + bluetooth_off: 'Turn Bluetooth off', + }; + if (settings[action]) return settings[action]; + } + if (tool === 'clipboard') { + if (action === 'read') return 'Read the text on your clipboard'; + if (action === 'write') return 'Copy text to your clipboard'; + } + if (tool === 'screenshot') return 'Take a screenshot of your screen'; + if (tool === 'git_commit' && text('message')) return `Commit "${text('message')}"`; return `Use ${tool}`; } +function lowerFirst(text: string): string { + return text.charAt(0).toLowerCase() + text.slice(1); +} + function ApprovalPrompt({ toolCall, argumentsText }: { toolCall: ToolCallInfo; argumentsText: string }) { const [sending, setSending] = useState(false); const answer = async (decision: ApprovalDecision) => { @@ -77,12 +110,30 @@ function ApprovalPrompt({ toolCall, argumentsText }: { toolCall: ToolCallInfo; a }} >
- {toolCall.risk === 'run' ? 'Locus wants to run a command:' : 'Locus wants to make a change:'}{' '} - {describeToolCall(toolCall.tool, argumentsText)} + Allow Locus to{' '} + {lowerFirst(describeToolCall(toolCall.tool, argumentsText))}?
+ {toolCall.preview && ( +
+          {toolCall.preview}
+        
+ )}
{button('Allow', 'approve', true)} {button(`Allow ${toolCall.tool} for this task`, 'approve_tool')} + {toolCall.canAlways && button('Always allow', 'always')} {button('Deny', 'deny')}
@@ -108,6 +159,55 @@ function previewArgs(raw: string): string { return raw.length > 60 ? `${raw.slice(0, 60)}…` : raw; } +function UndoButton({ toolCall }: { toolCall: ToolCallInfo }) { + const [state, setState] = useState<'ready' | 'working' | 'done'>(toolCall.undone ? 'done' : 'ready'); + if (state === 'done') { + return Undone; + } + const undo = async (e: React.MouseEvent) => { + e.stopPropagation(); + if (!toolCall.undoId) return; + setState('working'); + try { + const { ok, message } = await undoChange(toolCall.undoId); + if (ok) { + toolCall.undone = true; + setState('done'); + toast.success(message); + } else { + setState('ready'); + toast.error(message); + } + } catch (err: any) { + setState('ready'); + toast.error(err?.message || 'Could not undo the change.'); + } + }; + return ( + { + if (e.key === 'Enter' || e.key === ' ') undo(e as any); + }} + aria-disabled={state === 'working'} + className="inline-flex items-center gap-1 px-1.5 py-0.5 rounded cursor-pointer" + style={{ + color: 'var(--color-text-secondary)', + border: '1px solid var(--color-border)', + fontSize: 10, + flexShrink: 0, + opacity: state === 'working' ? 0.5 : 1, + }} + title="Put the file back the way it was" + > + + Undo + + ); +} + export function ToolCallCard({ toolCall }: Props) { const [expanded, setExpanded] = useState(false); const config = statusConfig[toolCall.status] ?? statusConfig.running; @@ -156,6 +256,7 @@ export function ToolCallCard({ toolCall }: Props) { )}
+ {toolCall.status === 'success' && toolCall.undoId && } {toolCall.status === 'denied' && ( Denied diff --git a/frontend/src/hooks/useHandsFree.ts b/frontend/src/hooks/useHandsFree.ts new file mode 100644 index 0000000..bc6566e --- /dev/null +++ b/frontend/src/hooks/useHandsFree.ts @@ -0,0 +1,125 @@ +import { useCallback, useEffect, useRef } from 'react'; +import { toast } from 'sonner'; +import { isTauri } from '../lib/api'; +import { useAppStore } from '../lib/store'; +import { useTtsStore } from '../lib/tts'; +import { HANDS_FREE_SHORTCUT, isHandsFreeShortcut, type VadState } from '../lib/vad'; +import type { RecordingOptions, SpeechState } from './useSpeech'; + +interface Options { + enabled: boolean; + /** Speech recognition is set up on the server. */ + available: boolean; + state: SpeechState; + startRecording: (options?: RecordingOptions) => Promise; + stopRecording: () => Promise; + cancelRecording: () => void; + /** Sends the transcript as a chat message. */ + send: (text: string) => void; +} + +/** + * Hands-free voice: Ctrl/Cmd+Shift+L (in the window, and system-wide in the + * desktop app) stops any spoken reply, listens until the user stops talking, + * sends what they said and has the reply read aloud. Pressing it again while + * listening sends straight away. + */ +export function useHandsFree({ + enabled, + available, + state, + startRecording, + stopRecording, + cancelRecording, + send, +}: Options) { + const finish = useCallback( + async (reason: VadState) => { + if (reason === 'no_speech') { + cancelRecording(); + toast("Didn't hear anything. Press Ctrl+Shift+L to try again."); + return; + } + try { + const text = (await stopRecording()).trim(); + if (!text) return; + useAppStore.getState().setSpeakNextReply(true); + send(text); + } catch { + // useSpeech reports transcription errors. + } + }, + [cancelRecording, stopRecording, send], + ); + + const listen = useCallback(async () => { + if (!available) { + toast.error('Speech recognition isn’t set up. Turn it on under Settings > Speech.'); + return; + } + useTtsStore.getState().stop(); // talking over a reply interrupts it + if (state === 'recording') { + void finish('done'); + return; + } + if (state === 'transcribing') return; + await startRecording({ onEndOfSpeech: (reason) => void finish(reason) }); + }, [available, state, startRecording, finish]); + + // The global shortcut outlives renders, so it calls the latest `listen`. + const listenRef = useRef(listen); + useEffect(() => { + listenRef.current = listen; + }, [listen]); + + useEffect(() => { + if (!enabled) return; + const onKey = (e: KeyboardEvent) => { + if (!isHandsFreeShortcut(e)) return; + e.preventDefault(); + void listenRef.current(); + }; + window.addEventListener('keydown', onKey); + return () => window.removeEventListener('keydown', onKey); + }, [enabled]); + + useEffect(() => { + if (!enabled || !isTauri()) return; + let registered = false; + let cancelled = false; + (async () => { + try { + const { register } = await import('@tauri-apps/plugin-global-shortcut'); + await register(HANDS_FREE_SHORTCUT, async (event) => { + if (event.state !== 'Pressed') return; + try { + const { getCurrentWindow } = await import('@tauri-apps/api/window'); + const win = getCurrentWindow(); + await win.unminimize(); + await win.show(); + await win.setFocus(); + } catch { + // Listening still works if the window can't be raised. + } + void listenRef.current(); + }); + registered = true; + if (cancelled) { + const { unregister } = await import('@tauri-apps/plugin-global-shortcut'); + await unregister(HANDS_FREE_SHORTCUT); + } + } catch (err) { + console.warn('Hands-free shortcut unavailable:', err); + } + })(); + return () => { + cancelled = true; + if (!registered) return; + void import('@tauri-apps/plugin-global-shortcut') + .then(({ unregister }) => unregister(HANDS_FREE_SHORTCUT)) + .catch(() => {}); + }; + }, [enabled]); + + return { listen }; +} diff --git a/frontend/src/hooks/useSpeech.ts b/frontend/src/hooks/useSpeech.ts index 6e16e25..0461268 100644 --- a/frontend/src/hooks/useSpeech.ts +++ b/frontend/src/hooks/useSpeech.ts @@ -1,8 +1,17 @@ import { useState, useCallback, useRef, useEffect } from 'react'; import { transcribeAudio, fetchSpeechHealth } from '../lib/api'; +import { SilenceDetector, rms, type VadState } from '../lib/vad'; export type SpeechState = 'idle' | 'recording' | 'transcribing'; +export interface RecordingOptions { + /** + * Hands-free: called once when the speaker stops talking (`done`), nobody + * spoke (`no_speech`) or the turn ran too long (`too_long`). + */ + onEndOfSpeech?: (reason: VadState) => void; +} + export function useSpeech() { const [state, setState] = useState('idle'); const [error, setError] = useState(null); @@ -10,6 +19,8 @@ export function useSpeech() { const mediaRecorderRef = useRef(null); const chunksRef = useRef([]); const streamRef = useRef(null); + // End-of-speech detection, while a hands-free recording runs. + const vadRef = useRef<{ context: AudioContext; timer: number } | null>(null); // Check if speech backend is available on mount useEffect(() => { @@ -18,7 +29,24 @@ export function useSpeech() { .catch(() => setAvailable(false)); }, []); - const startRecording = useCallback(async (): Promise => { + const stopListening = useCallback(() => { + const vad = vadRef.current; + if (vad) { + window.clearInterval(vad.timer); + void vad.context.close().catch(() => {}); + vadRef.current = null; + } + }, []); + + const releaseMic = useCallback(() => { + stopListening(); + streamRef.current?.getTracks().forEach((track) => track.stop()); + streamRef.current = null; + }, [stopListening]); + + useEffect(() => releaseMic, [releaseMic]); + + const startRecording = useCallback(async (options: RecordingOptions = {}): Promise => { setError(null); if (!navigator.mediaDevices?.getUserMedia) { @@ -40,11 +68,30 @@ export function useSpeech() { recorder.start(); mediaRecorderRef.current = recorder; setState('recording'); + + if (options.onEndOfSpeech && typeof AudioContext !== 'undefined') { + const context = new AudioContext(); + const analyser = context.createAnalyser(); + analyser.fftSize = 2048; + context.createMediaStreamSource(stream).connect(analyser); + const samples = new Float32Array(analyser.fftSize); + const detector = new SilenceDetector(); + const onEnd = options.onEndOfSpeech; + const timer = window.setInterval(() => { + analyser.getFloatTimeDomainData(samples); + const result = detector.push(rms(samples), performance.now()); + if (result === 'done' || result === 'no_speech' || result === 'too_long') { + stopListening(); + onEnd(result); + } + }, 100); + vadRef.current = { context, timer }; + } } catch (err) { setError('Microphone access denied'); setState('idle'); } - }, []); + }, [stopListening]); const stopRecording = useCallback(async (): Promise => { return new Promise((resolve, reject) => { @@ -58,8 +105,7 @@ export function useSpeech() { setState('transcribing'); // Stop all audio tracks - streamRef.current?.getTracks().forEach((track) => track.stop()); - streamRef.current = null; + releaseMic(); const blob = new Blob(chunksRef.current, { type: recorder.mimeType || 'audio/webm' }); chunksRef.current = []; @@ -78,7 +124,19 @@ export function useSpeech() { recorder.stop(); }); - }, []); + }, [releaseMic]); + + /** Stop recording and throw the audio away (nobody spoke, or Esc). */ + const cancelRecording = useCallback(() => { + const recorder = mediaRecorderRef.current; + if (recorder && recorder.state === 'recording') { + recorder.onstop = null; + recorder.stop(); + } + chunksRef.current = []; + releaseMic(); + setState('idle'); + }, [releaseMic]); return { state, @@ -86,6 +144,7 @@ export function useSpeech() { available, startRecording, stopRecording, + cancelRecording, isRecording: state === 'recording', isTranscribing: state === 'transcribing', }; diff --git a/frontend/src/lib/agent-stop.test.ts b/frontend/src/lib/agent-stop.test.ts new file mode 100644 index 0000000..dcd2f55 --- /dev/null +++ b/frontend/src/lib/agent-stop.test.ts @@ -0,0 +1,32 @@ +import { describe, expect, it } from 'vitest'; + +import { stoppedSummary } from './agent-stop'; +import type { ToolCallInfo } from '../types'; + +const tc = (tool: string, args: object, status: ToolCallInfo['status']): ToolCallInfo => ({ + id: tool, + tool, + arguments: JSON.stringify(args), + status, +}); + +describe('stoppedSummary', () => { + it('lists the finished steps', () => { + const text = stoppedSummary( + [ + tc('task_plan', { steps: [] }, 'success'), + tc('file_write', { path: 'a.txt', content: 'x' }, 'success'), + tc('shell_exec', { command: 'dir' }, 'denied'), + tc('system_control', { action: 'mute' }, 'success'), + ], + '', + ); + expect(text).toBe('Stopped before finishing.\n\nDone so far: Write a.txt; Mute the speakers.'); + }); + + it('keeps any partial answer and says when nothing finished', () => { + expect(stoppedSummary([], 'Working on it')).toBe( + 'Working on it\n\nStopped before finishing.\n\nNo steps were finished.', + ); + }); +}); diff --git a/frontend/src/lib/agent-stop.ts b/frontend/src/lib/agent-stop.ts new file mode 100644 index 0000000..27eb523 --- /dev/null +++ b/frontend/src/lib/agent-stop.ts @@ -0,0 +1,23 @@ +import type { ToolCallInfo } from '../types'; +import { describeToolCall } from '../components/Chat/ToolCallCard'; + +/** Sent by Continue on a stopped Agent mode task. */ +export const CONTINUE_PROMPT = + "Continue the task from where you stopped. Don't redo the steps you already finished."; + +/** + * The reply for an Agent mode task the user stopped. It stays in the + * conversation, so a later Continue tells the agent what was already done. + */ +export function stoppedSummary(toolCalls: ToolCallInfo[], partial: string): string { + const finished = toolCalls + .filter((tc) => tc.tool !== 'task_plan' && tc.status === 'success') + .map((tc) => describeToolCall(tc.tool, tc.arguments)); + const lines = [partial.trim(), 'Stopped before finishing.'].filter(Boolean); + lines.push( + finished.length > 0 + ? `Done so far: ${finished.join('; ')}.` + : 'No steps were finished.', + ); + return lines.join('\n\n'); +} diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts index 50de730..22543e3 100644 --- a/frontend/src/lib/api.ts +++ b/frontend/src/lib/api.ts @@ -1229,7 +1229,7 @@ export const stageInferenceSource = ( // ── Agent mode approvals ────────────────────────────────────── -export type ApprovalDecision = 'approve' | 'approve_tool' | 'deny'; +export type ApprovalDecision = 'approve' | 'approve_tool' | 'always' | 'deny'; /** Answer an Agent mode approval. Returns false if it's no longer waiting. */ export async function answerApproval(id: string, decision: ApprovalDecision): Promise { @@ -1247,3 +1247,29 @@ export async function answerApproval(id: string, decision: ApprovalDecision): Pr export async function stopAgentRun(runId: string): Promise { await apiFetch(`/v1/chat/runs/${encodeURIComponent(runId)}/stop`, { method: 'POST' }); } + +/** Undo an Agent mode file change. Resolves to the server's message. */ +export async function undoChange(undoId: string): Promise<{ ok: boolean; message: string }> { + const res = await apiFetch(`/v1/chat/undo/${encodeURIComponent(undoId)}`, { method: 'POST' }); + const body = await res.json().catch(() => ({})); + return { ok: res.ok, message: body.message ?? body.detail ?? `Undo failed: ${res.status}` }; +} + +export interface AgentPermission { + key: string; + tool: string; + action?: string | null; + created: number; +} + +/** Agent mode's "always allow" rules. */ +export async function fetchAgentPermissions(): Promise { + const res = await apiFetch('/v1/chat/permissions'); + if (!res.ok) throw new Error(`Could not load permissions: ${res.status}`); + return (await res.json()).rules ?? []; +} + +export async function removeAgentPermission(key: string): Promise { + const res = await apiFetch(`/v1/chat/permissions/${encodeURIComponent(key)}`, { method: 'DELETE' }); + if (!res.ok && res.status !== 404) throw new Error(`Could not remove the rule: ${res.status}`); +} diff --git a/frontend/src/lib/sse.ts b/frontend/src/lib/sse.ts index 84ece45..b728b53 100644 --- a/frontend/src/lib/sse.ts +++ b/frontend/src/lib/sse.ts @@ -17,7 +17,9 @@ export interface ChatRequest { /** Search the web for the latest user message before answering. */ web_search?: boolean; /** "agent" runs a tool-using agent; "chat" answers with the model alone. */ - mode?: 'chat' | 'agent'; + mode?: 'chat' | 'agent' | 'developer'; + /** Developer mode's project folder. */ + project_dir?: string; } export async function* streamChat( diff --git a/frontend/src/lib/store.ts b/frontend/src/lib/store.ts index eaeb42a..eae499c 100644 --- a/frontend/src/lib/store.ts +++ b/frontend/src/lib/store.ts @@ -45,6 +45,7 @@ const OPTIN_EMAIL_KEY = 'locus-email'; const OPTIN_ANONID_KEY = 'locus-anon-id'; const WEB_SEARCH_KEY = 'locus-web-search'; const AGENT_MODE_KEY = 'locus-agent-mode'; +const PROJECT_DIR_KEY = 'locus-project-dir'; interface ConversationStore { version: 1; @@ -112,6 +113,8 @@ interface Settings { speechEnabled: boolean; voiceOutputEnabled: boolean; voiceAutoplay: boolean; + /** Ctrl/Cmd+Shift+L listens, sends when you stop talking, and speaks the reply. */ + handsFree: boolean; } function loadSettings(): Settings { @@ -127,6 +130,7 @@ function loadSettings(): Settings { speechEnabled: false, voiceOutputEnabled: false, voiceAutoplay: false, + handsFree: false, }; try { const raw = localStorage.getItem(SETTINGS_KEY); @@ -219,6 +223,18 @@ interface AppState { // Agent mode: answers use a tool-using agent (remembered across launches) agentMode: boolean; setAgentMode: (on: boolean) => void; + markLastAssistantStopped: (conversationId: string, stopped: boolean) => void; + // Developer mode: Agent mode works inside this project folder + projectDir: string | null; + setProjectDir: (dir: string | null) => void; + + // A message for the chat input to send (Continue on a stopped task) + queuedPrompt: string | null; + queuePrompt: (text: string | null) => void; + + // Speak the next finished reply aloud (set by a hands-free turn) + speakNextReply: boolean; + setSpeakNextReply: (on: boolean) => void; setLastAssistantWebSearch: ( conversationId: string, webSearch: WebSearchInfo, @@ -514,6 +530,31 @@ export const useAppStore = create((set, get) => { localStorage.setItem(AGENT_MODE_KEY, String(on)); set({ agentMode: on }); }, + projectDir: localStorage.getItem(PROJECT_DIR_KEY) || null, + setProjectDir: (dir) => { + if (dir) localStorage.setItem(PROJECT_DIR_KEY, dir); + else localStorage.removeItem(PROJECT_DIR_KEY); + set({ projectDir: dir }); + }, + + markLastAssistantStopped: (conversationId, stopped) => { + const store = loadConversations(); + const conv = store.conversations[conversationId]; + const lastMsg = conv?.messages[conv.messages.length - 1]; + if (!conv || !lastMsg || lastMsg.role !== 'assistant') return; + lastMsg.agentStopped = stopped || undefined; + saveConversations(store); + if (get().activeId === conversationId) { + set({ messages: [...conv.messages] }); + } + }, + + queuedPrompt: null, + queuePrompt: (text) => set({ queuedPrompt: text }), + + speakNextReply: false, + setSpeakNextReply: (on) => set({ speakNextReply: on }), + setLastAssistantWebSearch: (conversationId, webSearch, sources) => { const store = loadConversations(); const conv = store.conversations[conversationId]; diff --git a/frontend/src/lib/vad.test.ts b/frontend/src/lib/vad.test.ts new file mode 100644 index 0000000..69c730a --- /dev/null +++ b/frontend/src/lib/vad.test.ts @@ -0,0 +1,64 @@ +import { describe, expect, it } from 'vitest'; + +import { SilenceDetector, isHandsFreeShortcut, rms } from './vad'; + +/** Feed `level` every 100 ms from `from` to `to` (ms). */ +function feed(vad: SilenceDetector, level: number, from: number, to: number) { + let state = vad.state; + for (let t = from; t < to; t += 100) state = vad.push(level, t); + return state; +} + +describe('SilenceDetector', () => { + it('ends the turn after speech and then quiet', () => { + const vad = new SilenceDetector({ silenceMs: 1000 }); + feed(vad, 0.005, 0, 300); // room noise + expect(feed(vad, 0.2, 300, 2000)).toBe('speaking'); + expect(feed(vad, 0.006, 2000, 2800)).toBe('speaking'); + expect(feed(vad, 0.006, 2800, 3200)).toBe('done'); + }); + + it('keeps listening through short pauses', () => { + const vad = new SilenceDetector({ silenceMs: 1000 }); + feed(vad, 0.005, 0, 300); + feed(vad, 0.2, 300, 1000); + feed(vad, 0.005, 1000, 1500); // half a second's pause + expect(feed(vad, 0.2, 1500, 2000)).toBe('speaking'); + }); + + it('gives up when nobody speaks', () => { + const vad = new SilenceDetector({ noSpeechMs: 2000 }); + expect(feed(vad, 0.004, 0, 2100)).toBe('no_speech'); + }); + + it('adapts to a noisy room', () => { + const vad = new SilenceDetector({ noSpeechMs: 2000 }); + feed(vad, 0.05, 0, 300); // loud background + expect(vad.threshold).toBeCloseTo(0.125); + expect(feed(vad, 0.06, 300, 2100)).toBe('no_speech'); + }); + + it('stops a turn that runs too long', () => { + const vad = new SilenceDetector({ maxMs: 1000 }); + feed(vad, 0.004, 0, 300); + expect(feed(vad, 0.3, 300, 1100)).toBe('too_long'); + }); +}); + +describe('rms', () => { + it('measures loudness', () => { + expect(rms(new Float32Array([]))).toBe(0); + expect(rms(new Float32Array([0.5, -0.5, 0.5, -0.5]))).toBeCloseTo(0.5); + }); +}); + +describe('isHandsFreeShortcut', () => { + const key = (over: object) => ({ key: 'L', ctrlKey: false, metaKey: false, shiftKey: true, altKey: false, ...over }); + it('matches Ctrl+Shift+L and Cmd+Shift+L only', () => { + expect(isHandsFreeShortcut(key({ ctrlKey: true }))).toBe(true); + expect(isHandsFreeShortcut(key({ metaKey: true }))).toBe(true); + expect(isHandsFreeShortcut(key({}))).toBe(false); + expect(isHandsFreeShortcut(key({ ctrlKey: true, altKey: true }))).toBe(false); + expect(isHandsFreeShortcut(key({ ctrlKey: true, key: 'k' }))).toBe(false); + }); +}); diff --git a/frontend/src/lib/vad.ts b/frontend/src/lib/vad.ts new file mode 100644 index 0000000..9fc8f8f --- /dev/null +++ b/frontend/src/lib/vad.ts @@ -0,0 +1,86 @@ +/** + * End-of-speech detection for hands-free voice. + * + * Feed it the microphone's loudness (RMS, 0-1) every ~100 ms. It learns the + * room's noise floor for the first moments, treats anything clearly louder as + * speech, and reports `done` once the speaker has been quiet for `silenceMs`. + */ + +export type VadState = 'waiting' | 'speaking' | 'done' | 'no_speech' | 'too_long'; + +export interface VadOptions { + /** Quiet after speech that ends the turn. */ + silenceMs?: number; + /** Give up if nobody speaks this long. */ + noSpeechMs?: number; + /** Stop a turn that runs this long. */ + maxMs?: number; + /** Time spent measuring background noise before listening for speech. */ + calibrateMs?: number; +} + +export class SilenceDetector { + private readonly silenceMs: number; + private readonly noSpeechMs: number; + private readonly maxMs: number; + private readonly calibrateMs: number; + private startedAt: number | null = null; + private lastLoudAt: number | null = null; + private noiseSamples: number[] = []; + private noiseFloor = 0; + state: VadState = 'waiting'; + + constructor(options: VadOptions = {}) { + this.silenceMs = options.silenceMs ?? 1200; + this.noSpeechMs = options.noSpeechMs ?? 8000; + this.maxMs = options.maxMs ?? 30000; + this.calibrateMs = options.calibrateMs ?? 300; + } + + /** Speech must be this loud: well above the noise floor, and audible. */ + get threshold(): number { + return Math.max(this.noiseFloor * 2.5, 0.02); + } + + push(rms: number, now: number): VadState { + if (this.state === 'done' || this.state === 'no_speech' || this.state === 'too_long') { + return this.state; + } + if (this.startedAt === null) this.startedAt = now; + const elapsed = now - this.startedAt; + + if (elapsed < this.calibrateMs) { + this.noiseSamples.push(rms); + this.noiseFloor = this.noiseSamples.reduce((a, b) => a + b, 0) / this.noiseSamples.length; + return this.state; + } + + if (rms >= this.threshold) { + this.lastLoudAt = now; + this.state = 'speaking'; + } + if (elapsed >= this.maxMs) { + this.state = this.state === 'speaking' ? 'too_long' : 'no_speech'; + } else if (this.state === 'speaking' && this.lastLoudAt !== null && now - this.lastLoudAt >= this.silenceMs) { + this.state = 'done'; + } else if (this.state === 'waiting' && elapsed >= this.noSpeechMs) { + this.state = 'no_speech'; + } + return this.state; + } +} + +/** Loudness of one buffer of samples (-1..1), as root mean square. */ +export function rms(samples: Float32Array): number { + if (samples.length === 0) return 0; + let sum = 0; + for (let i = 0; i < samples.length; i++) sum += samples[i] * samples[i]; + return Math.sqrt(sum / samples.length); +} + +/** The hands-free shortcut: Ctrl+Shift+L, or Cmd+Shift+L on a Mac. */ +export const HANDS_FREE_SHORTCUT = 'CommandOrControl+Shift+L'; + +export function isHandsFreeShortcut(e: { key: string; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean; altKey: boolean }): boolean { + return e.key.toLowerCase() === 'l' && e.shiftKey && !e.altKey && (e.ctrlKey || e.metaKey); +} diff --git a/frontend/src/pages/SettingsPage.tsx b/frontend/src/pages/SettingsPage.tsx index db3fc01..09d912b 100644 --- a/frontend/src/pages/SettingsPage.tsx +++ b/frontend/src/pages/SettingsPage.tsx @@ -36,6 +36,7 @@ import { type MemoryStats, } from '../lib/api'; import { isAutoUpdateDisabled, setAutoUpdateDisabled } from '../components/Desktop/UpdateChecker'; +import { AgentPermissionsList } from '../components/Chat/AgentPermissionsList'; const CLOUD_KEY_STATUS_CHANGED = 'locus-cloud-key-status-changed'; @@ -659,6 +660,14 @@ export function SettingsPage() { + {/* Agent mode */} +
+
+ Steps Locus may take without asking +
+ +
+ {/* Memory */}
{ void refreshMemoryStatus(); }} /> @@ -838,6 +847,25 @@ export function SettingsPage() { /> + + +
dict: diff --git a/src/locus/cli/serve.py b/src/locus/cli/serve.py index bd967bb..b970dbd 100644 --- a/src/locus/cli/serve.py +++ b/src/locus/cli/serve.py @@ -773,6 +773,17 @@ def serve( cors_origins=cors_origins, ) + # Reminders set in Agent mode are saved; schedule them again (and show + # any that came due while Locus was closed). + try: + from locus.tools.desktop.notify import restore_reminders + + restored = restore_reminders() + if restored: + console.print(f" Restored {restored} reminder(s).") + except Exception as exc: + logger.warning("Reminders couldn't be restored: %s", exc) + console.print( f"[green]Starting Locus API server[/green]\n" f" Engine: [cyan]{engine_name}[/cyan]\n" diff --git a/src/locus/security/capabilities.py b/src/locus/security/capabilities.py index 5a11a5c..c47be5f 100644 --- a/src/locus/security/capabilities.py +++ b/src/locus/security/capabilities.py @@ -213,6 +213,9 @@ def save(self, path: Path) -> None: "agent_send": [Capability.SYSTEM_ADMIN], "agent_spawn": [Capability.SYSTEM_ADMIN], "apply_patch": [Capability.FILE_WRITE], + # Desktop control (locus.tools.desktop). Opening a path or an app can start + # a program; system_control changes computer settings. + "app_control": [Capability.CODE_EXECUTE], "audio_transcribe": [Capability.FILE_READ, Capability.NETWORK_FETCH], "browser_axtree": [Capability.NETWORK_FETCH], "browser_click": [Capability.NETWORK_FETCH], @@ -228,6 +231,7 @@ def save(self, path: Path) -> None: "channel_send": [Capability.CHANNEL_SEND], "channel_status": [Capability.SYSTEM_ADMIN], "check_permission": [Capability.MEMORY_READ], + "clipboard": [Capability.FILE_READ, Capability.FILE_WRITE], "code_interpreter": [Capability.CODE_EXECUTE], "code_interpreter_docker": [Capability.CODE_EXECUTE], "db_query": [Capability.CODE_EXECUTE], @@ -262,6 +266,8 @@ def save(self, path: Path) -> None: "memory_retrieve": [Capability.MEMORY_READ], "memory_search": [Capability.MEMORY_READ], "memory_store": [Capability.MEMORY_WRITE], + "notify": [Capability.SCHEDULE_CREATE], + "open_path": [Capability.FILE_READ, Capability.CODE_EXECUTE], "pause_scheduled_task": [Capability.SCHEDULE_CREATE], "pdf_extract": [Capability.FILE_READ], "queue_action": [Capability.MEMORY_WRITE], @@ -271,17 +277,22 @@ def save(self, path: Path) -> None: "retrieval": [Capability.MEMORY_READ], "scan_chunks": [Capability.MEMORY_READ], "schedule_task": [Capability.SCHEDULE_CREATE], + "screenshot": [Capability.FILE_READ, Capability.FILE_WRITE], "shell_exec": [Capability.CODE_EXECUTE], "skill_manage": [Capability.FILE_READ, Capability.FILE_WRITE], + "system_control": [Capability.SYSTEM_ADMIN], + "task_plan": [], "text_to_speech": [Capability.NETWORK_FETCH, Capability.FILE_WRITE], "think": [], "user_profile_manage": [Capability.FILE_READ, Capability.FILE_WRITE], + "window_control": [Capability.TOOL_INVOKE], "web_search": [Capability.NETWORK_FETCH], } _SAFE_BUILTIN_PROVENANCE = { "calculator": ("locus.tools.calculator", "CalculatorTool"), "think": ("locus.tools.think", "ThinkTool"), + "task_plan": ("locus.tools.task_plan", "TaskPlanTool"), } diff --git a/src/locus/server/approvals.py b/src/locus/server/approvals.py index c179c09..f24f598 100644 --- a/src/locus/server/approvals.py +++ b/src/locus/server/approvals.py @@ -14,18 +14,22 @@ from __future__ import annotations import contextvars +import json import threading import time import uuid from dataclasses import dataclass, field +from pathlib import Path from typing import Any, Callable, Dict, Literal, Optional Risk = Literal["read", "change", "run"] -Decision = Literal["approve", "approve_tool", "deny"] +# "always" also saves a lasting rule; it applies only to "change" calls. +Decision = Literal["approve", "approve_tool", "always", "deny"] #: Tools that only read, or write to Locus's own memory. They never ask. READ_ONLY_TOOLS = frozenset( { + "task_plan", "think", "calculator", "file_read", @@ -55,16 +59,107 @@ 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.""" +def tool_risk(name: str, tool: Any = None, arguments: Optional[dict] = None) -> Risk: + """Classify a tool call. Unknown tools ask, so new tools fail closed. + + A tool whose risk depends on what it's asked to do (listing windows vs + closing an app) can define ``risk_for(arguments)``. + """ spec = getattr(tool, "spec", None) - if name in RUN_TOOLS or getattr(spec, "requires_confirmation", False): + if getattr(spec, "requires_confirmation", False): + return "run" + # A tool's own risk_for decides before the name lists, so developer + # mode's shell can let known checks (tests, git status) through. + risk_for = getattr(tool, "risk_for", None) + if callable(risk_for): + try: + risk = risk_for(arguments or {}) + except Exception: + risk = "change" + return risk if risk in ("read", "change", "run") else "change" + if name in RUN_TOOLS: return "run" if name in READ_ONLY_TOOLS: return "read" return "change" +#: Previews longer than this are cut before they're sent to the chat. +MAX_PREVIEW_CHARS = 8000 + + +def rule_key(tool_name: str, arguments: Optional[dict] = None) -> str: + """A lasting rule covers one tool, or one action of it (``tool:action``).""" + action = (arguments or {}).get("action") + return f"{tool_name}:{action}" if isinstance(action, str) and action else tool_name + + +class PermissionRules: + """ "Always allow" rules, kept in ``~/.locus/agent_permissions.json``.""" + + def __init__(self, path: Optional[Path] = None) -> None: + if path is None: + from locus.core.paths import get_config_dir + + path = Path(get_config_dir()) / "agent_permissions.json" + self.path = Path(path) + self._lock = threading.Lock() + + def _load(self) -> Dict[str, dict]: + try: + rows = json.loads(self.path.read_text(encoding="utf-8")) + except (OSError, ValueError): + return {} + return {r["key"]: r for r in rows if isinstance(r, dict) and r.get("key")} + + def _save(self, rules: Dict[str, dict]) -> None: + self.path.parent.mkdir(parents=True, exist_ok=True) + tmp = self.path.with_suffix(".tmp") + tmp.write_text(json.dumps(list(rules.values()), indent=2), encoding="utf-8") + tmp.replace(self.path) + + def allows(self, tool_name: str, arguments: Optional[dict] = None) -> bool: + with self._lock: + return rule_key(tool_name, arguments) in self._load() + + def add(self, tool_name: str, arguments: Optional[dict] = None) -> str: + key = rule_key(tool_name, arguments) + with self._lock: + rules = self._load() + rules[key] = { + "key": key, + "tool": tool_name, + "action": (arguments or {}).get("action"), + "created": time.time(), + } + self._save(rules) + return key + + def remove(self, key: str) -> bool: + with self._lock: + rules = self._load() + if rules.pop(key, None) is None: + return False + self._save(rules) + return True + + def list(self) -> list: + with self._lock: + return sorted(self._load().values(), key=lambda r: r["key"]) + + +_rules: Optional[PermissionRules] = None +_rules_lock = threading.Lock() + + +def get_rules() -> PermissionRules: + global _rules + with _rules_lock: + if _rules is None: + _rules = PermissionRules() + return _rules + + class AgentCancelled(BaseException): """Raised on the agent's thread to stop a run the user stopped. @@ -150,9 +245,13 @@ 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)) + tool = self._tools.get(tool_name) + risk = tool_risk(tool_name, tool, arguments) if risk == "read" or tool_name in self._allowed_tools: return True + # Lasting rules never cover "run" calls: commands and code always ask. + if risk == "change" and get_rules().allows(tool_name, arguments): + return True pending = _Pending(id=uuid.uuid4().hex, tool=tool_name) with _pending_lock: @@ -166,6 +265,9 @@ def check(self, tool_name: str, arguments: dict) -> bool: "tool": tool_name, "arguments": arguments, "risk": risk, + "can_always": risk == "change", + "rule": rule_key(tool_name, arguments), + "preview": _preview(tool, arguments), "timeout_seconds": self._timeout, }, ) @@ -181,9 +283,11 @@ def check(self, tool_name: str, arguments: dict) -> bool: if self.cancelled.is_set(): raise AgentCancelled() decision = pending.decision - approved = decision in ("approve", "approve_tool") + approved = decision in ("approve", "approve_tool", "always") if decision == "approve_tool": self._allowed_tools.add(tool_name) + elif decision == "always" and risk == "change": + get_rules().add(tool_name, arguments) self._emit( "approval_resolved", { @@ -196,6 +300,23 @@ def check(self, tool_name: str, arguments: dict) -> bool: return approved +def _preview(tool: Any, arguments: dict) -> Optional[str]: + """What the call would change (a diff, say), if the tool can tell.""" + preview_for = getattr(tool, "preview_for", None) + if not callable(preview_for): + return None + try: + text = preview_for(arguments) + except Exception: + return None + if not text: + return None + text = str(text) + if len(text) > MAX_PREVIEW_CHARS: + text = text[:MAX_PREVIEW_CHARS] + "\n… (preview cut off)" + return text + + current_session: contextvars.ContextVar[Optional[ApprovalSession]] = ( contextvars.ContextVar("locus_approval_session", default=None) ) diff --git a/src/locus/server/developer.py b/src/locus/server/developer.py new file mode 100644 index 0000000..fac6397 --- /dev/null +++ b/src/locus/server/developer.py @@ -0,0 +1,231 @@ +"""Developer mode: an Agent mode agent working inside one project folder. + +File, git and shell tools are kept in the project. Tests, linters and +read-only git commands run without asking; any other command asks every time. +""" + +from __future__ import annotations + +import dataclasses +import shlex +from pathlib import Path +from typing import Any, Optional + +from locus.core.types import ToolResult +from locus.tools._stubs import BaseTool, ToolSpec + +#: Commands that only check the project. A command runs without asking only +#: when it starts with one of these and has no shell operators. +SAFE_COMMANDS: tuple[tuple[str, ...], ...] = ( + ("git", "status"), + ("git", "diff"), + ("git", "log"), + ("git", "show"), + ("pytest",), + ("python", "-m", "pytest"), + ("uv", "run", "pytest"), + ("ruff", "check"), + ("ruff", "format", "--check"), + ("uv", "run", "ruff", "check"), + ("uv", "run", "ruff", "format", "--check"), + ("npm", "test"), + ("npm", "run", "test"), + ("npm", "run", "lint"), + ("npx", "vitest", "run"), + ("npx", "tsc", "--noEmit"), + ("npx", "eslint"), + ("cargo", "test"), + ("cargo", "check"), + ("cargo", "clippy"), + ("go", "test"), + ("go", "vet"), +) + +# Anything that chains, redirects, substitutes or expands needs a person. +_SHELL_OPERATORS = set(";&|<>`$(){}^%!\n\r") +# Flags that make an otherwise read-only command write or run something. +_UNSAFE_FLAGS = ("--output", "--ext-diff", "--exec", "-c", "--config") + + +def command_risk(command: str) -> str: + """``"read"`` for a known check (tests, linters, git status); else ``"run"``.""" + if not command or any(ch in _SHELL_OPERATORS for ch in command): + return "run" + try: + tokens = shlex.split(command) + except ValueError: + return "run" + for prefix in SAFE_COMMANDS: + if tuple(tokens[: len(prefix)]) == prefix: + rest = tokens[len(prefix) :] + if any( + t == f or t.startswith(f + "=") for t in rest for f in _UNSAFE_FLAGS + ): + return "run" + return "read" + return "run" + + +def resolve_project_dir(raw: Optional[str]) -> Path: + """The project folder, or ``ValueError`` saying why it can't be used.""" + if not raw or not str(raw).strip(): + raise ValueError("Choose a project folder for developer mode.") + path = Path(str(raw).strip()).expanduser() + if not path.is_absolute(): + raise ValueError("The project folder must be a full path.") + path = path.resolve() + if not path.is_dir(): + raise ValueError(f"{path} isn't a folder.") + if path == Path(path.anchor) or path == Path.home().resolve(): + raise ValueError( + "Choose a project folder, not a whole drive or your home folder." + ) + return path + + +def _inside(path: Path, project: Path) -> bool: + resolved = path.resolve() + return resolved == project or resolved.is_relative_to(project) + + +class InProjectTool(BaseTool): + """Wraps a tool that takes ``path_param`` so it stays in the project.""" + + def __init__(self, inner: BaseTool, project: Path, path_param: str) -> None: + self._inner = inner + self._project = project + self._path_param = path_param + self.tool_id = getattr(inner, "tool_id", inner.spec.name) + + @property + def spec(self) -> ToolSpec: + return self._inner.spec + + def __getattr__(self, name: str) -> Any: + # risk_for, preview_for and anything else the inner tool offers. + if name.startswith("_"): + raise AttributeError(name) + return getattr(self._inner, name) + + def execute(self, **params: Any) -> ToolResult: + raw = params.get(self._path_param) or str(self._project) + path = Path(str(raw)) + if not path.is_absolute(): + path = self._project / path + if not _inside(path, self._project): + return ToolResult( + tool_name=self.spec.name, + content=f"{raw} is outside the project folder {self._project}.", + success=False, + ) + return self._inner.execute(**{**params, self._path_param: str(path)}) + + +class ProjectShellTool(BaseTool): + """``shell_exec`` in the project folder, with read-only checks pre-approved. + + It isn't marked ``requires_confirmation``: approvals ask by its own + :meth:`risk_for` instead, which is ``run`` for anything but known checks. + """ + + def __init__(self, project: Path) -> None: + from locus.tools.shell_exec import ShellExecTool + + self._inner = ShellExecTool() + self._project = project + self.tool_id = "shell_exec" + + @property + def spec(self) -> ToolSpec: + spec = self._inner.spec + return dataclasses.replace( + spec, + description=( + f"{spec.description} Commands run in the project folder" + f" ({self._project}) unless working_dir names a folder inside" + " it. Tests, linters and git status/diff/log run right away;" + " other commands need the user's approval." + ), + requires_confirmation=False, + ) + + def risk_for(self, arguments: dict) -> str: + return command_risk(str(arguments.get("command") or "")) + + def execute(self, **params: Any) -> ToolResult: + working_dir = Path(str(params.get("working_dir") or self._project)) + if not working_dir.is_absolute(): + working_dir = self._project / working_dir + if not _inside(working_dir, self._project): + return ToolResult( + tool_name="shell_exec", + content=f"{working_dir} is outside the project folder.", + success=False, + ) + return self._inner.execute(**{**params, "working_dir": str(working_dir)}) + + +_DEVELOPER_RULES = ( + "For anything with more than one step, show your plan with task_plan first" + " and update it as you go.", + "Read the relevant code with file_read before changing it. Change files" + " with file_write, giving the whole new file; the user reviews a diff" + " before it's written.", + "Before your first change, run `git status`. If the project is a git" + " repository on main or master, create a branch with" + " `git switch -c locus/` (the user approves it).", + "After changing code, run the project's tests or checks (for example" + " pytest, npm test or cargo test). If they fail, read the failure, fix it" + " and run them again, up to 3 times, then report what's left.", + "Never push, delete branches or delete files unless the user asks. Commit" + " only when the user asks, with a short message saying what changed and" + " why.", + "Keep replies short: what you changed, and the test result.", +) + + +def developer_prompt(project: Path) -> str: + rules = "\n".join(f"- {rule}" for rule in _DEVELOPER_RULES) + return ( + f"You are Locus in developer mode, working on the project in {project}." + f"\n\nHow to work:\n{rules}" + ) + + +def developer_tools(project: Path, config: Any = None) -> list: + """The developer agent's tools, all kept inside *project*.""" + from locus.tools.calculator import CalculatorTool + from locus.tools.file_read import FileReadTool + from locus.tools.git_tool import ( + GitCommitTool, + GitDiffTool, + GitLogTool, + GitStatusTool, + ) + from locus.tools.task_plan import TaskPlanTool + from locus.tools.think import ThinkTool + from locus.tools.undo_journal import UndoableFileWriteTool + + folder = [str(project)] + tools: list = [ + TaskPlanTool(), + ThinkTool(), + CalculatorTool(), + FileReadTool(allowed_dirs=folder), + UndoableFileWriteTool(allowed_dirs=folder), + ProjectShellTool(project), + ] + for git_tool in (GitStatusTool(), GitDiffTool(), GitLogTool(), GitCommitTool()): + tools.append(InProjectTool(git_tool, project, "repo_path")) + return tools + + +__all__ = [ + "SAFE_COMMANDS", + "InProjectTool", + "ProjectShellTool", + "command_risk", + "developer_prompt", + "developer_tools", + "resolve_project_dir", +] diff --git a/src/locus/server/models.py b/src/locus/server/models.py index 8c8feee..e4c1d74 100644 --- a/src/locus/server/models.py +++ b/src/locus/server/models.py @@ -45,13 +45,16 @@ class ChatCompletionRequest(BaseModel): # Locus extension: search the web for the latest user message first. web_search: bool = False # Locus extension: "chat" answers with the model alone, "agent" runs a - # tool-using agent. Unset keeps the server's configured agent. - mode: Optional[Literal["chat", "agent"]] = None + # tool-using agent, and "developer" runs one kept inside project_dir. + # Unset keeps the server's configured agent. + mode: Optional[Literal["chat", "agent", "developer"]] = None + project_dir: Optional[str] = None class ApprovalAnswer(BaseModel): - # "approve_tool" also approves later calls to the same tool in this run. - decision: Literal["approve", "approve_tool", "deny"] + # "approve_tool" also approves later calls to the same tool in this run; + # "always" saves a lasting rule (change-level calls only). + decision: Literal["approve", "approve_tool", "always", "deny"] # --------------------------------------------------------------------------- diff --git a/src/locus/server/routes.py b/src/locus/server/routes.py index e1a367e..859c523 100644 --- a/src/locus/server/routes.py +++ b/src/locus/server/routes.py @@ -267,16 +267,26 @@ async def chat_completions(request_body: ChatCompletionRequest, request: Request from locus.server.task_agent import get_task_agent agent = await asyncio.to_thread(get_task_agent, request.app.state) + elif request_body.mode == "developer": + from locus.server.task_agent import get_developer_agent + + try: + agent = await asyncio.to_thread( + get_developer_agent, request.app.state, request_body.project_dir + ) + except ValueError as exc: + raise HTTPException(status_code=400, detail=str(exc)) from exc model = request_body.model - # Agents take only the latest message's text, which would drop web results, - # attached documents and images, so those requests go straight to the engine. + # Agent mode passes web results, attached documents and images to its agent + # (see _handle_agent). Other requests with them keep going straight to the + # engine, as they did before agents could take them. has_extras = request_body.web_search or any( m.images or m.attachments for m in request_body.messages ) use_server_agent = ( agent is not None and not request_body.tools - and not has_extras + and (request_body.mode in ("agent", "developer") or not has_extras) and (not request_body.stream or bool(getattr(agent, "_tools", None))) ) @@ -526,6 +536,35 @@ async def answer_approval(approval_id: str, body: ApprovalAnswer): return {"id": approval_id, "decision": body.decision} +@router.get("/v1/chat/permissions") +async def list_agent_permissions(): + """Agent mode's "always allow" rules.""" + from locus.server.approvals import get_rules + + return {"rules": get_rules().list()} + + +@router.delete("/v1/chat/permissions/{key}") +async def remove_agent_permission(key: str): + """Remove an "always allow" rule, so that step asks again.""" + from locus.server.approvals import get_rules + + if not get_rules().remove(key): + raise HTTPException(status_code=404, detail="No rule with that key") + return {"key": key, "removed": True} + + +@router.post("/v1/chat/undo/{undo_id}") +async def undo_file_change(undo_id: str): + """Undo a file change from Agent mode (``undo_id`` in ``tool_call_end``).""" + from locus.tools.undo_journal import get_journal + + done, message = await asyncio.to_thread(get_journal().undo, undo_id) + if not done: + raise HTTPException(status_code=409, detail=message) + return {"undo_id": undo_id, "message": message} + + @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.""" @@ -773,15 +812,16 @@ def _handle_agent( """ from locus.agents._stubs import AgentContext - # Build context from prior messages + # Prior messages are the context and the last one is the input, with + # attached documents folded into each message's text (the same budget as + # direct chat) and the last message's images kept for vision models. ctx = AgentContext() - if len(req.messages) > 1: - prior = _to_messages(req.messages[:-1]) - for m in prior: - ctx.conversation.add(m) - - # Last message is the input - input_text = req.messages[-1].content if req.messages else "" + messages = _to_messages(req.messages) if req.messages else [] + for m in messages[:-1]: + ctx.conversation.add(m) + input_text = messages[-1].content if messages else "" + if messages and messages[-1].images: + ctx.metadata["input_images"] = list(messages[-1].images) # Override agent model for this request if the caller specified one. # Locked for the full override-run-restore cycle (#759): only the diff --git a/src/locus/server/task_agent.py b/src/locus/server/task_agent.py index 3913ac6..11d6e6f 100644 --- a/src/locus/server/task_agent.py +++ b/src/locus/server/task_agent.py @@ -18,6 +18,7 @@ # Tools that change something (writing files, running commands) ask in the # chat before each call; see ``server/approvals.py``. Network access waits. ASSISTANT_TOOLS = ( + "task_plan", "think", "calculator", "file_read", @@ -28,6 +29,14 @@ "git_log", "file_write", "shell_exec", + # Desktop control (locus.tools.desktop) + "open_path", + "app_control", + "window_control", + "system_control", + "clipboard", + "notify", + "screenshot", ) #: Agent mode tasks take more steps than chat; ``agent.max_turns`` can raise it. @@ -76,11 +85,70 @@ def _assistant_tools(config: Any) -> list: # folder unless the user configured something narrower or wider. if name in ("file_read", "file_write") and not kwargs.get("allowed_dirs"): kwargs["allowed_dirs"] = [str(Path.home())] + if name == "file_write": + # Same tool, but each change can be undone from the chat. + from locus.tools.undo_journal import UndoableFileWriteTool + + tool_cls = UndoableFileWriteTool tools.append(tool_cls(**kwargs)) return tools def _build_task_agent(state: Any) -> Any: + return _build_agent( + state, + tools=_assistant_tools(getattr(state, "config", None)), + agent_id=ASSISTANT_AGENT_ID, + ) + + +DEVELOPER_AGENT_ID = "developer" + +#: Developer agents kept per project folder (oldest dropped past this). +MAX_DEVELOPER_AGENTS = 8 + + +def get_developer_agent(state: Any, project_dir: Optional[str]) -> Any: + """The developer mode agent for *project_dir*. + + Raises ``ValueError`` (with a message for the user) if the folder can't + be used. + """ + from locus.server.developer import resolve_project_dir + + project = resolve_project_dir(project_dir) + with _build_lock: + agents = getattr(state, "developer_agents", None) + if agents is None: + agents = {} + state.developer_agents = agents + agent = agents.get(str(project)) + if agent is None: + agent = _build_developer_agent(state, project) + if len(agents) >= MAX_DEVELOPER_AGENTS: + agents.pop(next(iter(agents))) + agents[str(project)] = agent + return agent + + +def _build_developer_agent(state: Any, project: Path) -> Any: + from locus.server.developer import developer_prompt, developer_tools + + return _build_agent( + state, + tools=developer_tools(project, getattr(state, "config", None)), + agent_id=DEVELOPER_AGENT_ID, + system_prompt=developer_prompt(project), + ) + + +def _build_agent( + state: Any, + *, + tools: list, + agent_id: str, + system_prompt: Optional[str] = None, +) -> Any: import inspect import locus.agents # noqa: F401 # trigger registration @@ -96,8 +164,8 @@ def _build_task_agent(state: Any) -> Any: agent_cls = AgentRegistry.get("orchestrator") kwargs: dict[str, Any] = { "bus": bus, - "tools": _assistant_tools(config), - "agent_id": ASSISTANT_AGENT_ID, + "tools": tools, + "agent_id": 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 @@ -108,22 +176,28 @@ def _build_task_agent(state: Any) -> Any: # threads wouldn't see the run's approval session. "parallel_tools": False, } + if system_prompt: + kwargs["system_prompt"] = system_prompt if config is not None: 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 - - kwargs["prompt_builder"] = SystemPromptBuilder( - agent_template=config.agent.default_system_prompt or "", - memory_files_config=config.memory_files, - system_prompt_config=config.system_prompt, - ) + if ( + config is not None + and not system_prompt + and "prompt_builder" in inspect.signature(agent_cls.__init__).parameters + ): + from locus.prompt.builder import SystemPromptBuilder + + kwargs["prompt_builder"] = SystemPromptBuilder( + agent_template=config.agent.default_system_prompt or "", + memory_files_config=config.memory_files, + system_prompt_config=config.system_prompt, + ) kwargs.update( agent_security_kwargs( agent_cls, capability_policy=capability_policy, rate_limiter=rate_limiter, - agent_id=ASSISTANT_AGENT_ID, + agent_id=agent_id, ) ) @@ -133,7 +207,7 @@ def _build_task_agent(state: Any) -> Any: bus=bus, capability_policy=capability_policy, rate_limiter=rate_limiter, - agent_id=ASSISTANT_AGENT_ID, + agent_id=agent_id, ) return agent diff --git a/src/locus/tools/__init__.py b/src/locus/tools/__init__.py index ac5581d..a8a9602 100644 --- a/src/locus/tools/__init__.py +++ b/src/locus/tools/__init__.py @@ -183,4 +183,14 @@ except ImportError: pass +try: + import locus.tools.task_plan # noqa: F401 +except ImportError: + pass + +try: + import locus.tools.desktop # noqa: F401 +except ImportError: + pass + __all__ = ["BaseTool", "ToolExecutor", "ToolSpec"] diff --git a/src/locus/tools/desktop/__init__.py b/src/locus/tools/desktop/__init__.py new file mode 100644 index 0000000..1be3828 --- /dev/null +++ b/src/locus/tools/desktop/__init__.py @@ -0,0 +1,37 @@ +"""Desktop control tools: apps, windows, settings, clipboard, notifications. + +Windows is supported fully; macOS and Linux support what their standard +command-line tools allow, and say so when an action isn't available. +""" + +from __future__ import annotations + +from locus.tools.desktop.app_control import AppControlTool +from locus.tools.desktop.clipboard import ClipboardTool +from locus.tools.desktop.notify import NotifyTool +from locus.tools.desktop.open_path import OpenPathTool +from locus.tools.desktop.screenshot import ScreenshotTool +from locus.tools.desktop.system_control import SystemControlTool +from locus.tools.desktop.window_control import WindowControlTool + +#: Registry names of every desktop tool. +DESKTOP_TOOLS = ( + "open_path", + "app_control", + "window_control", + "system_control", + "clipboard", + "notify", + "screenshot", +) + +__all__ = [ + "DESKTOP_TOOLS", + "AppControlTool", + "ClipboardTool", + "NotifyTool", + "OpenPathTool", + "ScreenshotTool", + "SystemControlTool", + "WindowControlTool", +] diff --git a/src/locus/tools/desktop/_os.py b/src/locus/tools/desktop/_os.py new file mode 100644 index 0000000..3e7045b --- /dev/null +++ b/src/locus/tools/desktop/_os.py @@ -0,0 +1,113 @@ +"""Running OS commands for the desktop tools. + +Values from the model never go into a script's text: PowerShell scripts read +them from ``LOCUS_ARG_*`` environment variables, and other commands get them +as separate arguments, so a window title or file name can't inject a command. +""" + +from __future__ import annotations + +import os +import platform +import shutil +import subprocess +from dataclasses import dataclass +from typing import Dict, List, Optional + +from locus.core.types import ToolResult + +DEFAULT_TIMEOUT = 20.0 + + +def system() -> str: + """``"windows"``, ``"macos"`` or ``"linux"`` (anything else as reported).""" + name = platform.system().lower() + return {"darwin": "macos"}.get(name, name) + + +@dataclass +class Completed: + returncode: int + stdout: str + stderr: str + + @property + def ok(self) -> bool: + return self.returncode == 0 + + def error(self) -> str: + return (self.stderr or self.stdout).strip() or f"exit code {self.returncode}" + + +def run( + args: List[str], + *, + env: Optional[Dict[str, str]] = None, + input: Optional[str] = None, + timeout: float = DEFAULT_TIMEOUT, +) -> Completed: + """Run *args* without a shell and return its output.""" + full_env = {**os.environ, **(env or {})} + try: + proc = subprocess.run( + args, + input=input, + capture_output=True, + text=True, + encoding="utf-8", + errors="replace", + env=full_env, + timeout=timeout, + creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0), + ) + except FileNotFoundError: + return Completed(127, "", f"{args[0]} isn't installed") + except subprocess.TimeoutExpired: + return Completed(124, "", f"{args[0]} took longer than {timeout:.0f}s") + return Completed(proc.returncode, proc.stdout or "", proc.stderr or "") + + +def powershell( + script: str, + *, + args: Optional[Dict[str, str]] = None, + input: Optional[str] = None, + timeout: float = DEFAULT_TIMEOUT, +) -> Completed: + """Run a PowerShell *script*; *args* arrive as ``$env:LOCUS_ARG_``.""" + env = {f"LOCUS_ARG_{k.upper()}": str(v) for k, v in (args or {}).items()} + prelude = "[Console]::OutputEncoding = [Text.Encoding]::UTF8; " + if input is not None: + prelude += "[Console]::InputEncoding = [Text.Encoding]::UTF8; " + return run( + [ + "powershell.exe", + "-NoProfile", + "-NonInteractive", + "-Command", + prelude + script, + ], + env=env, + input=input, + timeout=timeout, + ) + + +def has_command(name: str) -> bool: + return shutil.which(name) is not None + + +def ok(tool: str, content: str, **metadata) -> ToolResult: + return ToolResult(tool_name=tool, content=content, success=True, metadata=metadata) + + +def fail(tool: str, content: str) -> ToolResult: + return ToolResult(tool_name=tool, content=content, success=False) + + +def unsupported(tool: str, what: str) -> ToolResult: + return fail(tool, f"{what} isn't supported on {system()} yet.") + + +def bad_action(tool: str, action: object, actions: tuple) -> ToolResult: + return fail(tool, f"Unknown action {action!r}. Use one of: {', '.join(actions)}.") diff --git a/src/locus/tools/desktop/app_control.py b/src/locus/tools/desktop/app_control.py new file mode 100644 index 0000000..b5cce93 --- /dev/null +++ b/src/locus/tools/desktop/app_control.py @@ -0,0 +1,167 @@ +"""List, open and close desktop apps.""" + +from __future__ import annotations + +import json +import os +import re +import shutil +import subprocess +from typing import Any + +from locus.core.registry import ToolRegistry +from locus.core.types import ToolResult +from locus.tools._stubs import BaseTool, ToolSpec +from locus.tools.desktop import _os + +ACTIONS = ("list", "open", "close") + +# App names only: no paths, switches or URL schemes. +_APP_NAME = re.compile(r"^[\w][\w .+\-]{0,63}$") + +_WIN_LIST = ( + "Get-Process | Where-Object { $_.MainWindowTitle } | " + "Select-Object ProcessName, Id, MainWindowTitle | ConvertTo-Json -Compress" +) +# CloseMainWindow asks the app to close, like clicking X: unsaved work prompts. +_WIN_CLOSE = ( + "$p = Get-Process -Name $env:LOCUS_ARG_NAME -ErrorAction Stop | " + "Where-Object { $_.MainWindowHandle -ne 0 }; " + "if (-not $p) { throw 'It has no open window.' }; " + "$p | ForEach-Object { [void]$_.CloseMainWindow() }; @($p).Count" +) +_MAC_QUIT = [ + "-e", + "on run argv", + "-e", + "tell application (item 1 of argv) to quit", + "-e", + "end run", +] + + +def _app_name(raw: object) -> str: + name = str(raw or "").strip() + if name.lower().endswith(".exe"): + name = name[:-4] + return name + + +@ToolRegistry.register("app_control") +class AppControlTool(BaseTool): + """See which apps are open, open an app, or ask an app to close.""" + + tool_id = "app_control" + + @property + def spec(self) -> ToolSpec: + return ToolSpec( + name="app_control", + description=( + "Work with desktop apps. 'list' shows apps that have a window" + " open. 'open' starts an app by name (for example notepad," + " calc, chrome, spotify). 'close' asks an app to close, like" + " clicking its X, so unsaved work isn't lost." + ), + parameters={ + "type": "object", + "properties": { + "action": {"type": "string", "enum": list(ACTIONS)}, + "name": { + "type": "string", + "description": "App name for open and close, without .exe.", + }, + }, + "required": ["action"], + }, + category="desktop", + ) + + def risk_for(self, arguments: dict) -> str: + return "read" if arguments.get("action") == "list" else "change" + + def execute(self, **params: Any) -> ToolResult: + action = params.get("action") + if action == "list": + return self._list() + if action not in ACTIONS: + return _os.bad_action("app_control", action, ACTIONS) + name = _app_name(params.get("name")) + if not _APP_NAME.match(name): + return _os.fail( + "app_control", "Give the app's name, like notepad or chrome." + ) + return self._open(name) if action == "open" else self._close(name) + + def _list(self) -> ToolResult: + os_name = _os.system() + if os_name == "windows": + done = _os.powershell(_WIN_LIST) + if not done.ok: + return _os.fail("app_control", f"Couldn't list apps: {done.error()}") + rows = json.loads(done.stdout or "[]") + rows = [rows] if isinstance(rows, dict) else rows + apps = [ + {"name": r["ProcessName"], "window": r["MainWindowTitle"]} for r in rows + ] + elif os_name == "macos": + done = _os.run( + [ + "osascript", + "-e", + 'tell application "System Events" to get name of ' + "(processes where background only is false)", + ] + ) + if not done.ok: + return _os.fail("app_control", f"Couldn't list apps: {done.error()}") + apps = [{"name": n.strip()} for n in done.stdout.split(",") if n.strip()] + else: + return _os.unsupported("app_control", "Listing apps") + return _os.ok("app_control", json.dumps(apps, ensure_ascii=False), apps=apps) + + def _open(self, name: str) -> ToolResult: + os_name = _os.system() + if os_name == "windows": + try: + os.startfile(name) # type: ignore[attr-defined] + except OSError: + return _os.fail( + "app_control", + f"Couldn't find an app called {name}. Try its program name," + " like msedge for Edge or winword for Word.", + ) + return _os.ok("app_control", f"Opened {name}.") + if os_name == "macos": + done = _os.run(["open", "-a", name]) + if not done.ok: + return _os.fail("app_control", f"Couldn't open {name}: {done.error()}") + return _os.ok("app_control", f"Opened {name}.") + if os_name == "linux": + program = shutil.which(name) + if program is None: + return _os.fail("app_control", f"Couldn't find an app called {name}.") + subprocess.Popen( + [program], + stdin=subprocess.DEVNULL, + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + start_new_session=True, + ) + return _os.ok("app_control", f"Opened {name}.") + return _os.unsupported("app_control", "Opening apps") + + def _close(self, name: str) -> ToolResult: + os_name = _os.system() + if os_name == "windows": + done = _os.powershell(_WIN_CLOSE, args={"name": name}) + elif os_name == "macos": + done = _os.run(["osascript", *_MAC_QUIT, name]) + else: + return _os.unsupported("app_control", "Closing apps") + if not done.ok: + return _os.fail("app_control", f"Couldn't close {name}: {done.error()}") + return _os.ok("app_control", f"Asked {name} to close.") + + +__all__ = ["AppControlTool"] diff --git a/src/locus/tools/desktop/clipboard.py b/src/locus/tools/desktop/clipboard.py new file mode 100644 index 0000000..324ea14 --- /dev/null +++ b/src/locus/tools/desktop/clipboard.py @@ -0,0 +1,108 @@ +"""Read and write the clipboard's text.""" + +from __future__ import annotations + +from typing import Any + +from locus.core.registry import ToolRegistry +from locus.core.types import ToolResult +from locus.tools._stubs import BaseTool, ToolSpec +from locus.tools.desktop import _os + +ACTIONS = ("read", "write") + +#: Long clipboard contents are cut so they don't flood the model's context. +MAX_READ_CHARS = 10_000 + + +def _linux_commands(action: str) -> list[list[str]]: + if action == "read": + return [ + ["wl-paste", "--no-newline"], + ["xclip", "-selection", "clipboard", "-o"], + ] + return [["wl-copy"], ["xclip", "-selection", "clipboard"]] + + +@ToolRegistry.register("clipboard") +class ClipboardTool(BaseTool): + """Copy text to, or read text from, the clipboard.""" + + tool_id = "clipboard" + + @property + def spec(self) -> ToolSpec: + return ToolSpec( + name="clipboard", + description=( + "'read' returns the text on the clipboard. 'write' puts 'text'" + " on the clipboard so the user can paste it." + ), + parameters={ + "type": "object", + "properties": { + "action": {"type": "string", "enum": list(ACTIONS)}, + "text": { + "type": "string", + "description": "Text to copy, for write.", + }, + }, + "required": ["action"], + }, + category="desktop", + ) + + def risk_for(self, arguments: dict) -> str: + # Reading can expose passwords or private text the user copied. + return "change" + + def execute(self, **params: Any) -> ToolResult: + action = params.get("action") + if action not in ACTIONS: + return _os.bad_action("clipboard", action, ACTIONS) + text = str(params.get("text") or "") + if action == "write" and not text: + return _os.fail("clipboard", "Give the text to copy.") + + os_name = _os.system() + if os_name == "windows": + done = ( + _os.powershell("Get-Clipboard -Raw") + if action == "read" + else _os.powershell( + "Set-Clipboard -Value ([Console]::In.ReadToEnd())", input=text + ) + ) + elif os_name == "macos": + done = ( + _os.run(["pbpaste"]) + if action == "read" + else _os.run(["pbcopy"], input=text) + ) + elif os_name == "linux": + commands = [c for c in _linux_commands(action) if _os.has_command(c[0])] + if not commands: + return _os.fail( + "clipboard", "Install wl-clipboard or xclip to use the clipboard." + ) + done = _os.run(commands[0], input=None if action == "read" else text) + else: + return _os.unsupported("clipboard", "The clipboard") + if not done.ok: + return _os.fail("clipboard", f"Couldn't use the clipboard: {done.error()}") + + if action == "write": + return _os.ok( + "clipboard", f"Copied {len(text)} characters to the clipboard." + ) + content = done.stdout.rstrip("\r\n") if os_name == "windows" else done.stdout + if not content: + return _os.ok("clipboard", "The clipboard has no text.") + if len(content) > MAX_READ_CHARS: + content = ( + content[:MAX_READ_CHARS] + "\n[cut off: the clipboard has more text]" + ) + return _os.ok("clipboard", content) + + +__all__ = ["ClipboardTool"] diff --git a/src/locus/tools/desktop/notify.py b/src/locus/tools/desktop/notify.py new file mode 100644 index 0000000..b9f46f9 --- /dev/null +++ b/src/locus/tools/desktop/notify.py @@ -0,0 +1,284 @@ +"""Desktop notifications, now or later (timers and reminders). + +Reminders are saved in ``~/.locus/reminders.json``, so they survive a +restart: :func:`restore_reminders` (called when ``locus serve`` starts) +schedules them again and shows any that came due while Locus was closed. +""" + +from __future__ import annotations + +import json +import threading +import time +import uuid +from pathlib import Path +from typing import Any, Dict, List, Optional + +from locus.core.registry import ToolRegistry +from locus.core.types import ToolResult +from locus.tools._stubs import BaseTool, ToolSpec +from locus.tools.desktop import _os + +ACTIONS = ("notify", "list_reminders", "cancel_reminder") + +#: Longest delay for a reminder (30 days). +MAX_DELAY_MINUTES = 30 * 24 * 60 + +# Toasts need an app id Windows knows; PowerShell's is always registered. +_WIN_TOAST = ( + "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications," + " ContentType = WindowsRuntime] | Out-Null; " + "$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent(" + "[Windows.UI.Notifications.ToastTemplateType]::ToastText02); " + "$text = $xml.GetElementsByTagName('text'); " + "[void]$text.Item(0).AppendChild($xml.CreateTextNode($env:LOCUS_ARG_TITLE)); " + "[void]$text.Item(1).AppendChild($xml.CreateTextNode($env:LOCUS_ARG_MESSAGE)); " + "$toast = [Windows.UI.Notifications.ToastNotification]::new($xml); " + "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier(" + "'{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe'" + ").Show($toast)" +) +_MAC_NOTIFY = [ + "-e", + "on run argv", + "-e", + "display notification (item 2 of argv) with title (item 1 of argv)", + "-e", + "end run", +] + + +def show_notification(title: str, message: str) -> _os.Completed: + os_name = _os.system() + if os_name == "windows": + return _os.powershell(_WIN_TOAST, args={"title": title, "message": message}) + if os_name == "macos": + return _os.run(["osascript", *_MAC_NOTIFY, title, message]) + if os_name == "linux": + return _os.run(["notify-send", title, message]) + return _os.Completed(1, "", f"Notifications aren't supported on {os_name} yet.") + + +# ── Saved reminders ────────────────────────────────────────────── + + +class ReminderStore: + """Pending reminders: ``{id, title, message, due_at}`` (epoch seconds).""" + + def __init__(self, path: Optional[Path] = None) -> None: + if path is None: + from locus.core.paths import get_config_dir + + path = Path(get_config_dir()) / "reminders.json" + self.path = Path(path) + self._lock = threading.Lock() + + def _load(self) -> List[Dict[str, Any]]: + try: + rows = json.loads(self.path.read_text(encoding="utf-8")) + except (OSError, ValueError): + return [] + return [r for r in rows if isinstance(r, dict) and r.get("id")] + + def _save(self, rows: List[Dict[str, Any]]) -> None: + self.path.parent.mkdir(parents=True, exist_ok=True) + tmp = self.path.with_suffix(".tmp") + tmp.write_text(json.dumps(rows, indent=2), encoding="utf-8") + tmp.replace(self.path) + + def add(self, title: str, message: str, due_at: float) -> Dict[str, Any]: + entry = { + "id": uuid.uuid4().hex[:8], + "title": title, + "message": message, + "due_at": due_at, + } + with self._lock: + self._save(self._load() + [entry]) + return entry + + def remove(self, reminder_id: str) -> bool: + with self._lock: + rows = self._load() + kept = [r for r in rows if r["id"] != reminder_id] + if len(kept) == len(rows): + return False + self._save(kept) + return True + + def all(self) -> List[Dict[str, Any]]: + with self._lock: + return sorted(self._load(), key=lambda r: r.get("due_at", 0)) + + +_store: Optional[ReminderStore] = None +_timers: Dict[str, threading.Timer] = {} +_timers_lock = threading.Lock() + + +def get_store() -> ReminderStore: + global _store + with _timers_lock: + if _store is None: + _store = ReminderStore() + return _store + + +def _fire(entry: Dict[str, Any], missed: bool = False) -> None: + title = entry["title"] + (" (missed while Locus was closed)" if missed else "") + show_notification(title, entry["message"]) + get_store().remove(entry["id"]) + with _timers_lock: + _timers.pop(entry["id"], None) + + +def _schedule(entry: Dict[str, Any]) -> None: + delay = max(0.0, float(entry["due_at"]) - time.time()) + timer = threading.Timer(delay, _fire, args=(entry,)) + timer.daemon = True + with _timers_lock: + if entry["id"] in _timers: + return + _timers[entry["id"]] = timer + timer.start() + + +def restore_reminders() -> int: + """Schedule saved reminders again; show any that came due while closed. + + Returns how many reminders were restored. + """ + now = time.time() + entries = get_store().all() + for entry in entries: + if float(entry.get("due_at", 0)) <= now: + threading.Thread(target=_fire, args=(entry, True), daemon=True).start() + else: + _schedule(entry) + return len(entries) + + +def _when(seconds: float) -> str: + minutes = seconds / 60 + if minutes < 90: + return f"{minutes:g} minute" + ("" if minutes == 1 else "s") + return time.strftime("%a %d %b at %H:%M", time.localtime(time.time() + seconds)) + + +# ── Tool ───────────────────────────────────────────────────────── + + +@ToolRegistry.register("notify") +class NotifyTool(BaseTool): + """Show a desktop notification now, or set, list or cancel reminders.""" + + tool_id = "notify" + + @property + def spec(self) -> ToolSpec: + return ToolSpec( + name="notify", + description=( + "Desktop notifications and reminders. 'notify' (the default)" + " shows 'message' now, or after 'delay_minutes' as a timer or" + " reminder (up to 30 days; saved, so it still comes after" + " Locus restarts). 'list_reminders' shows pending reminders;" + " 'cancel_reminder' cancels the one with 'id'." + ), + parameters={ + "type": "object", + "properties": { + "action": {"type": "string", "enum": list(ACTIONS)}, + "title": {"type": "string", "description": "Short heading."}, + "message": { + "type": "string", + "description": "The notification text.", + }, + "delay_minutes": { + "type": "number", + "description": "Minutes to wait; 0 or empty shows it now.", + }, + "id": { + "type": "string", + "description": "Reminder id, for cancel_reminder.", + }, + }, + }, + category="desktop", + ) + + def risk_for(self, arguments: dict) -> str: + return "read" + + def execute(self, **params: Any) -> ToolResult: + action = params.get("action") or "notify" + if action not in ACTIONS: + return _os.bad_action("notify", action, ACTIONS) + if action == "list_reminders": + return self._list() + if action == "cancel_reminder": + return self._cancel(str(params.get("id") or "")) + + message = str(params.get("message") or "").strip() + if not message: + return _os.fail("notify", "Give the notification text.") + title = str(params.get("title") or "Locus").strip() or "Locus" + try: + delay = float(params.get("delay_minutes") or 0) + except (TypeError, ValueError): + return _os.fail("notify", "delay_minutes must be a number.") + if not 0 <= delay <= MAX_DELAY_MINUTES: + return _os.fail( + "notify", "delay_minutes must be from 0 to 43200 (30 days)." + ) + + if delay == 0: + done = show_notification(title, message) + if not done.ok: + return _os.fail( + "notify", f"Couldn't show the notification: {done.error()}" + ) + return _os.ok("notify", f"Showed the notification {title!r}.") + + entry = get_store().add(title, message, time.time() + delay * 60) + _schedule(entry) + return _os.ok( + "notify", + f"Set a reminder {title!r} for {_when(delay * 60)} from now" + f" (id {entry['id']}). If Locus is closed then, it shows the next" + " time Locus starts.", + reminder=entry, + ) + + @staticmethod + def _list() -> ToolResult: + entries = get_store().all() + if not entries: + return _os.ok("notify", "No reminders are set.", reminders=[]) + lines = [ + f"{e['id']}: {e['title']} - {e['message']} (in " + f"{_when(max(0.0, e['due_at'] - time.time()))})" + for e in entries + ] + return _os.ok("notify", "\n".join(lines), reminders=entries) + + @staticmethod + def _cancel(reminder_id: str) -> ToolResult: + if not reminder_id: + return _os.fail("notify", "Give the reminder's id (see list_reminders).") + if not get_store().remove(reminder_id): + return _os.fail("notify", f"No reminder has the id {reminder_id!r}.") + with _timers_lock: + timer = _timers.pop(reminder_id, None) + if timer is not None: + timer.cancel() + return _os.ok("notify", f"Cancelled reminder {reminder_id}.") + + +__all__ = [ + "NotifyTool", + "ReminderStore", + "get_store", + "restore_reminders", + "show_notification", +] diff --git a/src/locus/tools/desktop/open_path.py b/src/locus/tools/desktop/open_path.py new file mode 100644 index 0000000..94afffc --- /dev/null +++ b/src/locus/tools/desktop/open_path.py @@ -0,0 +1,118 @@ +"""Open a file, folder or web page in its default app.""" + +from __future__ import annotations + +import os +from pathlib import Path +from typing import Any +from urllib.parse import urlparse + +from locus.core.registry import ToolRegistry +from locus.core.types import ToolResult +from locus.tools._stubs import BaseTool, ToolSpec +from locus.tools.desktop import _os + +#: Opening these runs a program, so the user is always asked. +EXECUTABLE_SUFFIXES = frozenset( + { + ".exe", + ".msi", + ".bat", + ".cmd", + ".com", + ".ps1", + ".vbs", + ".vbe", + ".js", + ".jse", + ".wsf", + ".wsh", + ".scr", + ".lnk", + ".url", + ".hta", + ".cpl", + ".msc", + ".jar", + ".app", + ".command", + ".sh", + ".appimage", + ".run", + } +) + + +def _is_url(target: str) -> bool: + return urlparse(target).scheme in ("http", "https") + + +@ToolRegistry.register("open_path") +class OpenPathTool(BaseTool): + """Open a file, folder or http(s) link the way double-clicking would.""" + + tool_id = "open_path" + + @property + def spec(self) -> ToolSpec: + return ToolSpec( + name="open_path", + description=( + "Open a file or folder in its default app (for example a PDF in" + " the PDF reader, or a folder in File Explorer), or an http(s)" + " link in the default browser. Use ~ for the home folder." + ), + parameters={ + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "File or folder path, or an http(s) URL.", + }, + }, + "required": ["path"], + }, + category="desktop", + ) + + def risk_for(self, arguments: dict) -> str: + target = str(arguments.get("path", "")) + if _is_url(target): + return "change" + if Path(target).suffix.lower() in EXECUTABLE_SUFFIXES: + return "run" + return "read" + + def execute(self, **params: Any) -> ToolResult: + target = str(params.get("path", "")).strip() + if not target: + return _os.fail("open_path", "Give a file, folder or link to open.") + if not _is_url(target): + # A drive letter (C:\...) parses as a one-letter scheme; any longer + # scheme (mailto:, ms-settings:, file:) isn't a plain local path. + if len(urlparse(target).scheme) > 1: + return _os.fail("open_path", "Only http and https links can be opened.") + path = Path(target).expanduser() + if not path.exists(): + return _os.fail("open_path", f"{path} doesn't exist.") + target = str(path.resolve()) + + os_name = _os.system() + if os_name == "windows": + try: + os.startfile(target) # type: ignore[attr-defined] + except OSError as exc: + return _os.fail("open_path", f"Couldn't open {target}: {exc}") + return _os.ok("open_path", f"Opened {target}.") + if os_name == "macos": + done = _os.run(["open", target]) + elif os_name == "linux": + done = _os.run(["xdg-open", target]) + else: + return _os.unsupported("open_path", "Opening files") + if not done.ok: + return _os.fail("open_path", f"Couldn't open {target}: {done.error()}") + return _os.ok("open_path", f"Opened {target}.") + + +__all__ = ["OpenPathTool", "EXECUTABLE_SUFFIXES"] diff --git a/src/locus/tools/desktop/screenshot.py b/src/locus/tools/desktop/screenshot.py new file mode 100644 index 0000000..ed34235 --- /dev/null +++ b/src/locus/tools/desktop/screenshot.py @@ -0,0 +1,80 @@ +"""Save a screenshot of the whole screen.""" + +from __future__ import annotations + +import time +from pathlib import Path +from typing import Any + +from locus.core.registry import ToolRegistry +from locus.core.types import ToolResult +from locus.tools._stubs import BaseTool, ToolSpec +from locus.tools.desktop import _os + +_WIN_SCREENSHOT = ( + "Add-Type -AssemblyName System.Windows.Forms, System.Drawing; " + "$b = [System.Windows.Forms.SystemInformation]::VirtualScreen; " + "$img = New-Object System.Drawing.Bitmap $b.Width, $b.Height; " + "$g = [System.Drawing.Graphics]::FromImage($img); " + "$g.CopyFromScreen($b.Left, $b.Top, 0, 0, $img.Size); " + "$img.Save($env:LOCUS_ARG_PATH, [System.Drawing.Imaging.ImageFormat]::Png); " + "$g.Dispose(); $img.Dispose()" +) + + +def screenshots_dir() -> Path: + from locus.core.paths import get_config_dir + + return Path(get_config_dir()) / "screenshots" + + +@ToolRegistry.register("screenshot") +class ScreenshotTool(BaseTool): + """Capture every screen into a PNG in Locus's screenshots folder.""" + + tool_id = "screenshot" + + @property + def spec(self) -> ToolSpec: + return ToolSpec( + name="screenshot", + description=( + "Take a screenshot of the whole screen and save it as a PNG." + " Returns the file's path." + ), + parameters={"type": "object", "properties": {}}, + category="desktop", + ) + + def risk_for(self, arguments: dict) -> str: + # The screen can show private messages, passwords or documents. + return "change" + + def execute(self, **params: Any) -> ToolResult: + folder = screenshots_dir() + folder.mkdir(parents=True, exist_ok=True) + path = folder / time.strftime("screenshot-%Y%m%d-%H%M%S.png") + + os_name = _os.system() + if os_name == "windows": + done = _os.powershell(_WIN_SCREENSHOT, args={"path": str(path)}) + elif os_name == "macos": + done = _os.run(["screencapture", "-x", str(path)]) + elif os_name == "linux": + if _os.has_command("gnome-screenshot"): + done = _os.run(["gnome-screenshot", "-f", str(path)]) + elif _os.has_command("grim"): + done = _os.run(["grim", str(path)]) + else: + return _os.fail( + "screenshot", + "Install gnome-screenshot or grim to take screenshots.", + ) + else: + return _os.unsupported("screenshot", "Screenshots") + if not done.ok or not path.exists(): + return _os.fail("screenshot", f"Couldn't take a screenshot: {done.error()}") + return _os.ok("screenshot", f"Saved a screenshot to {path}.", path=str(path)) + + +__all__ = ["ScreenshotTool", "screenshots_dir"] diff --git a/src/locus/tools/desktop/system_control.py b/src/locus/tools/desktop/system_control.py new file mode 100644 index 0000000..e99f52f --- /dev/null +++ b/src/locus/tools/desktop/system_control.py @@ -0,0 +1,450 @@ +"""Volume, mute, screen brightness, dark mode and locking the screen.""" + +from __future__ import annotations + +import re +from typing import Any, Optional + +from locus.core.registry import ToolRegistry +from locus.core.types import ToolResult +from locus.tools._stubs import BaseTool, ToolSpec +from locus.tools.desktop import _os + +ACTIONS = ( + "get_volume", + "set_volume", + "mute", + "unmute", + "set_brightness", + "dark_mode", + "light_mode", + "lock_screen", + "get_radios", + "wifi_on", + "wifi_off", + "bluetooth_on", + "bluetooth_off", +) + +#: action -> (radio, turn on?) +_RADIO_ACTIONS = { + "wifi_on": ("wifi", True), + "wifi_off": ("wifi", False), + "bluetooth_on": ("bluetooth", True), + "bluetooth_off": ("bluetooth", False), +} + +# Core Audio's endpoint volume for the default output device. The method +# order in each interface must match the COM vtable, hence the placeholders. +_WIN_AUDIO = """Add-Type -TypeDefinition @' +using System; +using System.Runtime.InteropServices; +[Guid("5CDF2C82-841E-4546-9722-0CF74078229A"), + InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] +interface IAudioEndpointVolume { + int f(); int g(); int h(); int i(); + int SetMasterVolumeLevelScalar(float fLevel, Guid pguidEventContext); + int j(); + int GetMasterVolumeLevelScalar(out float pfLevel); + int k(); int l(); int m(); int n(); + int SetMute([MarshalAs(UnmanagedType.Bool)] bool bMute, Guid pguidEventContext); + int GetMute(out bool pbMute); +} +[Guid("D666063F-1587-4E43-81F1-B948E807363F"), + InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] +interface IMMDevice { + int Activate(ref Guid id, int clsCtx, int activationParams, + out IAudioEndpointVolume aev); +} +[Guid("A95664D2-9614-4F35-A746-DE8DB63617E6"), + InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] +interface IMMDeviceEnumerator { + int f(); + int GetDefaultAudioEndpoint(int dataFlow, int role, out IMMDevice endpoint); +} +[ComImport, Guid("BCDE0395-E52F-467C-8E3D-C4579291692E")] +class MMDeviceEnumeratorComObject { } +public class LocusAudio { + static IAudioEndpointVolume Endpoint() { + var devices = new MMDeviceEnumeratorComObject() as IMMDeviceEnumerator; + IMMDevice device; + Marshal.ThrowExceptionForHR(devices.GetDefaultAudioEndpoint(0, 1, out device)); + IAudioEndpointVolume volume; + var id = typeof(IAudioEndpointVolume).GUID; + Marshal.ThrowExceptionForHR(device.Activate(ref id, 23, 0, out volume)); + return volume; + } + public static float Volume { + get { + float v; + Marshal.ThrowExceptionForHR(Endpoint().GetMasterVolumeLevelScalar(out v)); + return v; + } + set { + Marshal.ThrowExceptionForHR( + Endpoint().SetMasterVolumeLevelScalar(value, Guid.Empty)); + } + } + public static bool Mute { + get { bool m; Marshal.ThrowExceptionForHR(Endpoint().GetMute(out m)); return m; } + set { Marshal.ThrowExceptionForHR(Endpoint().SetMute(value, Guid.Empty)); } + } +} +'@ +""" +_WIN_GET_VOLUME = _WIN_AUDIO + ( + "'{0} {1}' -f [Math]::Round([LocusAudio]::Volume * 100), [LocusAudio]::Mute" +) +_WIN_SET_VOLUME = _WIN_AUDIO + ( + "[LocusAudio]::Mute = $false; " + "[LocusAudio]::Volume = [float]$env:LOCUS_ARG_LEVEL / 100" +) +_WIN_SET_MUTE = _WIN_AUDIO + "[LocusAudio]::Mute = [bool][int]$env:LOCUS_ARG_MUTE" +_WIN_SET_BRIGHTNESS = ( + "Get-CimInstance -Namespace root/WMI -ClassName WmiMonitorBrightnessMethods" + " -ErrorAction Stop | Invoke-CimMethod -MethodName WmiSetBrightness" + " -Arguments @{Timeout = 1; Brightness = [byte]$env:LOCUS_ARG_LEVEL}" + " | Out-Null" +) +_WIN_PERSONALIZE = r"Software\Microsoft\Windows\CurrentVersion\Themes\Personalize" + +# Windows.Devices.Radios switches Wi-Fi and Bluetooth without admin rights. +# PowerShell 5.1 waits on its async calls through WindowsRuntime's AsTask. +_WIN_RADIOS = """Add-Type -AssemblyName System.Runtime.WindowsRuntime +$asTask = [System.WindowsRuntimeSystemExtensions].GetMethods() | Where-Object { + $_.Name -eq 'AsTask' -and $_.GetParameters().Count -eq 1 -and + $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation`1' } | + Select-Object -First 1 +function Await($op, [Type]$type) { + $t = $asTask.MakeGenericMethod($type).Invoke($null, @($op)) + $t.Wait(-1) | Out-Null + $t.Result +} +[Windows.Devices.Radios.Radio, Windows.System.Devices, ContentType = WindowsRuntime] | + Out-Null +$listType = [System.Collections.Generic.IReadOnlyList[Windows.Devices.Radios.Radio]] +$radios = Await ([Windows.Devices.Radios.Radio]::GetRadiosAsync()) $listType +""" +_WIN_GET_RADIOS = ( + _WIN_RADIOS + "$radios | ForEach-Object { '{0} {1}' -f $_.Kind, $_.State }" +) +_WIN_SET_RADIO = ( + _WIN_RADIOS + + """$status = [Windows.Devices.Radios.RadioAccessStatus] +$access = Await ([Windows.Devices.Radios.Radio]::RequestAccessAsync()) $status +if ($access -ne 'Allowed') { throw "Windows didn't allow it ($access)." } +$radio = $radios | Where-Object { $_.Kind -eq $env:LOCUS_ARG_KIND } | + Select-Object -First 1 +if (-not $radio) { throw "This computer has no $env:LOCUS_ARG_KIND radio." } +$state = [Windows.Devices.Radios.RadioState]$env:LOCUS_ARG_STATE +$result = Await ($radio.SetStateAsync($state)) $status +if ($result -ne 'Allowed') { throw "Windows didn't change it ($result)." } +""" +) + + +def _level(raw: object) -> Optional[int]: + try: + level = int(round(float(raw))) # type: ignore[arg-type] + except (TypeError, ValueError): + return None + return level if 0 <= level <= 100 else None + + +def _windows_dark_mode(dark: bool) -> None: + import ctypes + import winreg + + with winreg.OpenKey( + winreg.HKEY_CURRENT_USER, _WIN_PERSONALIZE, 0, winreg.KEY_SET_VALUE + ) as key: + for name in ("AppsUseLightTheme", "SystemUsesLightTheme"): + winreg.SetValueEx(key, name, 0, winreg.REG_DWORD, 0 if dark else 1) + # Tell open windows the theme changed (HWND_BROADCAST, WM_SETTINGCHANGE). + result = ctypes.c_ulong() + ctypes.windll.user32.SendMessageTimeoutW( # type: ignore[attr-defined] + 0xFFFF, 0x001A, 0, "ImmersiveColorSet", 0x0002, 2000, ctypes.byref(result) + ) + + +@ToolRegistry.register("system_control") +class SystemControlTool(BaseTool): + """Change everyday system settings on the user's computer.""" + + tool_id = "system_control" + + @property + def spec(self) -> ToolSpec: + return ToolSpec( + name="system_control", + description=( + "Everyday computer settings. 'get_volume' reads the speaker" + " volume (0-100) and whether it's muted. 'set_volume' sets it" + " to 'level' (0-100) and unmutes. 'mute' and 'unmute' the" + " speakers. 'set_brightness' sets a laptop screen to 'level'" + " (0-100). 'dark_mode' and 'light_mode' switch the theme." + " 'lock_screen' locks the computer. 'get_radios' reports" + " whether Wi-Fi and Bluetooth are on; 'wifi_on', 'wifi_off'," + " 'bluetooth_on' and 'bluetooth_off' switch them." + ), + parameters={ + "type": "object", + "properties": { + "action": {"type": "string", "enum": list(ACTIONS)}, + "level": { + "type": "number", + "description": "0-100, for set_volume and set_brightness.", + }, + }, + "required": ["action"], + }, + category="desktop", + ) + + def risk_for(self, arguments: dict) -> str: + read_only = ("get_volume", "get_radios") + return "read" if arguments.get("action") in read_only else "change" + + def execute(self, **params: Any) -> ToolResult: + action = params.get("action") + if action not in ACTIONS: + return _os.bad_action("system_control", action, ACTIONS) + level = _level(params.get("level")) + if action in ("set_volume", "set_brightness") and level is None: + return _os.fail("system_control", "Give a level from 0 to 100.") + if action == "get_radios" or action in _RADIO_ACTIONS: + return self._radios(action) + handler = { + "windows": self._windows, + "macos": self._macos, + "linux": self._linux, + }.get(_os.system()) + if handler is None: + return _os.unsupported("system_control", "Changing settings") + return handler(action, level) + + # ── Windows ────────────────────────────────────────────────── + + def _windows(self, action: str, level: Optional[int]) -> ToolResult: + if action == "lock_screen": + import ctypes + + if not ctypes.windll.user32.LockWorkStation(): # type: ignore[attr-defined] + return _os.fail("system_control", "Windows didn't lock the screen.") + return _os.ok("system_control", "Locked the screen.") + if action in ("dark_mode", "light_mode"): + try: + _windows_dark_mode(action == "dark_mode") + except OSError as exc: + return _os.fail("system_control", f"Couldn't change the theme: {exc}") + return _os.ok("system_control", f"Switched to {action.replace('_', ' ')}.") + if action == "get_volume": + done = _os.powershell(_WIN_GET_VOLUME) + if not done.ok: + return _os.fail( + "system_control", f"Couldn't read the volume: {done.error()}" + ) + volume, muted = done.stdout.split() + return self._volume_result(int(volume), muted.lower() == "true") + if action == "set_volume": + done = _os.powershell(_WIN_SET_VOLUME, args={"level": level}) + elif action in ("mute", "unmute"): + done = _os.powershell(_WIN_SET_MUTE, args={"mute": int(action == "mute")}) + else: # set_brightness + done = _os.powershell(_WIN_SET_BRIGHTNESS, args={"level": level}) + if not done.ok: + return _os.fail( + "system_control", + "Couldn't set the brightness. Windows can only change it" + " on built-in laptop screens.", + ) + if not done.ok: + return _os.fail( + "system_control", f"Couldn't change the volume: {done.error()}" + ) + return self._done(action, level) + + # ── macOS ──────────────────────────────────────────────────── + + def _macos(self, action: str, level: Optional[int]) -> ToolResult: + scripts = { + "get_volume": 'get (output volume of (get volume settings)) & " " & ' + "(output muted of (get volume settings))", + "set_volume": f"set volume output volume {level} without output muted", + "mute": "set volume with output muted", + "unmute": "set volume without output muted", + "dark_mode": 'tell application "System Events" to tell appearance ' + "preferences to set dark mode to true", + "light_mode": 'tell application "System Events" to tell appearance ' + "preferences to set dark mode to false", + } + if action == "lock_screen": + done = _os.run(["pmset", "displaysleepnow"]) + elif action in scripts: + done = _os.run(["osascript", "-e", scripts[action]]) + else: + return _os.unsupported("system_control", "Changing the brightness") + if not done.ok: + return _os.fail("system_control", f"That didn't work: {done.error()}") + if action == "get_volume": + volume, muted = done.stdout.split() + return self._volume_result(int(volume), muted == "true") + return self._done(action, level) + + # ── Linux (PulseAudio or PipeWire, systemd) ────────────────── + + def _linux(self, action: str, level: Optional[int]) -> ToolResult: + sink = "@DEFAULT_SINK@" + if action == "lock_screen": + done = _os.run(["loginctl", "lock-session"]) + elif action == "get_volume": + done = _os.run(["pactl", "get-sink-volume", sink]) + muted = _os.run(["pactl", "get-sink-mute", sink]) + match = re.search(r"(\d+)%", done.stdout) + if not done.ok or not match: + return _os.fail( + "system_control", f"Couldn't read the volume: {done.error()}" + ) + return self._volume_result(int(match.group(1)), "yes" in muted.stdout) + elif action == "set_volume": + _os.run(["pactl", "set-sink-mute", sink, "0"]) + done = _os.run(["pactl", "set-sink-volume", sink, f"{level}%"]) + elif action in ("mute", "unmute"): + done = _os.run( + ["pactl", "set-sink-mute", sink, "1" if action == "mute" else "0"] + ) + else: + return _os.unsupported( + "system_control", action.replace("_", " ").capitalize() + ) + if not done.ok: + return _os.fail("system_control", f"That didn't work: {done.error()}") + return self._done(action, level) + + # ── Wi-Fi and Bluetooth ────────────────────────────────────── + + def _radios(self, action: str) -> ToolResult: + os_name = _os.system() + if action == "get_radios": + states = { + "windows": self._windows_radio_states, + "macos": self._macos_radio_states, + "linux": self._linux_radio_states, + }.get(os_name) + if states is None: + return _os.unsupported("system_control", "Wi-Fi and Bluetooth") + found = states() + if isinstance(found, ToolResult): + return found + text = "; ".join( + f"{name}: {'on' if on else 'off'}" for name, on in found.items() + ) + return _os.ok( + "system_control", text or "No Wi-Fi or Bluetooth found.", radios=found + ) + + radio, on = _RADIO_ACTIONS[action] + label = "Wi-Fi" if radio == "wifi" else "Bluetooth" + if os_name == "windows": + done = _os.powershell( + _WIN_SET_RADIO, + args={ + "kind": "WiFi" if radio == "wifi" else "Bluetooth", + "state": "On" if on else "Off", + }, + timeout=40, + ) + elif os_name == "macos": + if radio == "wifi": + device = self._macos_wifi_device() + if device is None: + return _os.fail("system_control", "This Mac has no Wi-Fi.") + done = _os.run( + ["networksetup", "-setairportpower", device, "on" if on else "off"] + ) + elif _os.has_command("blueutil"): + done = _os.run(["blueutil", "--power", "1" if on else "0"]) + else: + return _os.fail( + "system_control", "Install blueutil to switch Bluetooth on a Mac." + ) + elif os_name == "linux": + if radio == "wifi": + done = _os.run(["nmcli", "radio", "wifi", "on" if on else "off"]) + else: + done = _os.run(["rfkill", "unblock" if on else "block", "bluetooth"]) + else: + return _os.unsupported("system_control", "Wi-Fi and Bluetooth") + if not done.ok: + return _os.fail( + "system_control", f"Couldn't switch {label}: {done.error()}" + ) + return _os.ok("system_control", f"Turned {label} {'on' if on else 'off'}.") + + @staticmethod + def _windows_radio_states(): + done = _os.powershell(_WIN_GET_RADIOS, timeout=40) + if not done.ok: + return _os.fail( + "system_control", f"Couldn't read Wi-Fi and Bluetooth: {done.error()}" + ) + names = {"wifi": "Wi-Fi", "bluetooth": "Bluetooth"} + found = {} + for line in done.stdout.splitlines(): + parts = line.split() + if len(parts) == 2 and parts[0].lower() in names: + found[names[parts[0].lower()]] = parts[1].lower() == "on" + return found + + @staticmethod + def _macos_wifi_device() -> Optional[str]: + done = _os.run(["networksetup", "-listallhardwareports"]) + match = re.search( + r"Hardware Port: (?:Wi-Fi|AirPort)\s*\nDevice: (\S+)", done.stdout + ) + return match.group(1) if match else None + + def _macos_radio_states(self): + found = {} + device = self._macos_wifi_device() + if device: + done = _os.run(["networksetup", "-getairportpower", device]) + found["Wi-Fi"] = done.stdout.strip().lower().endswith("on") + if _os.has_command("blueutil"): + done = _os.run(["blueutil", "--power"]) + found["Bluetooth"] = done.stdout.strip() == "1" + return found + + @staticmethod + def _linux_radio_states(): + found = {} + wifi = _os.run(["nmcli", "radio", "wifi"]) + if wifi.ok: + found["Wi-Fi"] = wifi.stdout.strip() == "enabled" + bluetooth = _os.run(["rfkill", "list", "bluetooth"]) + if bluetooth.ok and bluetooth.stdout.strip(): + found["Bluetooth"] = "Soft blocked: yes" not in bluetooth.stdout + return found + + # ── Results ────────────────────────────────────────────────── + + @staticmethod + def _volume_result(volume: int, muted: bool) -> ToolResult: + text = f"Volume is {volume}%" + (" and muted." if muted else ".") + return _os.ok("system_control", text, volume=volume, muted=muted) + + @staticmethod + def _done(action: str, level: Optional[int]) -> ToolResult: + text = { + "set_volume": f"Set the volume to {level}%.", + "mute": "Muted the speakers.", + "unmute": "Unmuted the speakers.", + "set_brightness": f"Set the brightness to {level}%.", + "dark_mode": "Switched to dark mode.", + "light_mode": "Switched to light mode.", + "lock_screen": "Locked the screen.", + }[action] + return _os.ok("system_control", text) + + +__all__ = ["SystemControlTool"] diff --git a/src/locus/tools/desktop/window_control.py b/src/locus/tools/desktop/window_control.py new file mode 100644 index 0000000..d36404d --- /dev/null +++ b/src/locus/tools/desktop/window_control.py @@ -0,0 +1,265 @@ +"""List, focus, minimize, maximize and restore windows. + +Windows uses the window API through ctypes, macOS uses System Events (Locus +needs Accessibility permission), and Linux uses wmctrl, which works on X11 +but not Wayland. +""" + +from __future__ import annotations + +import json +from typing import Any, Callable, List, Tuple, Union + +from locus.core.registry import ToolRegistry +from locus.core.types import ToolResult +from locus.tools._stubs import BaseTool, ToolSpec +from locus.tools.desktop import _os + +ACTIONS = ("list", "focus", "minimize", "maximize", "restore") + +_PAST = { + "focus": "Focused", + "minimize": "Minimized", + "maximize": "Maximized", + "restore": "Restored", +} + +#: (handle, title): the handle is whatever the OS needs to act on the window. +Window = Tuple[Any, str] + +# ── Windows ────────────────────────────────────────────────────── + +_SW = {"minimize": 6, "maximize": 3, "restore": 9} +_GW_OWNER = 4 +_GWL_EXSTYLE = -20 +_WS_EX_TOOLWINDOW = 0x80 +_DWMWA_CLOAKED = 14 +_VK_MENU = 0x12 +_KEYEVENTF_KEYUP = 0x2 + + +def list_windows() -> List[Tuple[int, str]]: + """``(handle, title)`` for each window a user would see in the taskbar.""" + import ctypes + from ctypes import wintypes + + user32 = ctypes.windll.user32 # type: ignore[attr-defined] + dwmapi = ctypes.windll.dwmapi # type: ignore[attr-defined] + found: List[Tuple[int, str]] = [] + + @ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM) + def visit(hwnd, _lparam): + if not user32.IsWindowVisible(hwnd) or user32.GetWindow(hwnd, _GW_OWNER): + return True + if user32.GetWindowLongW(hwnd, _GWL_EXSTYLE) & _WS_EX_TOOLWINDOW: + return True + cloaked = wintypes.DWORD() + dwmapi.DwmGetWindowAttribute( + hwnd, _DWMWA_CLOAKED, ctypes.byref(cloaked), ctypes.sizeof(cloaked) + ) + if cloaked.value: + return True # suspended Store apps and other hidden windows + length = user32.GetWindowTextLengthW(hwnd) + if length: + title = ctypes.create_unicode_buffer(length + 1) + user32.GetWindowTextW(hwnd, title, length + 1) + if title.value and title.value != "Program Manager": + found.append((int(hwnd), title.value)) + return True + + user32.EnumWindows(visit, 0) + return found + + +def _apply(hwnd: int, action: str) -> bool: + import ctypes + + user32 = ctypes.windll.user32 # type: ignore[attr-defined] + if action == "focus": + if user32.IsIconic(hwnd): + user32.ShowWindow(hwnd, _SW["restore"]) + # Windows only lets the app that last had input change the foreground + # window; a released Alt key press counts as input. + user32.keybd_event(_VK_MENU, 0, 0, 0) + user32.keybd_event(_VK_MENU, 0, _KEYEVENTF_KEYUP, 0) + return bool(user32.SetForegroundWindow(hwnd)) + user32.ShowWindow(hwnd, _SW[action]) + return True + + +def _windows_act(hwnd: int, title: str, action: str) -> Union[None, str]: + if not _apply(hwnd, action): + return f"Windows didn't let Locus focus {title}." + return None + + +# ── macOS ──────────────────────────────────────────────────────── + +_MAC_LIST = """set out to "" +tell application "System Events" + repeat with p in (processes whose visible is true) + try + repeat with w in windows of p + set out to out & (name of p) & tab & (name of w) & linefeed + end repeat + end try + end repeat +end tell +return out""" + +_MAC_ACT = """on run argv + set appName to item 1 of argv + set winName to item 2 of argv + set act to item 3 of argv + tell application "System Events" + tell process appName + set w to (first window whose name is winName) + if act is "minimize" then + set value of attribute "AXMinimized" of w to true + else if act is "maximize" then + set value of attribute "AXFullScreen" of w to true + else + set value of attribute "AXMinimized" of w to false + set frontmost to true + perform action "AXRaise" of w + end if + end tell + end tell +end run""" + + +def _mac_windows() -> Union[List[Window], ToolResult]: + done = _os.run(["osascript", "-e", _MAC_LIST]) + if not done.ok: + return _os.fail( + "window_control", + "Couldn't list windows. Allow Locus under System Settings > Privacy" + f" & Security > Accessibility. ({done.error()})", + ) + windows: List[Window] = [] + for line in done.stdout.splitlines(): + app, _, title = line.partition("\t") + if title.strip(): + windows.append(((app, title), title)) + return windows + + +def _mac_act(handle: Tuple[str, str], title: str, action: str) -> Union[None, str]: + app, name = handle + done = _os.run(["osascript", "-e", _MAC_ACT, app, name, action]) + return None if done.ok else f"Couldn't change {title}: {done.error()}" + + +# ── Linux (X11) ────────────────────────────────────────────────── + +_WMCTRL_STATES = { + "minimize": "add,hidden", + "maximize": "add,maximized_vert,maximized_horz", + "restore": "remove,hidden,maximized_vert,maximized_horz", +} + + +def _linux_windows() -> Union[List[Window], ToolResult]: + if not _os.has_command("wmctrl"): + return _os.fail( + "window_control", "Install wmctrl to control windows (X11 only)." + ) + done = _os.run(["wmctrl", "-l"]) + if not done.ok: + return _os.fail("window_control", f"Couldn't list windows: {done.error()}") + windows: List[Window] = [] + for line in done.stdout.splitlines(): + parts = line.split(None, 3) # id, desktop, host, title + if len(parts) == 4 and parts[3].strip(): + windows.append((parts[0], parts[3])) + return windows + + +def _linux_act(window_id: str, title: str, action: str) -> Union[None, str]: + if action in _WMCTRL_STATES: + done = _os.run(["wmctrl", "-i", "-r", window_id, "-b", _WMCTRL_STATES[action]]) + if not done.ok: + return f"Couldn't change {title}: {done.error()}" + if action in ("focus", "restore"): + done = _os.run(["wmctrl", "-i", "-a", window_id]) + if not done.ok: + return f"Couldn't focus {title}: {done.error()}" + return None + + +# ── Tool ───────────────────────────────────────────────────────── + +# Looked up when called, so each OS's functions can be swapped out in tests. +_PLATFORMS: dict[str, Tuple[Callable[[], Any], Callable[[Any, str, str], Any]]] = { + "windows": (lambda: list_windows(), lambda *a: _windows_act(*a)), + "macos": (lambda: _mac_windows(), lambda *a: _mac_act(*a)), + "linux": (lambda: _linux_windows(), lambda *a: _linux_act(*a)), +} + + +@ToolRegistry.register("window_control") +class WindowControlTool(BaseTool): + """Arrange open windows. Nothing here closes a window or loses work.""" + + tool_id = "window_control" + + @property + def spec(self) -> ToolSpec: + return ToolSpec( + name="window_control", + description=( + "Work with open windows. 'list' shows window titles. 'focus'," + " 'minimize', 'maximize' and 'restore' act on the first window" + " whose title contains 'title' (not case-sensitive). To close" + " an app, use app_control instead." + ), + parameters={ + "type": "object", + "properties": { + "action": {"type": "string", "enum": list(ACTIONS)}, + "title": { + "type": "string", + "description": "Part of the window's title, like 'Notepad'.", + }, + }, + "required": ["action"], + }, + category="desktop", + ) + + def risk_for(self, arguments: dict) -> str: + return "read" + + def execute(self, **params: Any) -> ToolResult: + action = params.get("action") + if action not in ACTIONS: + return _os.bad_action("window_control", action, ACTIONS) + platform = _PLATFORMS.get(_os.system()) + if platform is None: + return _os.unsupported("window_control", "Controlling windows") + list_fn, act_fn = platform + + windows = list_fn() + if isinstance(windows, ToolResult): + return windows + if action == "list": + titles = [title for _, title in windows] + return _os.ok( + "window_control", json.dumps(titles, ensure_ascii=False), titles=titles + ) + wanted = str(params.get("title") or "").strip().lower() + if not wanted: + return _os.fail("window_control", "Give part of the window's title.") + match = next(((h, t) for h, t in windows if wanted in t.lower()), None) + if match is None: + return _os.fail( + "window_control", f"No open window has {wanted!r} in its title." + ) + handle, title = match + error = act_fn(handle, title, action) + if error: + return _os.fail("window_control", error) + return _os.ok("window_control", f"{_PAST[action]} {title}.") + + +__all__ = ["WindowControlTool", "list_windows"] diff --git a/src/locus/tools/task_plan.py b/src/locus/tools/task_plan.py new file mode 100644 index 0000000..53073e9 --- /dev/null +++ b/src/locus/tools/task_plan.py @@ -0,0 +1,93 @@ +"""Task plan tool — the agent's visible checklist for multi-step tasks. + +The chat shows the latest ``task_plan`` call as a checklist (from its +``tool_call_start`` event), so the user can follow the task while it runs. +""" + +from __future__ import annotations + +from typing import Any + +from locus.core.registry import ToolRegistry +from locus.core.types import ToolResult +from locus.tools._stubs import BaseTool, ToolSpec + +STATUSES = ("pending", "in_progress", "done", "skipped") +MAX_STEPS = 12 + + +@ToolRegistry.register("task_plan") +class TaskPlanTool(BaseTool): + """Show or update the plan for the current task.""" + + tool_id = "task_plan" + + @property + def spec(self) -> ToolSpec: + return ToolSpec( + name="task_plan", + description=( + "Show the user your plan for a task that takes more than one" + " step. Call it before starting, with every step 'pending'" + " except the first ('in_progress'), then again whenever a step" + " finishes, sending the whole list each time. Keep steps short" + " (a few words) and at most 12." + ), + parameters={ + "type": "object", + "properties": { + "steps": { + "type": "array", + "items": { + "type": "object", + "properties": { + "title": {"type": "string"}, + "status": {"type": "string", "enum": list(STATUSES)}, + }, + "required": ["title", "status"], + }, + }, + }, + "required": ["steps"], + }, + category="reasoning", + ) + + def risk_for(self, arguments: dict) -> str: + return "read" + + def execute(self, **params: Any) -> ToolResult: + steps = params.get("steps") + if not isinstance(steps, list) or not steps: + return ToolResult( + tool_name="task_plan", + content="Send at least one step, each with a title and status.", + success=False, + ) + clean = [] + for step in steps[:MAX_STEPS]: + if not isinstance(step, dict) or not str(step.get("title", "")).strip(): + continue + status = step.get("status") + clean.append( + { + "title": str(step["title"]).strip(), + "status": status if status in STATUSES else "pending", + } + ) + if not clean: + return ToolResult( + tool_name="task_plan", + content="Each step needs a title.", + success=False, + ) + done = sum(s["status"] in ("done", "skipped") for s in clean) + return ToolResult( + tool_name="task_plan", + content=f"Plan shown to the user ({done} of {len(clean)} steps done).", + success=True, + metadata={"steps": clean}, + ) + + +__all__ = ["TaskPlanTool", "STATUSES"] diff --git a/src/locus/tools/undo_journal.py b/src/locus/tools/undo_journal.py new file mode 100644 index 0000000..8b56c75 --- /dev/null +++ b/src/locus/tools/undo_journal.py @@ -0,0 +1,204 @@ +"""Undo for file changes made in Agent mode. + +Before :class:`UndoableFileWriteTool` writes a file, it saves the old contents +(or notes that the file is new) in a journal under ``~/.locus/undo``. Undoing +puts the old contents back, or deletes a file the agent created, but only if +the file still holds what the agent wrote, so later edits are never lost. +""" + +from __future__ import annotations + +import difflib +import hashlib +import json +import threading +import time +import uuid +from dataclasses import asdict, dataclass +from pathlib import Path +from typing import Any, List, Optional, Tuple + +from locus.core.types import ToolResult +from locus.tools.file_write import FileWriteTool + +#: Files bigger than this aren't backed up, so their changes can't be undone. +MAX_BACKUP_BYTES = 10 * 1024 * 1024 +#: Older entries are dropped (with their backups) past this many. +MAX_ENTRIES = 100 + + +def _digest(data: bytes) -> str: + return hashlib.sha256(data).hexdigest() + + +@dataclass +class UndoEntry: + id: str + path: str + created: bool # the file didn't exist before the change + written_sha256: str + timestamp: float + + +class UndoJournal: + """Saved file contents from before each change, newest last.""" + + def __init__(self, root: Optional[Path] = None) -> None: + if root is None: + from locus.core.paths import get_config_dir + + root = Path(get_config_dir()) / "undo" + self.root = Path(root) + self._lock = threading.Lock() + + @property + def _index(self) -> Path: + return self.root / "index.json" + + def _load(self) -> List[UndoEntry]: + try: + rows = json.loads(self._index.read_text(encoding="utf-8")) + except (OSError, ValueError): + return [] + return [UndoEntry(**row) for row in rows if isinstance(row, dict)] + + def _save(self, entries: List[UndoEntry]) -> None: + self.root.mkdir(parents=True, exist_ok=True) + tmp = self._index.with_suffix(".tmp") + tmp.write_text(json.dumps([asdict(e) for e in entries]), encoding="utf-8") + tmp.replace(self._index) + + def _backup(self, entry_id: str) -> Path: + return self.root / f"{entry_id}.bak" + + def record(self, path: Path, previous: Optional[bytes], written: bytes) -> str: + """Note a change to *path*; *previous* is ``None`` for a new file.""" + entry = UndoEntry( + id=uuid.uuid4().hex, + path=str(path), + created=previous is None, + written_sha256=_digest(written), + timestamp=time.time(), + ) + with self._lock: + self.root.mkdir(parents=True, exist_ok=True) + if previous is not None: + self._backup(entry.id).write_bytes(previous) + entries = self._load() + [entry] + for old in entries[:-MAX_ENTRIES]: + self._backup(old.id).unlink(missing_ok=True) + self._save(entries[-MAX_ENTRIES:]) + return entry.id + + def undo(self, entry_id: str) -> Tuple[bool, str]: + """Undo one change. Returns ``(done, message)``.""" + with self._lock: + entries = self._load() + entry = next((e for e in entries if e.id == entry_id), None) + if entry is None: + return False, "That change can't be undone any more." + path = Path(entry.path) + try: + current = path.read_bytes() if path.exists() else None + except OSError as exc: + return False, f"Couldn't read {path}: {exc}" + if current is None or _digest(current) != entry.written_sha256: + return False, f"{path} has changed since, so it wasn't undone." + try: + if entry.created: + path.unlink() + message = f"Deleted {path}, which the agent created." + else: + path.write_bytes(self._backup(entry.id).read_bytes()) + message = f"Put back the earlier version of {path}." + except OSError as exc: + return False, f"Couldn't undo the change to {path}: {exc}" + self._backup(entry.id).unlink(missing_ok=True) + self._save([e for e in entries if e.id != entry_id]) + return True, message + + +_journal: Optional[UndoJournal] = None +_journal_lock = threading.Lock() + + +def get_journal() -> UndoJournal: + global _journal + with _journal_lock: + if _journal is None: + _journal = UndoJournal() + return _journal + + +class UndoableFileWriteTool(FileWriteTool): + """``file_write`` that records each change so the user can undo it.""" + + def __init__(self, *args: Any, journal: Optional[UndoJournal] = None, **kwargs): + super().__init__(*args, **kwargs) + self._journal = journal + + def _target(self, raw: Any) -> Optional[Path]: + if not raw: + return None + path = Path(str(raw)) + if not path.is_absolute() and self._allowed_dirs: + path = self._allowed_dirs[0] / path + return path + + def preview_for(self, arguments: dict) -> Optional[str]: + """A diff of the change, shown in the approval before it's written.""" + path = self._target(arguments.get("path")) + content = arguments.get("content") + if path is None or not isinstance(content, str): + return None + old = "" + if path.is_file(): + try: + if path.stat().st_size > MAX_BACKUP_BYTES: + return None + old = path.read_text(encoding="utf-8") + except (OSError, UnicodeDecodeError): + return None + new = old + content if arguments.get("mode") == "append" else content + if new == old: + return f"No change to {path}." + diff = difflib.unified_diff( + old.splitlines(keepends=True), + new.splitlines(keepends=True), + fromfile=str(path) if path.exists() else "/dev/null", + tofile=str(path), + ) + return "".join(diff) + + def execute(self, **params: Any) -> ToolResult: + path = self._target(params.get("path")) + previous: Optional[bytes] = None + can_undo = path is not None + if path is not None and path.is_file(): + try: + if path.stat().st_size <= MAX_BACKUP_BYTES: + previous = path.read_bytes() + else: + can_undo = False + except OSError: + can_undo = False + + result = super().execute(**params) + if not (result.success and can_undo and path is not None and path.is_file()): + return result + try: + journal = self._journal or get_journal() + entry_id = journal.record(path, previous, path.read_bytes()) + except OSError: + return result + result.metadata = {**(result.metadata or {}), "undo_id": entry_id} + return result + + +__all__ = [ + "MAX_BACKUP_BYTES", + "UndoEntry", + "UndoJournal", + "UndoableFileWriteTool", + "get_journal", +] diff --git a/tests/server/conftest.py b/tests/server/conftest.py index 4bcccc9..f147b6e 100644 --- a/tests/server/conftest.py +++ b/tests/server/conftest.py @@ -15,6 +15,18 @@ import pytest +@pytest.fixture(autouse=True) +def _isolate_agent_permissions(tmp_path, monkeypatch): + """Keep Agent mode's "always allow" rules out of the real ``~/.locus``.""" + from locus.server import approvals + + monkeypatch.setattr( + approvals, + "_rules", + approvals.PermissionRules(tmp_path / "agent_permissions.json"), + ) + + @pytest.fixture(autouse=True) def _isolate_traces_db(tmp_path, monkeypatch): """Point ``config.traces.db_path`` at a temp file for every server test. diff --git a/tests/server/test_agent_approvals.py b/tests/server/test_agent_approvals.py index 7ccdf3b..8d00bc6 100644 --- a/tests/server/test_agent_approvals.py +++ b/tests/server/test_agent_approvals.py @@ -317,3 +317,76 @@ def test_non_streaming_agent_mode_denies_changes(monkeypatch): assert resp.status_code == 200 assert agent.results == [True, False] + + +# ── Lasting rules ──────────────────────────────────────────────── + + +def test_rule_keys_cover_one_action(): + from locus.server.approvals import rule_key + + assert rule_key("file_write", {"path": "a"}) == "file_write" + assert ( + rule_key("system_control", {"action": "set_volume"}) + == "system_control:set_volume" + ) + + +def test_always_saves_a_rule_that_later_runs_use(): + emit = Recorder(answer="always") + assert ApprovalSession(emit).check("system_control", {"action": "set_volume"}) + + later = Recorder(answer="deny") + session = ApprovalSession(later) + # The same action no longer asks, in a new run. + assert session.check("system_control", {"action": "set_volume", "level": 10}) + assert later.events == [] + # Other actions of the tool still ask. + assert session.check("system_control", {"action": "lock_screen"}) is False + assert later.names().count("approval_required") == 1 + required = emit.events[0][1] + assert required["can_always"] is True + assert required["rule"] == "system_control:set_volume" + + +def test_run_level_calls_never_get_lasting_rules(): + emit = Recorder(answer="always") + assert ApprovalSession(emit).check("shell_exec", {"command": "ls"}) + assert emit.events[0][1]["can_always"] is False + + later = Recorder(answer="deny") + assert ApprovalSession(later).check("shell_exec", {"command": "ls"}) is False + assert approvals.get_rules().list() == [] + + +def test_rules_can_be_listed_and_removed(monkeypatch): + client = TestClient(_app(monkeypatch, AskingAgent([]))) + approvals.get_rules().add("file_write", {"path": "a"}) + + rules = client.get("/v1/chat/permissions").json()["rules"] + assert [r["key"] for r in rules] == ["file_write"] + assert client.delete("/v1/chat/permissions/file_write").status_code == 200 + assert client.get("/v1/chat/permissions").json()["rules"] == [] + assert client.delete("/v1/chat/permissions/file_write").status_code == 404 + + +def test_rules_survive_a_restart(tmp_path): + from locus.server.approvals import PermissionRules + + path = tmp_path / "rules.json" + PermissionRules(path).add("clipboard", {"action": "write"}) + assert PermissionRules(path).allows("clipboard", {"action": "write"}) + assert not PermissionRules(path).allows("clipboard", {"action": "read"}) + + +def test_previews_come_from_the_tool(): + class Previewing: + def preview_for(self, arguments): + return "x" * (approvals.MAX_PREVIEW_CHARS + 10) + + emit = Recorder(answer="deny") + ApprovalSession(emit, tools={"file_write": Previewing()}).check("file_write", {}) + + preview = emit.events[0][1]["preview"] + assert preview.startswith("x" * approvals.MAX_PREVIEW_CHARS) + assert preview.endswith("(preview cut off)") diff --git a/tests/server/test_agent_mode.py b/tests/server/test_agent_mode.py index ae6989f..c5df629 100644 --- a/tests/server/test_agent_mode.py +++ b/tests/server/test_agent_mode.py @@ -55,9 +55,11 @@ def __init__(self, bus=None, tools=True): self._tools = [object()] if tools else [] self._model = "test-model" self.inputs: list[str] = [] + self.contexts: list = [] def run(self, input, context=None): self.inputs.append(input) + self.contexts.append(context) if self._bus is not None: self._bus.publish( EventType.TOOL_CALL_START, @@ -183,22 +185,78 @@ def test_agent_mode_streams_only_its_own_tool_events(monkeypatch): ] -def test_agent_mode_with_web_search_answers_without_the_agent(monkeypatch): +def test_agent_mode_gets_web_results_as_context(monkeypatch): from locus.server import web_context seen: list = [] agent = FakeAgent() + monkeypatch.setattr(task_agent, "_build_task_agent", lambda state: agent) - async def no_results(query): - return web_context.WebSearchResult(query=query, sources=[], error="offline") + async def results(query): + return web_context.WebSearchResult( + query=query, + sources=[ + web_context.WebSource( + ref=1, title="Docs", url="https://example.com", text="Answer 42" + ) + ], + ) + + monkeypatch.setattr(web_context, "search_web", results) + app = create_app(_engine(seen), "test-model", config=_config()) + + resp = _post(TestClient(app), mode="agent", web_search=True) + + assert agent.inputs == ["read a.txt"] + assert seen == [] + system = [ + m for m in agent.contexts[0].conversation.messages if m.role.value == "system" + ] + assert any("Answer 42" in m.content for m in system) + assert any(name == "web_search" for name, _ in _events(resp)) - monkeypatch.setattr(web_context, "search_web", no_results) - app = create_app(_engine(seen), "test-model", agent=agent, config=_config()) - _post(TestClient(app), mode="agent", web_search=True) +def test_agent_mode_gets_attached_documents_and_images(monkeypatch): + agent = FakeAgent() + monkeypatch.setattr(task_agent, "_build_task_agent", lambda state: agent) + app = create_app(_engine([]), "test-model", config=_config()) + monkeypatch.setattr( + "locus.server.routes._model_accepts_images", + lambda engine, model: _true(), + ) - assert agent.inputs == [] - assert seen + TestClient(app).post( + "/v1/chat/completions", + json={ + "model": "test-model", + "stream": True, + "mode": "agent", + "messages": [ + { + "role": "user", + "content": "earlier", + "attachments": [{"name": "old.txt", "text": "OLD NOTES"}], + }, + {"role": "assistant", "content": "ok"}, + { + "role": "user", + "content": "summarize", + "attachments": [{"name": "plan.md", "text": "THE PLAN"}], + "images": ["aW1n"], + }, + ], + }, + ) + + assert "THE PLAN" in agent.inputs[0] + assert agent.inputs[0].endswith("summarize") + context = agent.contexts[0] + assert "OLD NOTES" in context.conversation.messages[0].content + assert context.metadata["input_images"] == ["aW1n"] + + +async def _true(): + return True def test_agent_mode_falls_back_to_chat_when_the_agent_cannot_start(monkeypatch): @@ -266,3 +324,19 @@ def test_built_agent_asks_before_changes_and_stays_in_home(monkeypatch): 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) + + +def test_agents_send_input_images_with_the_last_message(): + from locus.agents._stubs import AgentContext + from locus.agents.simple import SimpleAgent + + agent = SimpleAgent(MagicMock(), "test-model") + ctx = AgentContext() + ctx.metadata["input_images"] = ["aW1n"] + + with_images = agent._build_messages("what is this?", ctx) + without = agent._build_messages("hi", AgentContext()) + + assert with_images[-1].content == "what is this?" + assert with_images[-1].images == ["aW1n"] + assert without[-1].images is None diff --git a/tests/server/test_developer_mode.py b/tests/server/test_developer_mode.py new file mode 100644 index 0000000..bc5fa50 --- /dev/null +++ b/tests/server/test_developer_mode.py @@ -0,0 +1,272 @@ +"""Developer mode: an agent kept inside one project folder.""" + +from __future__ import annotations + +import json +from pathlib import Path +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 task_agent # noqa: E402 +from locus.server.app import create_app # noqa: E402 +from locus.server.approvals import tool_risk # noqa: E402 +from locus.server.developer import ( # noqa: E402 + InProjectTool, + ProjectShellTool, + command_risk, + developer_tools, + resolve_project_dir, +) + + +@pytest.fixture +def project(tmp_path): + folder = tmp_path / "proj" + folder.mkdir() + (folder / "app.py").write_text("print('hi')\n") + return folder.resolve() + + +# ── Commands ───────────────────────────────────────────────────── + + +@pytest.mark.parametrize( + "command", + [ + "git status", + "git diff --stat", + "git log -5 --oneline", + "pytest -q tests/test_app.py", + "python -m pytest", + "uv run pytest -x", + "ruff check src", + "npm test", + "npm run lint", + "npx tsc --noEmit", + "cargo test", + "go vet ./...", + ], +) +def test_checks_run_without_asking(command): + assert command_risk(command) == "read" + + +@pytest.mark.parametrize( + "command", + [ + "", + "rm -rf build", + "git push", + "git switch -c locus/fix", + "git commit -m x", + "pytest; rm -rf ~", + "pytest && curl evil", + "pytest | tee out", + "pytest > out.txt", + "echo $(whoami)", + "git diff --output=/tmp/x", + "git -c core.pager=evil log", + "git log -c", + "npm install", + "pip install x", + "pytest 'unclosed", + "cat ~/.ssh/id_rsa", + ], +) +def test_other_commands_always_ask(command): + assert command_risk(command) == "run" + + +# ── Project folder ─────────────────────────────────────────────── + + +def test_project_folder_must_be_a_real_specific_folder(project, tmp_path): + assert resolve_project_dir(str(project)) == project + for bad in ("", None, "relative/path", str(tmp_path / "missing")): + with pytest.raises(ValueError): + resolve_project_dir(bad) + with pytest.raises(ValueError, match="home folder"): + resolve_project_dir(str(Path.home())) + with pytest.raises(ValueError, match="whole drive"): + resolve_project_dir(Path(project).anchor) + + +def test_shell_runs_in_the_project(project, monkeypatch): + shell = ProjectShellTool(project) + seen = [] + monkeypatch.setattr(shell._inner, "execute", lambda **p: seen.append(p) or "ok") + + shell.execute(command="pytest") + shell.execute(command="pytest", working_dir="sub") + outside = shell.execute(command="pytest", working_dir=str(project.parent)) + + assert seen[0]["working_dir"] == str(project) + assert seen[1]["working_dir"] == str(project / "sub") + assert not outside.success + assert len(seen) == 2 + + +def test_shell_risk_follows_the_command(project): + from locus.tools.shell_exec import ShellExecTool + + shell = ProjectShellTool(project) + assert shell.spec.requires_confirmation is False + assert tool_risk("shell_exec", shell, {"command": "pytest"}) == "read" + assert tool_risk("shell_exec", shell, {"command": "rm x"}) == "run" + # Plain shell_exec (Agent mode) still always asks. + assert tool_risk("shell_exec", ShellExecTool(), {"command": "pytest"}) == "run" + + +def test_git_tools_default_to_and_stay_in_the_project(project): + class Recorder: + spec = SimpleNamespace(name="git_status", requires_confirmation=False) + tool_id = "git_status" + + def __init__(self): + self.calls = [] + + def execute(self, **params): + self.calls.append(params) + return "ok" + + inner = Recorder() + tool = InProjectTool(inner, project, "repo_path") + + tool.execute() + tool.execute(repo_path="sub") + refused = tool.execute(repo_path=str(project.parent)) + + assert [c["repo_path"] for c in inner.calls] == [str(project), str(project / "sub")] + assert not refused.success + + +def test_developer_tools_are_kept_in_the_project(project): + tools = {t.spec.name: t for t in developer_tools(project)} + + assert { + "task_plan", + "file_read", + "file_write", + "shell_exec", + "git_status", + "git_commit", + } <= set(tools) + assert not set(tools) & {"web_search", "http_request", "clipboard"} + for name in ("file_read", "file_write"): + assert tools[name]._allowed_dirs == [project] + # Commits always ask: git_commit requires confirmation. + assert tool_risk("git_commit", tools["git_commit"], {"message": "m"}) == "run" + + +def test_file_changes_show_a_diff_first(project): + write = {t.spec.name: t for t in developer_tools(project)}["file_write"] + + diff = write.preview_for({"path": "app.py", "content": "print('bye')\n"}) + new = write.preview_for({"path": "new.py", "content": "x = 1\n"}) + + assert "-print('hi')" in diff and "+print('bye')" in diff + assert "/dev/null" in new and "+x = 1" in new + assert write.preview_for({"path": "app.py", "content": "print('hi')\n"}).startswith( + "No change" + ) + + +# ── Through the chat ───────────────────────────────────────────── + + +class FakeAgent: + agent_id = "developer" + + def __init__(self): + self._tools = [object()] + self._model = "m" + self.inputs = [] + + def run(self, input, context=None): + self.inputs.append(input) + return AgentResult(content="Done.") + + +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 + + +def _post(client, **extra): + return client.post( + "/v1/chat/completions", + json={ + "model": "m", + "messages": [{"role": "user", "content": "fix the test"}], + "stream": True, + "mode": "developer", + **extra, + }, + ) + + +def test_developer_mode_uses_one_agent_per_project(project, tmp_path, monkeypatch): + built = [] + + def build(state, folder): + built.append(folder) + return FakeAgent() + + monkeypatch.setattr(task_agent, "_build_developer_agent", build) + other = tmp_path / "other" + other.mkdir() + client = TestClient(create_app(object(), "m", config=_config())) + + _post(client, project_dir=str(project)) + _post(client, project_dir=str(project)) + _post(client, project_dir=str(other)) + + assert built == [project, other.resolve()] + + +def test_developer_mode_needs_a_usable_folder(monkeypatch): + client = TestClient(create_app(object(), "m", config=_config())) + + missing = _post(client) + home = _post(client, project_dir=str(Path.home())) + + assert missing.status_code == 400 + assert "project folder" in missing.json()["detail"] + assert home.status_code == 400 + + +def test_built_developer_agent(project): + from locus.agents.orchestrator import OrchestratorAgent + from locus.core.events import EventBus + from locus.core.registry import AgentRegistry + from locus.server.approvals import before_tool_call + + AgentRegistry.register_value("orchestrator", OrchestratorAgent) + engine = SimpleNamespace(engine_id="mock") + state = SimpleNamespace( + engine=engine, + model="m", + config=_config(), + bus=EventBus(), + capability_policy=None, + rate_limiter=None, + ) + + agent = task_agent.get_developer_agent(state, str(project)) + + assert agent._before_tool_call is before_tool_call + assert str(project) in agent._system_prompt + assert task_agent.get_developer_agent(state, str(project)) is agent + assert json.dumps(sorted(t.spec.name for t in agent._tools)) diff --git a/tests/tools/test_desktop_tools.py b/tests/tools/test_desktop_tools.py new file mode 100644 index 0000000..8a3bec1 --- /dev/null +++ b/tests/tools/test_desktop_tools.py @@ -0,0 +1,559 @@ +"""Desktop control tools, with the OS layer faked so nothing touches the desktop.""" + +from __future__ import annotations + +import json +from pathlib import Path + +import pytest + +from locus.server.approvals import tool_risk +from locus.tools.desktop import ( + AppControlTool, + ClipboardTool, + NotifyTool, + OpenPathTool, + ScreenshotTool, + SystemControlTool, + WindowControlTool, + _os, + app_control, + notify, + open_path, + window_control, +) + + +@pytest.fixture(autouse=True) +def _isolate_reminders(tmp_path, monkeypatch): + """Keep reminders out of the real ``~/.locus`` and drop leftover timers.""" + monkeypatch.setattr(notify, "_store", notify.ReminderStore(tmp_path / "rem.json")) + monkeypatch.setattr(notify, "_timers", {}) + + +class FakeOS: + """Records commands instead of running them.""" + + def __init__(self, monkeypatch, system="windows", stdout="", returncode=0): + self.calls: list[dict] = [] + self.stdout = stdout + self.returncode = returncode + self.on_call = None + monkeypatch.setattr(_os, "system", lambda: system) + monkeypatch.setattr(_os, "run", self._run) + monkeypatch.setattr(_os, "powershell", self._powershell) + monkeypatch.setattr(_os, "has_command", lambda name: True) + + def _done(self, call): + self.calls.append(call) + if self.on_call: + self.on_call(call) + return _os.Completed( + self.returncode, self.stdout, "boom" if self.returncode else "" + ) + + def _run(self, args, *, env=None, input=None, timeout=0): + return self._done({"args": args, "input": input}) + + def _powershell(self, script, *, args=None, input=None, timeout=0): + return self._done({"script": script, "args": args or {}, "input": input}) + + +# ── Risk levels ────────────────────────────────────────────────── + + +@pytest.mark.parametrize( + "tool, arguments, risk", + [ + (OpenPathTool(), {"path": "C:/docs/report.pdf"}, "read"), + (OpenPathTool(), {"path": "C:/downloads/setup.EXE"}, "run"), + (OpenPathTool(), {"path": "C:/x/run.ps1"}, "run"), + (OpenPathTool(), {"path": "https://example.com"}, "change"), + (AppControlTool(), {"action": "list"}, "read"), + (AppControlTool(), {"action": "open", "name": "notepad"}, "change"), + (AppControlTool(), {"action": "close", "name": "notepad"}, "change"), + (WindowControlTool(), {"action": "minimize", "title": "x"}, "read"), + (SystemControlTool(), {"action": "get_volume"}, "read"), + (SystemControlTool(), {"action": "set_volume", "level": 20}, "change"), + (SystemControlTool(), {"action": "lock_screen"}, "change"), + (ClipboardTool(), {"action": "read"}, "change"), + (ClipboardTool(), {"action": "write", "text": "x"}, "change"), + (NotifyTool(), {"message": "hi"}, "read"), + (ScreenshotTool(), {}, "change"), + ], +) +def test_risk_depends_on_the_call(tool, arguments, risk): + assert tool_risk(tool.spec.name, tool, arguments) == risk + + +def test_a_broken_risk_for_asks(): + class Broken: + def risk_for(self, arguments): + raise RuntimeError + + class Odd: + def risk_for(self, arguments): + return "harmless" + + assert tool_risk("x", Broken(), {}) == "change" + assert tool_risk("x", Odd(), {}) == "change" + + +# ── open_path ──────────────────────────────────────────────────── + + +def test_open_path_opens_existing_files_on_windows(monkeypatch, tmp_path): + FakeOS(monkeypatch, "windows") + opened = [] + monkeypatch.setattr(open_path.os, "startfile", opened.append, raising=False) + target = tmp_path / "notes.txt" + target.write_text("x") + + result = OpenPathTool().execute(path=str(target)) + + assert result.success + assert opened == [str(target.resolve())] + + +def test_open_path_uses_xdg_open_on_linux(monkeypatch, tmp_path): + fake = FakeOS(monkeypatch, "linux") + assert OpenPathTool().execute(path=str(tmp_path)).success + assert fake.calls[0]["args"] == ["xdg-open", str(tmp_path.resolve())] + + +@pytest.mark.parametrize( + "path, message", + [ + ("", "Give a file"), + ("~/definitely-missing-locus-file.txt", "doesn't exist"), + ("ms-settings:display", "Only http and https"), + ("file:///C:/x.txt", "Only http and https"), + ], +) +def test_open_path_refuses(monkeypatch, path, message): + FakeOS(monkeypatch, "macos") + result = OpenPathTool().execute(path=path) + assert not result.success + assert message in result.content + + +def test_open_path_opens_links_without_checking_the_disk(monkeypatch): + fake = FakeOS(monkeypatch, "macos") + assert OpenPathTool().execute(path="https://example.com/a").success + assert fake.calls[0]["args"] == ["open", "https://example.com/a"] + + +# ── app_control ────────────────────────────────────────────────── + + +@pytest.mark.parametrize( + "stdout", + [ + json.dumps({"ProcessName": "notepad", "Id": 1, "MainWindowTitle": "a.txt"}), + json.dumps([{"ProcessName": "notepad", "Id": 1, "MainWindowTitle": "a.txt"}]), + ], +) +def test_app_list_on_windows(monkeypatch, stdout): + FakeOS(monkeypatch, "windows", stdout=stdout) + result = AppControlTool().execute(action="list") + assert result.metadata["apps"] == [{"name": "notepad", "window": "a.txt"}] + + +def test_app_open_on_windows_uses_the_shell(monkeypatch): + FakeOS(monkeypatch, "windows") + opened = [] + monkeypatch.setattr(app_control.os, "startfile", opened.append, raising=False) + assert AppControlTool().execute(action="open", name="notepad.exe").success + assert opened == ["notepad"] + + +@pytest.mark.parametrize( + "name", ["", "C:\\Windows\\cmd.exe", "../evil", "a;b", "ms-settings:", "x" * 80] +) +def test_app_names_must_be_plain(monkeypatch, name): + fake = FakeOS(monkeypatch, "windows") + result = AppControlTool().execute(action="open", name=name) + assert not result.success + assert fake.calls == [] + + +def test_app_close_passes_the_name_outside_the_script(monkeypatch): + fake = FakeOS(monkeypatch, "windows", stdout="1") + assert AppControlTool().execute(action="close", name="notepad").success + call = fake.calls[0] + assert call["args"] == {"name": "notepad"} + assert "notepad" not in call["script"] + assert "CloseMainWindow" in call["script"] + + +def test_app_close_on_macos_quits_by_name(monkeypatch): + fake = FakeOS(monkeypatch, "macos") + assert AppControlTool().execute(action="close", name="Safari").success + assert fake.calls[0]["args"][0] == "osascript" + assert fake.calls[0]["args"][-1] == "Safari" + + +def test_app_errors_are_reported(monkeypatch): + FakeOS(monkeypatch, "windows", returncode=1) + result = AppControlTool().execute(action="close", name="notepad") + assert not result.success + assert "boom" in result.content + + +# ── window_control ─────────────────────────────────────────────── + + +def test_windows_are_matched_by_part_of_the_title(monkeypatch): + FakeOS(monkeypatch, "windows") + applied = [] + monkeypatch.setattr( + window_control, + "list_windows", + lambda: [(1, "Inbox - Outlook"), (2, "notes.txt - Notepad")], + ) + monkeypatch.setattr( + window_control, + "_apply", + lambda hwnd, action: applied.append((hwnd, action)) or True, + ) + + result = WindowControlTool().execute(action="minimize", title="notepad") + + assert result.success + assert result.content == "Minimized notes.txt - Notepad." + assert applied == [(2, "minimize")] + listed = WindowControlTool().execute(action="list") + assert listed.metadata["titles"] == ["Inbox - Outlook", "notes.txt - Notepad"] + assert not WindowControlTool().execute(action="focus", title="excel").success + + +def test_window_control_on_macos_uses_system_events(monkeypatch): + fake = FakeOS(monkeypatch, "macos", stdout="Safari\tApple\nNotes\tShopping list\n") + + listed = WindowControlTool().execute(action="list") + result = WindowControlTool().execute(action="minimize", title="shopping") + + assert listed.metadata["titles"] == ["Apple", "Shopping list"] + assert result.content == "Minimized Shopping list." + args = fake.calls[-1]["args"] + assert args[0] == "osascript" + assert args[-3:] == ["Notes", "Shopping list", "minimize"] + + +def test_window_control_on_macos_explains_accessibility(monkeypatch): + FakeOS(monkeypatch, "macos", returncode=1) + result = WindowControlTool().execute(action="list") + assert "Accessibility" in result.content + + +def test_window_control_on_linux_uses_wmctrl(monkeypatch): + fake = FakeOS( + monkeypatch, + "linux", + stdout="0x01 0 host Terminal\n0x02 0 host notes.txt - gedit\n", + ) + + result = WindowControlTool().execute(action="restore", title="GEDIT") + + assert result.content == "Restored notes.txt - gedit." + calls = [c["args"] for c in fake.calls[1:]] + assert calls == [ + [ + "wmctrl", + "-i", + "-r", + "0x02", + "-b", + "remove,hidden,maximized_vert,maximized_horz", + ], + ["wmctrl", "-i", "-a", "0x02"], + ] + + +def test_window_control_on_linux_needs_wmctrl(monkeypatch): + FakeOS(monkeypatch, "linux") + monkeypatch.setattr(_os, "has_command", lambda name: False) + assert "wmctrl" in WindowControlTool().execute(action="list").content + + +def test_window_control_on_other_systems(monkeypatch): + FakeOS(monkeypatch, "freebsd") + result = WindowControlTool().execute(action="list") + assert "isn't supported on freebsd" in result.content + + +# ── system_control ─────────────────────────────────────────────── + + +def test_volume_level_goes_in_as_an_argument(monkeypatch): + fake = FakeOS(monkeypatch, "windows") + assert SystemControlTool().execute(action="set_volume", level=35).success + call = fake.calls[0] + assert call["args"] == {"level": 35} + assert "$env:LOCUS_ARG_LEVEL" in call["script"] + + +def test_reading_the_volume_on_windows(monkeypatch): + FakeOS(monkeypatch, "windows", stdout="42 True\n") + result = SystemControlTool().execute(action="get_volume") + assert result.content == "Volume is 42% and muted." + assert result.metadata == {"volume": 42, "muted": True} + + +@pytest.mark.parametrize("level", [None, -1, 101, "loud"]) +def test_levels_must_be_0_to_100(monkeypatch, level): + fake = FakeOS(monkeypatch, "windows") + result = SystemControlTool().execute(action="set_volume", level=level) + assert not result.success + assert fake.calls == [] + + +def test_brightness_failure_explains_why(monkeypatch): + FakeOS(monkeypatch, "windows", returncode=1) + result = SystemControlTool().execute(action="set_brightness", level=50) + assert "built-in laptop screens" in result.content + + +def test_macos_volume_and_lock(monkeypatch): + fake = FakeOS(monkeypatch, "macos") + assert SystemControlTool().execute(action="set_volume", level=20).success + assert "set volume output volume 20" in fake.calls[0]["args"][-1] + assert SystemControlTool().execute(action="lock_screen").success + assert fake.calls[1]["args"] == ["pmset", "displaysleepnow"] + assert not SystemControlTool().execute(action="set_brightness", level=5).success + + +def test_linux_volume_uses_pactl(monkeypatch): + fake = FakeOS(monkeypatch, "linux", stdout="Volume: front-left: 1 / 55% / -15 dB") + result = SystemControlTool().execute(action="get_volume") + assert result.metadata["volume"] == 55 + SystemControlTool().execute(action="mute") + assert fake.calls[-1]["args"] == ["pactl", "set-sink-mute", "@DEFAULT_SINK@", "1"] + + +# ── clipboard ──────────────────────────────────────────────────── + + +def test_clipboard_text_goes_through_stdin(monkeypatch): + fake = FakeOS(monkeypatch, "windows") + assert ClipboardTool().execute(action="write", text="'; Remove-Item x").success + call = fake.calls[0] + assert call["input"] == "'; Remove-Item x" + assert "Remove-Item" not in call["script"] + + +def test_long_clipboard_text_is_cut(monkeypatch): + from locus.tools.desktop.clipboard import MAX_READ_CHARS + + FakeOS(monkeypatch, "macos", stdout="x" * (MAX_READ_CHARS + 5)) + result = ClipboardTool().execute(action="read") + assert result.content.startswith("x" * MAX_READ_CHARS) + assert "cut off" in result.content + + +def test_empty_clipboard(monkeypatch): + FakeOS(monkeypatch, "windows", stdout="\r\n") + assert ( + ClipboardTool().execute(action="read").content == "The clipboard has no text." + ) + + +def test_linux_clipboard_needs_a_helper(monkeypatch): + FakeOS(monkeypatch, "linux") + monkeypatch.setattr(_os, "has_command", lambda name: False) + result = ClipboardTool().execute(action="read") + assert "wl-clipboard or xclip" in result.content + + +# ── notify ─────────────────────────────────────────────────────── + + +def test_notification_now_passes_text_as_arguments(monkeypatch): + fake = FakeOS(monkeypatch, "windows") + assert NotifyTool().execute(title="Tea", message="It's ready").success + call = fake.calls[0] + assert call["args"] == {"title": "Tea", "message": "It's ready"} + assert "It's ready" not in call["script"] + + +def test_reminders_wait(monkeypatch): + FakeOS(monkeypatch, "linux") + started = [] + + class FakeTimer: + def __init__(self, seconds, function, args): + self.seconds, self.function, self.args = seconds, function, args + self.daemon = False + + def start(self): + started.append(self) + + def cancel(self): + started.remove(self) + + monkeypatch.setattr(notify.threading, "Timer", FakeTimer) + + result = NotifyTool().execute(message="Stand up", delay_minutes=2.5) + + assert result.success + assert "2.5 minutes from now" in result.content + assert started[0].seconds == pytest.approx(150, abs=2) + assert started[0].daemon is True + saved = notify.get_store().all() + assert [r["message"] for r in saved] == ["Stand up"] + + listed = NotifyTool().execute(action="list_reminders") + assert "Stand up" in listed.content + reminder_id = saved[0]["id"] + assert NotifyTool().execute(action="cancel_reminder", id=reminder_id).success + assert notify.get_store().all() == [] + assert started == [] + assert not NotifyTool().execute(action="cancel_reminder", id=reminder_id).success + + +def test_reminders_are_restored_after_a_restart(monkeypatch): + import time as _time + + fake = FakeOS(monkeypatch, "linux") + store = notify.get_store() + future = store.add("Call", "Ring the bank", _time.time() + 3600) + store.add("Meds", "Take them", _time.time() - 60) + scheduled = [] + monkeypatch.setattr(notify, "_schedule", scheduled.append) + + class Inline: + def __init__(self, target, args, daemon): + self.target, self.args = target, args + + def start(self): + self.target(*self.args) + + monkeypatch.setattr(notify.threading, "Thread", Inline) + + assert notify.restore_reminders() == 2 + + assert [e["id"] for e in scheduled] == [future["id"]] + # The one that came due while Locus was closed shows now and is done. + assert fake.calls[0]["args"] == [ + "notify-send", + "Meds (missed while Locus was closed)", + "Take them", + ] + assert [r["id"] for r in store.all()] == [future["id"]] + + +@pytest.mark.parametrize("delay", [-1, 50000, "soon"]) +def test_reminder_delays_are_checked(monkeypatch, delay): + FakeOS(monkeypatch, "linux") + assert not NotifyTool().execute(message="x", delay_minutes=delay).success + + +def test_notifications_need_text(monkeypatch): + FakeOS(monkeypatch, "linux") + assert not NotifyTool().execute(message=" ").success + + +# ── screenshot ─────────────────────────────────────────────────── + + +def test_screenshot_is_saved_in_the_locus_folder(monkeypatch, tmp_path): + monkeypatch.setenv("LOCUS_HOME", str(tmp_path)) + fake = FakeOS(monkeypatch, "windows") + fake.on_call = lambda call: Path(call["args"]["path"]).write_bytes(b"png") + + result = ScreenshotTool().execute() + + assert result.success + saved = Path(result.metadata["path"]) + assert saved.parent == tmp_path / "screenshots" + assert saved.suffix == ".png" + + +def test_screenshot_reports_failure(monkeypatch, tmp_path): + monkeypatch.setenv("LOCUS_HOME", str(tmp_path)) + FakeOS(monkeypatch, "macos") # no file is written + assert not ScreenshotTool().execute().success + + +# ── Registration ───────────────────────────────────────────────── + + +def test_every_desktop_tool_has_a_spec_and_risk(): + from locus.tools.desktop import DESKTOP_TOOLS + + tools = [ + OpenPathTool(), + AppControlTool(), + WindowControlTool(), + SystemControlTool(), + ClipboardTool(), + NotifyTool(), + ScreenshotTool(), + ] + assert sorted(t.spec.name for t in tools) == sorted(DESKTOP_TOOLS) + for tool in tools: + assert tool.spec.category == "desktop" + assert callable(tool.risk_for) + + +# ── Wi-Fi and Bluetooth ────────────────────────────────────────── + + +def test_radio_state_is_read_on_windows(monkeypatch): + FakeOS(monkeypatch, "windows", stdout="WiFi On\nBluetooth Off\n") + result = SystemControlTool().execute(action="get_radios") + assert result.content == "Wi-Fi: on; Bluetooth: off" + assert result.metadata["radios"] == {"Wi-Fi": True, "Bluetooth": False} + + +def test_switching_radios_on_windows_passes_kind_and_state(monkeypatch): + fake = FakeOS(monkeypatch, "windows") + assert SystemControlTool().execute(action="wifi_off").content == "Turned Wi-Fi off." + assert fake.calls[0]["args"] == {"kind": "WiFi", "state": "Off"} + assert "$env:LOCUS_ARG_KIND" in fake.calls[0]["script"] + SystemControlTool().execute(action="bluetooth_on") + assert fake.calls[1]["args"] == {"kind": "Bluetooth", "state": "On"} + + +def test_switching_radios_on_linux(monkeypatch): + fake = FakeOS(monkeypatch, "linux") + SystemControlTool().execute(action="wifi_on") + SystemControlTool().execute(action="bluetooth_off") + assert fake.calls[0]["args"] == ["nmcli", "radio", "wifi", "on"] + assert fake.calls[1]["args"] == ["rfkill", "block", "bluetooth"] + + +def test_mac_wifi_uses_the_wifi_device(monkeypatch): + fake = FakeOS( + monkeypatch, + "macos", + stdout=( + "Hardware Port: Ethernet\nDevice: en1\n\n" + "Hardware Port: Wi-Fi\nDevice: en0\n" + ), + ) + SystemControlTool().execute(action="wifi_off") + assert fake.calls[-1]["args"] == ["networksetup", "-setairportpower", "en0", "off"] + + +def test_mac_bluetooth_needs_blueutil(monkeypatch): + FakeOS(monkeypatch, "macos") + monkeypatch.setattr(_os, "has_command", lambda name: False) + result = SystemControlTool().execute(action="bluetooth_on") + assert "blueutil" in result.content + + +def test_radio_failures_are_reported(monkeypatch): + FakeOS(monkeypatch, "windows", returncode=1) + result = SystemControlTool().execute(action="wifi_on") + assert not result.success + assert "Couldn't switch Wi-Fi" in result.content + + +@pytest.mark.parametrize( + "action, risk", + [("get_radios", "read"), ("wifi_off", "change"), ("bluetooth_on", "change")], +) +def test_radio_risk(action, risk): + tool = SystemControlTool() + assert tool_risk("system_control", tool, {"action": action}) == risk diff --git a/tests/tools/test_task_plan.py b/tests/tools/test_task_plan.py new file mode 100644 index 0000000..63c0fc5 --- /dev/null +++ b/tests/tools/test_task_plan.py @@ -0,0 +1,43 @@ +"""The task_plan tool behind Agent mode's checklist.""" + +from __future__ import annotations + +from locus.server.approvals import tool_risk +from locus.tools.task_plan import MAX_STEPS, TaskPlanTool + + +def test_plan_is_cleaned_and_counted(): + result = TaskPlanTool().execute( + steps=[ + {"title": " Find files ", "status": "done"}, + {"title": "Move them", "status": "in_progress"}, + {"title": "Report", "status": "nonsense"}, + {"title": "", "status": "done"}, + "not a step", + ] + ) + + assert result.success + assert result.content == "Plan shown to the user (1 of 3 steps done)." + assert result.metadata["steps"] == [ + {"title": "Find files", "status": "done"}, + {"title": "Move them", "status": "in_progress"}, + {"title": "Report", "status": "pending"}, + ] + + +def test_plan_is_capped(): + steps = [{"title": f"Step {i}", "status": "pending"} for i in range(20)] + assert len(TaskPlanTool().execute(steps=steps).metadata["steps"]) == MAX_STEPS + + +def test_empty_plans_fail(): + assert not TaskPlanTool().execute(steps=[]).success + assert not TaskPlanTool().execute(steps=[{"title": " "}]).success + assert not TaskPlanTool().execute().success + + +def test_planning_never_asks(): + tool = TaskPlanTool() + assert tool_risk("task_plan", tool, {"steps": []}) == "read" + assert tool_risk("task_plan") == "read" diff --git a/tests/tools/test_undo_journal.py b/tests/tools/test_undo_journal.py new file mode 100644 index 0000000..e35450b --- /dev/null +++ b/tests/tools/test_undo_journal.py @@ -0,0 +1,142 @@ +"""Undo for Agent mode file changes.""" + +from __future__ import annotations + +import pytest + +from locus.tools import undo_journal +from locus.tools.undo_journal import MAX_ENTRIES, UndoableFileWriteTool, UndoJournal + + +@pytest.fixture +def journal(tmp_path): + return UndoJournal(tmp_path / "undo") + + +@pytest.fixture +def home(tmp_path): + folder = tmp_path / "home" + folder.mkdir() + return folder + + +def _tool(home, journal): + return UndoableFileWriteTool(allowed_dirs=[str(home)], journal=journal) + + +def test_undo_puts_back_the_old_version(home, journal): + target = home / "notes.txt" + target.write_text("original") + + result = _tool(home, journal).execute(path=str(target), content="rewritten") + + assert result.success + assert target.read_text() == "rewritten" + done, message = journal.undo(result.metadata["undo_id"]) + assert done, message + assert target.read_text() == "original" + # Each change undoes once. + assert journal.undo(result.metadata["undo_id"])[0] is False + + +def test_undo_deletes_a_file_the_agent_created(home, journal): + result = _tool(home, journal).execute(path="new.txt", content="hello") + + created = home / "new.txt" + assert created.read_text() == "hello" + done, message = journal.undo(result.metadata["undo_id"]) + assert done + assert "created" in message + assert not created.exists() + + +def test_undo_never_loses_later_edits(home, journal): + target = home / "notes.txt" + target.write_text("original") + result = _tool(home, journal).execute(path=str(target), content="agent") + target.write_text("the user edited it after") + + done, message = journal.undo(result.metadata["undo_id"]) + + assert not done + assert "changed since" in message + assert target.read_text() == "the user edited it after" + + +def test_undo_after_append(home, journal): + target = home / "log.txt" + target.write_text("one\n") + result = _tool(home, journal).execute( + path=str(target), content="two\n", mode="append" + ) + + assert target.read_text() == "one\ntwo\n" + assert journal.undo(result.metadata["undo_id"])[0] + assert target.read_text() == "one\n" + + +def test_failed_writes_record_nothing(home, journal, tmp_path): + outside = tmp_path / "outside.txt" + result = _tool(home, journal).execute(path=str(outside), content="x") + + assert not result.success + assert "undo_id" not in (result.metadata or {}) + assert journal._load() == [] + + +def test_big_files_are_not_backed_up(home, journal, monkeypatch): + monkeypatch.setattr(undo_journal, "MAX_BACKUP_BYTES", 4) + target = home / "big.txt" + target.write_text("more than four bytes") + + result = _tool(home, journal).execute(path=str(target), content="small") + + assert result.success + assert "undo_id" not in result.metadata + + +def test_old_entries_are_dropped(home, journal): + target = home / "a.txt" + target.write_text("0") + ids = [] + for i in range(MAX_ENTRIES + 3): + ids.append( + _tool(home, journal) + .execute(path=str(target), content=str(i + 1)) + .metadata["undo_id"] + ) + + kept = [e.id for e in journal._load()] + assert len(kept) == MAX_ENTRIES + assert ids[0] not in kept + assert not (journal.root / f"{ids[0]}.bak").exists() + + +def test_undo_endpoint(home, monkeypatch, tmp_path): + fastapi = pytest.importorskip("fastapi") # noqa: F841 + from fastapi.testclient import TestClient + + from locus.core.config import JarvisConfig + from locus.server.app import create_app + + journal = UndoJournal(tmp_path / "undo") + monkeypatch.setattr(undo_journal, "_journal", journal) + target = home / "notes.txt" + target.write_text("original") + undo_id = ( + _tool(home, journal) + .execute(path=str(target), content="new") + .metadata["undo_id"] + ) + + cfg = JarvisConfig() + cfg.analytics.enabled = False + cfg.traces.enabled = False + client = TestClient(create_app(object(), "m", config=cfg)) + + resp = client.post(f"/v1/chat/undo/{undo_id}") + assert resp.status_code == 200 + assert target.read_text() == "original" + again = client.post(f"/v1/chat/undo/{undo_id}") + assert again.status_code == 409 + assert "can't be undone" in again.json()["detail"]