@pheem49/mint 1.14.0 → 1.16.0

package/crates/mint-core/src/prompts/agent.rs

@@ -1,14 +1,31 @@
 use super::persona;
 use crate::MintConfig;
 
-pub(crate) fn is_port_9222_open() -> bool {
-    use std::net::TcpStream;
+pub(crate) fn browser_endpoint_available(config: &MintConfig) -> bool {
+    use std::net::{TcpStream, ToSocketAddrs};
     use std::time::Duration;
-    if let Ok(addr) = "127.0.0.1:9222".parse() {
-        TcpStream::connect_timeout(&addr, Duration::from_millis(50)).is_ok()
-    } else {
-        false
-    }
+    let endpoint = config
+        .extra
+        .get("browserDebugUrl")
+        .and_then(serde_json::Value::as_str)
+        .unwrap_or("http://127.0.0.1:9222/json/list");
+    let Ok(url) = reqwest::Url::parse(endpoint) else {
+        return false;
+    };
+    let Some(host) = url.host_str() else {
+        return false;
+    };
+    let Some(port) = url.port_or_known_default() else {
+        return false;
+    };
+    (host, port)
+        .to_socket_addrs()
+        .ok()
+        .is_some_and(|mut addresses| {
+            addresses.any(|address| {
+                TcpStream::connect_timeout(&address, Duration::from_millis(50)).is_ok()
+            })
+        })
 }
 
 pub(crate) const PLAN_MODE_ALLOWED_ACTIONS: &[&str] = &[
@@ -29,6 +46,9 @@ pub(crate) const PLAN_MODE_ALLOWED_ACTIONS: &[&str] = &[
     "stock",
     "calculation",
     "memory_recall",
+    "mod_help",
+    "mod_list",
+    "mod_validate",
     "git_status",
     "git_diff",
     "git_log",
@@ -47,6 +67,9 @@ pub(crate) const PLAN_MODE_ALLOWED_ACTIONS: &[&str] = &[
     "mcp_list_tools",
     "browser_open",
     "browser_read",
+    "browser_observe",
+    "browser_wait",
+    "browser_scroll",
     "browser_mouse_move",
     "browser_screenshot",
     "run_shell",
@@ -82,6 +105,10 @@ pub(crate) fn base_allowed_actions() -> Vec<&'static str> {
         "stock",
         "calculation",
         "memory_recall",
+        "mod_help",
+        "mod_list",
+        "mod_validate",
+        "mod_publish",
         "git_status",
         "git_diff",
         "git_log",
@@ -145,15 +172,8 @@ pub fn build_system_prompt(
 ) -> String {
     let mut allowed_actions = base_allowed_actions();
 
-    if is_port_9222_open() {
-        allowed_actions.push("browser_open");
-        allowed_actions.push("browser_click");
-        allowed_actions.push("browser_type");
-        allowed_actions.push("browser_read");
-        allowed_actions.push("browser_mouse_move");
-        allowed_actions.push("browser_mouse_click");
-        allowed_actions.push("browser_key_press");
-        allowed_actions.push("browser_screenshot");
+    if browser_endpoint_available(config) {
+        allowed_actions.extend_from_slice(crate::browser::BROWSER_TOOLS);
     }
 
     if !config.avatar_token.is_empty() {
@@ -172,6 +192,7 @@ pub fn build_system_prompt(
     let actions_str = allowed_actions.join("|");
 
     let mut input_formats = Vec::new();
+    input_formats.push("- mod_help / mod_list: {}. mod_validate / mod_publish: {\"arguments\":{\"manifest\":{...},\"source\":\"export function register(mint) {...}\",\"readme\":\"...\",\"expectedHash\":\"existing hash when replacing\"}}.");
     if allowed_actions.contains(&"list_files") {
         input_formats.push(
             "- list_files: {\"path\":\".\",\"limit\":100} (workspace path, ~/path, or allowed user folder like Downloads)",
@@ -182,7 +203,7 @@ pub fn build_system_prompt(
             .push("- read_file: {\"path\":\"relative/path\",\"startLine\":1,\"endLine\":240} (if the file has more lines than the requested range, the result says so explicitly and tells you the exact startLine/endLine to use next — re-read with those before assuming you've seen the whole file)");
     }
     if allowed_actions.contains(&"search_code") {
-        input_formats.push("- search_code: {\"query\":\"text\",\"path\":\".\",\"limit\":20}");
+        input_formats.push("- search_code: {\"query\":\"text\",\"path\":\".\",\"limit\":20} (path MUST be \".\" or a sub-path of the workspace — never use home dir, username, or absolute paths outside the project)");
     }
     if allowed_actions.contains(&"symbols") {
         input_formats.push("- symbols: {\"path\":\".\",\"limit\":100}");
@@ -239,6 +260,9 @@ pub fn build_system_prompt(
     if allowed_actions.contains(&"browser_open") {
         input_formats.push("- browser_open: {\"url\":\"https://example.com\"}");
     }
+    if allowed_actions.contains(&"browser_observe") {
+        input_formats.push("- browser_observe: {textOffset?:number,elementOffset?:number,takeoverComplete?:boolean}; browser_tabs: {operation:list|open|select|close,tabId?:string,url?:string}; browser_fill: {elementRef?:string,selector?:string,text:string}; browser_select: {elementRef?:string,selector?:string,value:string}; browser_scroll: {elementRef?:string,selector?:string,x?:number,y?:number}; browser_wait: {condition:url|text|visible|hidden,value?:string,elementRef?:string,selector?:string,timeoutMs?:number}. browser_click/browser_type also accept elementRef instead of selector.");
+    }
     if allowed_actions.contains(&"browser_click") {
         input_formats.push("- browser_click: {\"selector\":\"button.submit-btn\"} (CSS selector, or text=Login, contains=Submit, xpath=//button)");
     }
@@ -430,11 +454,14 @@ pub fn build_system_prompt(
     if allowed_actions.contains(&"generate_video") {
         input_formats.push("- generate_video / veo.generate: {\"prompt\":\"sunset over ocean waves\",\"aspectRatio\":\"16:9\",\"duration\":5}");
     }
-    input_formats.push("- finish: {\"summary\":\"complete final answer in Thai when the user writes Thai, covering every part of what was asked\",\"verification\":\"what you ran via the verify tool and its result — REQUIRED (finish will be rejected) if this run used apply_patch or write_file, unless you explain here why no check applies (no test suite, documentation-only change, etc.)\"}");
+    input_formats.push("- finish: {\"summary\":\"complete final answer in the user's language, covering every part of what was asked\",\"verification\":\"what you ran via the verify tool and its result — REQUIRED (finish will be rejected) if this run used apply_patch or write_file, unless you explain here why no check applies (no test suite, documentation-only change, etc.)\"}");
 
     let input_formats_str = input_formats.join("\n");
 
     let mut rules = Vec::new();
+    if allowed_actions.contains(&"mod_help") {
+        rules.push("MINT MODS: When asked to create or change a mod, call mod_help and mod_list first. Use the guide to draft the single-file source directly in mod_validate tool arguments, with at most one short progress sentence. Choose reasonable implementation defaults and proceed to validation. After validation succeeds, call mod_publish in execution mode if available; use expectedHash when replacing source. Creation is complete only after the publication result confirms the path in workspace/.mint-mods/<id>/ and activation state. In plan mode, present the draft/plan for approval. Follow the guide's bounded validation retries and report actual diagnostics if blocked.");
+    }
     if plan_mode {
         rules.push(
             "0p. PLAN MODE IS ACTIVE: you may only investigate (read files, search, inspect diagnostics, etc.). Mutating tools such as write_file, apply_patch, and most run_shell/mcp_tool/run_plugin calls are unavailable and will be blocked. Once you have a clear implementation plan, call exit_plan_mode with the full plan; the user will approve or reject it. Do not attempt to edit files or run mutating commands before that approval.",
@@ -464,6 +491,9 @@ pub fn build_system_prompt(
         rules.push(
             "2a. BOUND INVESTIGATION: Keep investigations concise and targeted. Do NOT recursively read dozens of source files across directories. After 2-4 read/search inspection calls, synthesize your findings and present your answer or plan. Do NOT get trapped in endless exploratory reading.",
         );
+        rules.push(
+            "2b. SEARCH PATH SCOPE: For search_code, always use \".\" or a specific sub-directory of the current workspace as the path. NEVER use a home directory, username path, or any path outside the project root — doing so scans thousands of unrelated files and spikes CPU.",
+        );
     }
     if allowed_actions.contains(&"apply_patch") && allowed_actions.contains(&"write_file") {
         rules.push("3. Use apply_patch for all edits to existing files (write_file is only for creating new files). For edits across multiple sections of a file, supply separate small hunks in the 'hunks' array (one hunk per edit location). Keep oldText in each hunk minimal (only 1-3 exact lines needed to pinpoint the edit). NEVER bundle multiple separate edits into a single giant hunk that spans the entire file.");
@@ -473,6 +503,7 @@ pub fn build_system_prompt(
         || allowed_actions.contains(&"apply_patch")
     {
         rules.push("4. Shell commands and file edits require user approval. Mint handles approval after you request the tool.");
+        rules.push("4a. SKILL CHANGES: Create or edit reusable skills only when the user asks for that work. Otherwise complete the current task and suggest the skill in your summary. Use write_file or apply_patch for skill files so Mint can show the concrete diff and request approval for each change. A general file or session permission does not authorize changing persistent skill instructions. After approval, report the saved skill path and what changed.");
     }
     if allowed_actions.contains(&"run_shell") {
         rules.push("5. Shell commands are classified as readOnly, test, network, or mutating. Only policy-allowed modes may run after approval. Never request destructive commands such as rm -rf, git reset --hard, git checkout --, or git clean -f.");
@@ -502,7 +533,7 @@ pub fn build_system_prompt(
         rules.push("7v. A Project Avatar is connected. Call avatar_signal when your reply carries an emotional beat the automatic tool-based reactions can't express — greeting, joking, apologizing, thinking something over. Don't call it for routine tool-driven turns (shell, browser, image/video generation); those already react on their own.");
     }
     if allowed_actions.contains(&"browser_open") {
-        rules.push("7a. Use browser_open to navigate the virtual browser to a URL.");
+        rules.push("7a. Use browser_open to open websites in the automation browser. Inspect the returned page observation, then use browser_observe/browser_read to read the page or browser_screenshot for visual inspection; verify the requested URL/content with browser_wait before finishing. A successful browser_open already opens the website for the user: do not also launch it through run_shell, xdg-open, open, Start-Process, or another browser. Keep website navigation and interaction in the automation browser. If the user explicitly requests an external browser, use that route instead of first opening the website in automation. If automation is unavailable or blocked, report that and ask the user before switching browsers.");
     }
     if allowed_actions.contains(&"browser_click") {
         rules.push("7b. Use browser_click to click elements. Selector can be: CSS selector (button.class, #id, [attr=val]), text=ExactText to find by visible text, contains=PartialText for partial match, or xpath=//expr for XPath. Prefer text= or contains= when the element has visible text but no unique CSS class.");
@@ -527,6 +558,9 @@ pub fn build_system_prompt(
     if allowed_actions.contains(&"browser_screenshot") {
         rules.push("7h. Use browser_screenshot to capture the current page as a PNG image (base64). Use it to inspect the visual state of the page before deciding where to click.");
     }
+    if allowed_actions.contains(&"browser_observe") {
+        rules.push("7i. Browser workflow: browser_observe -> action -> inspect the returned observation -> verify the expected result with browser_wait. Each run starts in its own tab. Use browser_tabs to list/open/select/close tabs; select new popup tabs explicitly. Prefer elementRef from the most recent observation over guessing selectors. Old refs expire after observation refresh, navigation, removed nodes, or tab selection. browser_fill replaces text; browser_type appends. browser_select handles native dropdowns; browser_scroll scrolls the viewport or a target. browser_wait accepts condition url/text/visible/hidden, value or target, and timeoutMs (default 10000, maximum 30000). Observations support textOffset and elementOffset pagination. Coordinate actions require a screenshot of the selected tab within 30 seconds. Never retry an ambiguous click or submission automatically; observe and check the result first. input_dispatched is not task completion. Cite observed URL/text/field evidence in finish.verification, or say the task is unverified/blocked. If blocked by login, CAPTCHA, or repeated lack of progress, ask_user for manual takeover; only after user confirmation call browser_observe with takeoverComplete=true.");
+    }
     if allowed_actions.contains(&"memory_recall") {
         rules.push("8. Use memory_recall to search past interactions before asking the user to repeat context.");
     }
@@ -553,17 +587,27 @@ pub fn build_system_prompt(
         rules.push(&pin_rule);
     }
     if native {
-        rules.push("11. When you explain your reasoning before calling a tool, keep it short, concrete, and in English. Give your final answer in Thai when the task is written in Thai.");
+        rules.push("11. When you call tools, you may include a brief 1-line progress note in the user's language explaining what you are about to do next. Do not repeat greetings in intermediate notes before tool calls — state your immediate action directly. Give your final answer in the language the user uses or explicitly requests. When work is complete, call the finish tool and put the entire final answer in its summary field; do not return a plain-text final answer.");
     } else {
-        rules.push("11. Keep thought short and concrete. Write the thought field in English at all times. Use Thai for the final summary when the task is written in Thai.");
+        rules.push("11. Keep thought short and concrete (1-2 sentences). DO NOT repeat greetings in the thought field — state your immediate action directly. Use the user's language for the thought and final summary, unless they explicitly request another language.");
     }
     rules.push("11a. The final summary must be complete, not just concise. Include every relevant detail you gathered (numbers, names, dates, steps, options, caveats) that answers what the user asked. If the user asked multiple things, address all of them. Only cut filler and repetition, never cut substance. Never truncate a list or explanation just to keep the reply short.");
     rules.push("11b. When a diagram, mindmap, flowchart, or tree structure would clarify your answer, include one directly in your response as a fenced ```mermaid code block using standard Mermaid syntax (flowchart, mindmap, sequenceDiagram, etc.) — do not attempt to draw diagrams with ASCII art or Unicode box characters.");
-    if native {
-        rules.push("12. Commands that open URLs, files, folders, or launch apps (e.g. xdg-open, open) run in the background. Once they succeed (exit: 0), you are done — reply with your final answer directly, with no further tool call.");
+    rules.push("11c. For rich presentation in your final answers, leverage UI blocks and callouts when helpful: \
+- Comparison / Multi-choice: use fenced ```ui-grid with JSON array:\n```ui-grid\n[{\"icon\": \"message-square\", \"title\": \"...\", \"desc\": \"...\", \"badge\": \"...\"}]\n```\n\
+Each ui-grid array item must be one complete JSON object; keep every field (including badge) inside that item's braces, and validate the JSON before closing the code fence.\n\
+For every JSON-backed card, ensure all properties stay inside their intended object and validate the JSON syntax before closing the code fence.\n\
+- Feature showcases: use fenced ```ui-card with JSON array:\n```ui-card\n[{\"title\": \"...\", \"subtitle\": \"...\", \"icon\": \"file-text\", \"badge\": \"...\", \"details\": {\"Key\": \"Value\"}}]\n```\n\
+- UI Prototypes: use fenced ```ui-mockup with JSON object:\n```ui-mockup\n{\"title\": \"...\", \"subtitle\": \"...\", \"dropzoneText\": \"...\", \"metrics\": {...}}\n```\n\
+- Key insights / alerts: use GitHub callouts (> [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING]). Always converse naturally and smoothly; never prefix conversational phrases or greetings with artificial status tags or badge pills. Always put opening and closing ``` fences on their own separate lines.");
+    if allowed_actions.contains(&"browser_open") {
+        rules.push("12. Shell commands may open local files/folders or launch apps when requested. For websites, follow rule 7a and verify the automation browser's observed page; a shell launch is not evidence that a browser task is complete.");
+    } else if native {
+        rules.push("12. Commands that open URLs, files, folders, or launch apps (e.g. xdg-open, open) run in the background. Once they succeed (exit: 0), you are done. Use the finish tool immediately.");
     } else {
         rules.push("12. Commands that open URLs, files, folders, or launch apps (e.g. xdg-open, open) run in the background. Once they succeed (exit: 0), you are done. Use the 'finish' action immediately.");
     }
+    rules.push("12a. Development servers and watchers must use run_shell with background: true so the tool returns a job_id immediately. For Python use python3 -u -m http.server <port>. Inspect shell_output and verify an HTTP response before claiming a server is ready; a job_id alone only proves it started. Keep existing background jobs alive when finishing a response or cancelling AI work, unless the user asks to stop them. Use kill_shell to stop only the requested job.");
     let mature_rule = format!("13. {}", persona::MATURE_CONTENT_POLICY);
     rules.push(&mature_rule);
 
@@ -571,27 +615,27 @@ pub fn build_system_prompt(
 
     let mut prompt = if native {
         format!(
-            "You are Mint Unified CLI Agent, a pragmatic autonomous assistant working in a local workspace.\n\
+            "You are Mint Agent, a pragmatic AI coding agent working in a local workspace. Help with non-coding requests too when your available tools support them.\n\
              You are also Mint: {persona} Keep the personality subtle during technical work: be friendly without adding fluff or reducing precision.\n\
-             Follow an inspect -> act -> verify loop using the tools available to you. On every single turn, either call a tool immediately or give your complete final answer — never do neither. \
-             Do not narrate or announce a tool call in plain text (e.g. \"I will now check the file\") — call the tool itself, in the same turn, instead. \
-             Only reply in plain text with no tool call once the task is genuinely finished and you can give a complete, real final answer; a plain-text reply is always treated as your final answer to the user, so never use it as a placeholder for what you are about to do next.\n\n\
+             Follow an inspect -> act -> verify loop using the tools available to you. On every single turn, call a tool immediately; when the task is complete, call the finish tool with the complete final answer. \
+             When calling tools, you may include a brief 1-line progress note in the user's language explaining what you are about to do next. Do not repeat greetings in intermediate notes — state your immediate action directly. Never output a progress note without calling the tool in the same turn. \
+             Use finish only when the task is genuinely finished. Put all user-facing final text in finish.summary; never return a plain-text final answer.\n\n\
              Rules:\n\
              {rules}",
-            persona = persona::PERSONA_TH,
+            persona = persona::PERSONA,
             rules = rules_str
         )
     } else {
         format!(
-            "You are Mint Unified CLI Agent, a pragmatic autonomous assistant working in a local workspace.\n\
-             You are also Mint: {persona} Keep the personality subtle during technical work: be friendly without adding fluff or reducing precision. Write the \"thought\" field in English at all times (never use Thai for the thought field).\n\
+            "You are Mint Agent, a pragmatic AI coding agent working in a local workspace. Help with non-coding requests too when your available tools support them.\n\
+             You are also Mint: {persona} Keep the personality subtle during technical work: be friendly without adding fluff or reducing precision.\n\
              Follow an inspect -> act -> verify loop. Return exactly one JSON object per response, with no markdown:\n\
              {{\"thought\":\"short user-visible progress note\",\"action\":\"{actions}\",\"input\":{{...}}}}\n\n\
              Input formats:\n\
              {inputs}\n\n\
              Rules:\n\
              {rules}",
-            persona = persona::PERSONA_TH,
+            persona = persona::PERSONA,
             actions = actions_str,
             inputs = input_formats_str,
             rules = rules_str

package/crates/mint-core/src/prompts/chat.rs

@@ -8,7 +8,7 @@ pub fn default_chat_system_instruction() -> String {
         "You are Mint, {persona} \
          {completeness} \
          {mature_policy}",
-        persona = persona::PERSONA_TH,
+        persona = persona::PERSONA,
         completeness = persona::COMPLETENESS_RULE,
         mature_policy = persona::MATURE_CONTENT_POLICY,
     )

package/crates/mint-core/src/prompts/persona.rs

@@ -1,6 +1,6 @@
 /// Shared persona/tone fragment. Callers prepend their own opening sentence
 /// (e.g. "You are Mint, ..." or "You are also Mint: ...") before this fragment.
-pub const PERSONA_TH: &str = "a cute, warm, and helpful Thai assistant. Speak politely, naturally, and sweetly in Thai when the user writes in Thai. Refer to yourself as \"มิ้น\" and use polite particles such as \"ค่ะ\" and \"นะคะ\" where appropriate.";
+pub const PERSONA: &str = "Mint is a female AI assistant with a cute, warm, and helpful personality. Reply in the language the user uses in their current message, or in the language they explicitly request. Follow language changes naturally across the conversation; do not default to any one language. In Thai, refer to yourself as \"มิ้น\" and use feminine polite particles such as \"ค่ะ\" and \"นะคะ\" where appropriate. In other languages, express the same personality naturally without inserting Thai words or particles. Keep answers clear and accurate; do not force sweet wording into technical explanations.";
 
 /// Instruction to give complete, thorough answers rather than truncated ones.
 pub const COMPLETENESS_RULE: &str = "Always give a complete answer, not just a short one: cover every part of what the user asked, include relevant details and context you know, and only trim filler or repetition, never substance. If the user asks a multi-part question, answer all parts.";

package/crates/mint-core/src/prompts/tool_catalog.rs

@@ -12,7 +12,7 @@ use std::path::Path;
 
 use serde_json::{Value, json};
 
-use super::agent::{PLAN_MODE_ALLOWED_ACTIONS, base_allowed_actions, is_port_9222_open};
+use super::agent::{PLAN_MODE_ALLOWED_ACTIONS, base_allowed_actions, browser_endpoint_available};
 use crate::MintConfig;
 use crate::chat::ToolSpec;
 use crate::subagents::list_subagents;
@@ -55,15 +55,8 @@ pub fn tool_catalog(
     allow_subagent_dispatch: bool,
 ) -> Vec<ToolSpec> {
     let mut allowed = base_allowed_actions();
-    if is_port_9222_open() {
-        allowed.push("browser_open");
-        allowed.push("browser_click");
-        allowed.push("browser_type");
-        allowed.push("browser_read");
-        allowed.push("browser_mouse_move");
-        allowed.push("browser_mouse_click");
-        allowed.push("browser_key_press");
-        allowed.push("browser_screenshot");
+    if browser_endpoint_available(config) {
+        allowed.extend_from_slice(crate::browser::BROWSER_TOOLS);
     }
     if !config.avatar_token.is_empty() && !config.avatar_signal_disabled {
         allowed.push("avatar_signal");
@@ -81,6 +74,11 @@ pub fn tool_catalog(
         .filter_map(|action| all_tools().into_iter().find(|t| t.name == action))
         .collect();
 
+    // Native models need a structured terminal action. Plain text can be a
+    // progress preamble or a final reply, but finish.summary is unambiguous
+    // and can be streamed as the final answer.
+    tools.push(finish_tool());
+
     if allow_subagent_dispatch && !plan_mode {
         let subagents = list_subagents(Some(root));
         if !subagents.is_empty() {
@@ -116,8 +114,54 @@ fn dispatch_subagent_tool(subagents: &[crate::subagents::SubagentDefinition]) ->
     )
 }
 
+fn finish_tool() -> ToolSpec {
+    tool(
+        "finish",
+        "Complete the task and deliver the final answer. Call this only when no further tool calls are needed. Put the complete user-facing response in summary. If this run changed files, verification must state the check and its result, or explain why no check applies.",
+        schema(
+            json!({
+                "summary": {
+                    "type": "string",
+                    "description": "Complete final answer in the user's language."
+                },
+                "verification": {
+                    "type": "string",
+                    "description": "Verification performed after file changes and its result; otherwise omit."
+                }
+            }),
+            &["summary"],
+        ),
+    )
+}
+
 fn all_tools() -> Vec<ToolSpec> {
     vec![
+        tool(
+            "mod_help",
+            "Read the Mint Mods authoring guide. Call before creating or editing a mod from a user prompt.",
+            schema(json!({}), &[]),
+        ),
+        tool(
+            "mod_list",
+            "Inspect workspace mods, sources, hashes, permissions and active revisions.",
+            schema(json!({}), &[]),
+        ),
+        tool(
+            "mod_validate",
+            "Compile and preview a single-file Mint mod without running real tools. Follow mod_help; fix errors before publishing.",
+            schema(
+                json!({"arguments":{"type":"object","properties":{"manifest":{"type":"object"},"source":{"type":"string"},"readme":{"type":"string"}},"required":["manifest","source"]}}),
+                &["arguments"],
+            ),
+        ),
+        tool(
+            "mod_publish",
+            "Publish a validated mod in workspace/.mint-mods/<id> and open it in this chat. Use only when the user requests mod creation/editing. Requested special permissions require approval. Existing source requires expectedHash.",
+            schema(
+                json!({"arguments":{"type":"object","properties":{"manifest":{"type":"object"},"source":{"type":"string"},"readme":{"type":"string"},"expectedHash":{"type":"string"}},"required":["manifest","source"]}}),
+                &["arguments"],
+            ),
+        ),
         tool(
             "conversation_summary",
             "Internal tool representing a compacted conversation history summary from previous steps.",
@@ -277,26 +321,66 @@ fn all_tools() -> Vec<ToolSpec> {
         ),
         tool(
             "browser_click",
-            "Click an element in the automation browser.",
+            "Click an observed element. Provide elementRef or selector, not both.",
             schema(
-                json!({
-                    "selector": {
-                        "type": "string",
-                        "description": "CSS selector, or text=ExactText, contains=PartialText, xpath=//expr."
-                    }
-                }),
-                &["selector"],
+                json!({"elementRef":{"type":"string"},"selector":{"type":"string"}}),
+                &[],
             ),
         ),
         tool(
             "browser_type",
-            "Type text into a form field or search box in the automation browser.",
+            "Append text to a field. Provide elementRef or selector, not both.",
             schema(
-                json!({
-                    "selector": { "type": "string", "description": "Same formats as browser_click." },
-                    "text": { "type": "string" }
-                }),
-                &["selector", "text"],
+                json!({"elementRef":{"type":"string"},"selector":{"type":"string"},"text":{"type":"string"}}),
+                &["text"],
+            ),
+        ),
+        tool(
+            "browser_fill",
+            "Replace a field's value and verify it.",
+            schema(
+                json!({"elementRef":{"type":"string"},"selector":{"type":"string"},"text":{"type":"string"}}),
+                &["text"],
+            ),
+        ),
+        tool(
+            "browser_select",
+            "Select a native dropdown option by value.",
+            schema(
+                json!({"elementRef":{"type":"string"},"selector":{"type":"string"},"value":{"type":"string"}}),
+                &["value"],
+            ),
+        ),
+        tool(
+            "browser_observe",
+            "Read structured page state and fresh element references. Confirm takeover only after the user has completed it.",
+            schema(
+                json!({"textOffset":{"type":"integer","minimum":0},"elementOffset":{"type":"integer","minimum":0},"takeoverComplete":{"type":"boolean"}}),
+                &[],
+            ),
+        ),
+        tool(
+            "browser_tabs",
+            "List/open/select/close tabs. Selection and closure require explicit tabId; popups are never auto-selected.",
+            schema(
+                json!({"operation":{"type":"string","enum":["list","open","select","close"]},"tabId":{"type":"string"},"url":{"type":"string"}}),
+                &["operation"],
+            ),
+        ),
+        tool(
+            "browser_scroll",
+            "Scroll the viewport or an observed element by pixels.",
+            schema(
+                json!({"elementRef":{"type":"string"},"selector":{"type":"string"},"x":{"type":"number"},"y":{"type":"number"}}),
+                &[],
+            ),
+        ),
+        tool(
+            "browser_wait",
+            "Wait for a URL, text, or element visibility condition; at most 30 seconds.",
+            schema(
+                json!({"condition":{"type":"string","enum":["url","text","visible","hidden"]},"value":{"type":"string"},"elementRef":{"type":"string"},"selector":{"type":"string"},"timeoutMs":{"type":"integer","minimum":1,"maximum":30000}}),
+                &["condition"],
             ),
         ),
         tool(
@@ -306,7 +390,7 @@ fn all_tools() -> Vec<ToolSpec> {
         ),
         tool(
             "browser_mouse_move",
-            "Move the real mouse cursor to absolute (x, y) coordinates.",
+            "Move the browser cursor to viewport (x, y) coordinates.",
             schema(
                 json!({ "x": { "type": "number" }, "y": { "type": "number" } }),
                 &["x", "y"],
@@ -597,7 +681,7 @@ fn all_tools() -> Vec<ToolSpec> {
         tool(
             "run_shell",
             "Run a local shell command. Subject to safety classification and user approval; destructive commands are blocked outright. \
-             Set 'background' to true for a long-running command (a dev server, a watcher, ...) so it doesn't \
+             Always set 'background' to true for development servers and watchers. For example: {command: 'python3 -u -m http.server 8000', background: true}. Check output and HTTP readiness before claiming the server is ready. Set 'background' to true for a long-running command (a dev server, a watcher, ...) so it doesn't \
              block you — it returns a job_id immediately instead of waiting for the command to exit. Use the \
              'shell_output' tool to check on it later and 'kill_shell' to stop it.",
             schema(
@@ -692,7 +776,7 @@ fn all_tools() -> Vec<ToolSpec> {
         ),
         tool(
             "apply_patch",
-            "Apply one or more find-and-replace hunks to an existing file. This is the only way to edit existing files (write_file is for new files only). Keep oldText minimal (1-3 exact lines) per hunk; use separate hunks for separate edit locations.",
+            "Apply one or more find-and-replace hunks to an existing file. Pass patch as a JSON object, never a JSON-encoded string: {\"patch\":{\"path\":\"style.css\",\"hunks\":[{\"oldText\":\"exact existing text\",\"newText\":\"replacement text\"}]}}. This is the only way to edit existing files (write_file is for new files only). Keep oldText minimal (1-3 exact lines) per hunk; use separate hunks for separate edit locations.",
             schema(
                 json!({
                     "patch": {
@@ -1097,4 +1181,14 @@ mod tests {
             }
         }
     }
+
+    #[test]
+    fn native_catalog_always_offers_finish() {
+        let config = MintConfig::default();
+        let tools = tool_catalog(&config, false, Path::new("."), true);
+        assert!(
+            tools.iter().any(|tool| tool.name == "finish"),
+            "native tool catalog must include the terminal finish tool"
+        );
+    }
 }

package/crates/mint-core/src/search/knowledge.rs

@@ -225,6 +225,12 @@ impl KnowledgeStore {
 
 pub fn extract_document_text(path: &Path, config: &MintConfig) -> Result<String, KnowledgeError> {
     let path = assert_path_capability(path, Capability::Read, config)?;
+    extract_managed_document_text(&path)
+}
+
+// Only Library may bypass workspace policy after validating a managed original.
+pub(crate) fn extract_managed_document_text(path: &Path) -> Result<String, KnowledgeError> {
+    let path = path.to_path_buf();
     let metadata = fs::metadata(&path).map_err(|source| KnowledgeError::Read {
         path: path.clone(),
         source,
@@ -245,7 +251,7 @@ pub fn extract_document_text(path: &Path, config: &MintConfig) -> Result<String,
     Ok(content)
 }
 
-fn supported(path: &Path) -> bool {
+pub(crate) fn supported(path: &Path) -> bool {
     path.extension()
         .and_then(|extension| extension.to_str())
         .is_some_and(|extension| {