@hypothesi/tauri-mcp-server 0.12.0 → 0.13.1

package/dist/driver/webview-interactions.d.ts

@@ -18,9 +18,10 @@ export declare const InteractSchema: z.ZodObject<{
     windowId: z.ZodOptional<z.ZodString>;
     appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
 } & {
-    action: z.ZodEnum<["click", "double-click", "long-press", "scroll", "swipe", "focus"]>;
+    action: z.ZodEnum<["click", "double-click", "long-press", "scroll", "swipe", "focus", "hover", "right-click"]>;
     selector: z.ZodOptional<z.ZodString>;
     strategy: z.ZodDefault<z.ZodEnum<["css", "xpath", "text"]>>;
+    nth: z.ZodOptional<z.ZodNumber>;
     x: z.ZodOptional<z.ZodNumber>;
     y: z.ZodOptional<z.ZodNumber>;
     duration: z.ZodOptional<z.ZodNumber>;
@@ -31,11 +32,12 @@ export declare const InteractSchema: z.ZodObject<{
     toX: z.ZodOptional<z.ZodNumber>;
     toY: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    action: "swipe" | "focus" | "click" | "double-click" | "long-press" | "scroll";
+    action: "swipe" | "focus" | "click" | "double-click" | "long-press" | "scroll" | "hover" | "right-click";
     strategy: "css" | "text" | "xpath";
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
     selector?: string | undefined;
+    nth?: number | undefined;
     x?: number | undefined;
     y?: number | undefined;
     duration?: number | undefined;
@@ -46,11 +48,12 @@ export declare const InteractSchema: z.ZodObject<{
     toX?: number | undefined;
     toY?: number | undefined;
 }, {
-    action: "swipe" | "focus" | "click" | "double-click" | "long-press" | "scroll";
+    action: "swipe" | "focus" | "click" | "double-click" | "long-press" | "scroll" | "hover" | "right-click";
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
     selector?: string | undefined;
     strategy?: "css" | "text" | "xpath" | undefined;
+    nth?: number | undefined;
     x?: number | undefined;
     y?: number | undefined;
     duration?: number | undefined;
@@ -69,19 +72,22 @@ export declare const ScreenshotSchema: z.ZodObject<{
     quality: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     filePath: z.ZodOptional<z.ZodString>;
     maxWidth: z.ZodOptional<z.ZodNumber>;
+    allowScreenCapture: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
     format: "png" | "jpeg";
     quality: number;
+    allowScreenCapture: boolean;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
     maxWidth?: number | undefined;
     filePath?: string | undefined;
 }, {
-    format?: "png" | "jpeg" | undefined;
-    quality?: number | undefined;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
+    format?: "png" | "jpeg" | undefined;
+    quality?: number | undefined;
     maxWidth?: number | undefined;
+    allowScreenCapture?: boolean | undefined;
     filePath?: string | undefined;
 }>;
 export declare const KeyboardSchema: z.ZodObject<{
@@ -91,25 +97,28 @@ export declare const KeyboardSchema: z.ZodObject<{
     action: z.ZodEnum<["type", "press", "down", "up"]>;
     selector: z.ZodOptional<z.ZodString>;
     strategy: z.ZodDefault<z.ZodEnum<["css", "xpath", "text"]>>;
+    nth: z.ZodOptional<z.ZodNumber>;
     text: z.ZodOptional<z.ZodString>;
     key: z.ZodOptional<z.ZodString>;
     modifiers: z.ZodOptional<z.ZodArray<z.ZodEnum<["Control", "Alt", "Shift", "Meta"]>, "many">>;
 }, "strip", z.ZodTypeAny, {
     action: "type" | "press" | "down" | "up";
     strategy: "css" | "text" | "xpath";
-    text?: string | undefined;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
+    text?: string | undefined;
     selector?: string | undefined;
+    nth?: number | undefined;
     key?: string | undefined;
     modifiers?: ("Control" | "Alt" | "Shift" | "Meta")[] | undefined;
 }, {
     action: "type" | "press" | "down" | "up";
-    text?: string | undefined;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
+    text?: string | undefined;
     selector?: string | undefined;
     strategy?: "css" | "text" | "xpath" | undefined;
+    nth?: number | undefined;
     key?: string | undefined;
     modifiers?: ("Control" | "Alt" | "Shift" | "Meta")[] | undefined;
 }>;
@@ -136,42 +145,22 @@ export declare const WaitForSchema: z.ZodObject<{
     appIdentifier?: string | number | undefined;
     strategy?: "css" | "text" | "xpath" | undefined;
 }>;
-export declare const GetStylesSchema: z.ZodObject<{
-    windowId: z.ZodOptional<z.ZodString>;
-    appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-} & {
-    selector: z.ZodString;
-    strategy: z.ZodDefault<z.ZodEnum<["css", "xpath", "text"]>>;
-    properties: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    multiple: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, "strip", z.ZodTypeAny, {
-    selector: string;
-    strategy: "css" | "text" | "xpath";
-    multiple: boolean;
-    windowId?: string | undefined;
-    appIdentifier?: string | number | undefined;
-    properties?: string[] | undefined;
-}, {
-    selector: string;
-    windowId?: string | undefined;
-    appIdentifier?: string | number | undefined;
-    strategy?: "css" | "text" | "xpath" | undefined;
-    properties?: string[] | undefined;
-    multiple?: boolean | undefined;
-}>;
 export declare const ExecuteJavaScriptSchema: z.ZodObject<{
     windowId: z.ZodOptional<z.ZodString>;
     appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
 } & {
     script: z.ZodString;
     args: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    timeout: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     script: string;
+    timeout?: number | undefined;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
     args?: unknown[] | undefined;
 }, {
     script: string;
+    timeout?: number | undefined;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
     args?: unknown[] | undefined;
@@ -181,14 +170,20 @@ export declare const FocusElementSchema: z.ZodObject<{
     appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
 } & {
     selector: z.ZodString;
+    strategy: z.ZodDefault<z.ZodEnum<["css", "xpath", "text"]>>;
+    nth: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     selector: string;
+    strategy: "css" | "text" | "xpath";
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
+    nth?: number | undefined;
 }, {
     selector: string;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
+    strategy?: "css" | "text" | "xpath" | undefined;
+    nth?: number | undefined;
 }>;
 export declare const FindElementSchema: z.ZodObject<{
     windowId: z.ZodOptional<z.ZodString>;
@@ -196,16 +191,31 @@ export declare const FindElementSchema: z.ZodObject<{
 } & {
     selector: z.ZodString;
     strategy: z.ZodDefault<z.ZodEnum<["css", "xpath", "text"]>>;
+    nth: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    properties: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    visibleOnly: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    includeHtml: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
     selector: string;
     strategy: "css" | "text" | "xpath";
+    limit: number;
+    visibleOnly: boolean;
+    includeHtml: boolean;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
+    nth?: number | undefined;
+    properties?: string[] | undefined;
 }, {
     selector: string;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
     strategy?: "css" | "text" | "xpath" | undefined;
+    nth?: number | undefined;
+    limit?: number | undefined;
+    properties?: string[] | undefined;
+    visibleOnly?: boolean | undefined;
+    includeHtml?: boolean | undefined;
 }>;
 export declare const GetConsoleLogsSchema: z.ZodObject<{
     windowId: z.ZodOptional<z.ZodString>;
@@ -215,14 +225,14 @@ export declare const GetConsoleLogsSchema: z.ZodObject<{
     since: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     filter?: string | undefined;
+    since?: string | undefined;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
-    since?: string | undefined;
 }, {
     filter?: string | undefined;
+    since?: string | undefined;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
-    since?: string | undefined;
 }>;
 export declare const DomSnapshotSchema: z.ZodObject<{
     windowId: z.ZodOptional<z.ZodString>;
@@ -248,6 +258,7 @@ export declare function interact(options: {
     action: string;
     selector?: string;
     strategy?: string;
+    nth?: number;
     x?: number;
     y?: number;
     duration?: number;
@@ -267,6 +278,7 @@ export interface ScreenshotOptions {
     filePath?: string;
     appIdentifier?: string | number;
     maxWidth?: number;
+    allowScreenCapture?: boolean;
 }
 export interface ScreenshotFileResult {
     filePath: string;
@@ -277,6 +289,7 @@ export interface KeyboardOptions {
     action: string;
     selectorOrKey?: string;
     strategy?: string;
+    nth?: number;
     textOrModifiers?: string | string[];
     modifiers?: string[];
     windowId?: string;
@@ -292,18 +305,10 @@ export interface WaitForOptions {
     appIdentifier?: string | number;
 }
 export declare function waitFor(options: WaitForOptions): Promise<string>;
-export interface GetStylesOptions {
-    selector: string;
-    strategy?: string;
-    properties?: string[];
-    multiple?: boolean;
-    windowId?: string;
-    appIdentifier?: string | number;
-}
-export declare function getStyles(options: GetStylesOptions): Promise<string>;
 export interface ExecuteJavaScriptOptions {
     script: string;
     args?: unknown[];
+    timeout?: number;
     windowId?: string;
     appIdentifier?: string | number;
 }
@@ -311,6 +316,7 @@ export declare function executeJavaScript(options: ExecuteJavaScriptOptions): Pr
 export interface FocusElementOptions {
     selector: string;
     strategy?: string;
+    nth?: number;
     windowId?: string;
     appIdentifier?: string | number;
 }
@@ -318,6 +324,11 @@ export declare function focusElement(options: FocusElementOptions): Promise<stri
 export interface FindElementOptions {
     selector: string;
     strategy: string;
+    nth?: number;
+    limit?: number;
+    properties?: string[];
+    visibleOnly?: boolean;
+    includeHtml?: boolean;
     windowId?: string;
     appIdentifier?: string | number;
 }
@@ -326,6 +337,10 @@ export interface FindElementOptions {
  */
 export declare function findElement(options: FindElementOptions): Promise<string>;
 export interface GetConsoleLogsOptions {
+    lines?: number;
+    level?: 'log' | 'debug' | 'info' | 'warn' | 'error';
+    maxChars?: number;
+    maxCharsPerEntry?: number;
     filter?: string;
     since?: string;
     windowId?: string;

package/dist/driver/webview-interactions.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { executeInWebview, executeInWebviewWithContext, captureScreenshot, getConsoleLogs as getConsoleLogsFromCapture, } from './webview-executor.js';
+import { executeInWebview, executeInWebviewWithContext, executeAsyncInWebview, captureScreenshot, getConsoleLogs as getConsoleLogsFromCapture, } from './webview-executor.js';
 import { SCRIPTS, buildScript, buildTypeScript, buildKeyEventScript } from './scripts/index.js';
 // ============================================================================
 // Base Schema for Window Targeting
@@ -24,14 +24,21 @@ export const WindowTargetSchema = z.object({
 const selectorStrategyField = z.enum(['css', 'xpath', 'text']).default('css').describe('Selector strategy: "css" (default) for CSS selectors, "xpath" for XPath expressions, ' +
     '"text" to find elements by text content, with fallback to placeholder, aria-label, ' +
     'and title attributes. Ref IDs (e.g., "ref=e3") work with any strategy.');
+/**
+ * Optional nth parameter for disambiguating multiple matches.
+ * Required when a text selector matches more than one visible element.
+ */
+const nthField = z.number().int().min(0).optional().describe('Zero-based index to pick one of several matching elements. ' +
+    'Omit when the selector is unique. Required when a text selector matches more than one visible element.');
 // ============================================================================
 // Schemas
 // ============================================================================
 export const InteractSchema = WindowTargetSchema.extend({
-    action: z.enum(['click', 'double-click', 'long-press', 'scroll', 'swipe', 'focus'])
+    action: z.enum(['click', 'double-click', 'long-press', 'scroll', 'swipe', 'focus', 'hover', 'right-click'])
         .describe('Type of interaction to perform'),
     selector: z.string().optional().describe('Element selector: CSS selector (default), XPath expression, text content, or ref ID (e.g., "ref=e3")'),
     strategy: selectorStrategyField,
+    nth: nthField,
     x: z.number().optional().describe('X coordinate for direct coordinate interaction'),
     y: z.number().optional().describe('Y coordinate for direct coordinate interaction'),
     duration: z.number().optional()
@@ -49,6 +56,7 @@ export const ScreenshotSchema = WindowTargetSchema.extend({
     filePath: z.string().optional().describe('File path to save the screenshot to instead of returning as base64'),
     maxWidth: z.number().int().positive().optional().describe('Maximum width in pixels. Images wider than this will be scaled down proportionally. ' +
         'Can also be set via TAURI_MCP_SCREENSHOT_MAX_WIDTH environment variable.'),
+    allowScreenCapture: z.boolean().optional().default(false).describe('Allow an interactive OS screen-sharing permission prompt if native and html2canvas capture fail'),
 });
 export const KeyboardSchema = WindowTargetSchema.extend({
     action: z.enum(['type', 'press', 'down', 'up'])
@@ -56,6 +64,7 @@ export const KeyboardSchema = WindowTargetSchema.extend({
     selector: z.string().optional().describe('Element selector for element to type into (required for "type" action): ' +
         'CSS selector (default), XPath, text content, or ref ID'),
     strategy: selectorStrategyField,
+    nth: nthField,
     text: z.string().optional().describe('Text to type (required for "type" action)'),
     key: z.string().optional().describe('Key to press (required for "press/down/up" actions, e.g., "Enter", "a", "Escape")'),
     modifiers: z.array(z.enum(['Control', 'Alt', 'Shift', 'Meta'])).optional().describe('Modifier keys to hold'),
@@ -66,26 +75,30 @@ export const WaitForSchema = WindowTargetSchema.extend({
     strategy: selectorStrategyField.describe('Selector strategy (applies when type is "selector"): "css" (default), "xpath", or "text".'),
     timeout: z.number().optional().default(5000).describe('Timeout in milliseconds (default: 5000ms)'),
 });
-export const GetStylesSchema = WindowTargetSchema.extend({
-    selector: z.string().describe('Element selector: CSS selector (default), XPath expression, text content, or ref ID'),
-    strategy: selectorStrategyField,
-    properties: z.array(z.string()).optional().describe('Specific CSS properties to retrieve. If omitted, returns all computed styles'),
-    multiple: z.boolean().optional().default(false)
-        .describe('Whether to get styles for all matching elements (true) or just the first (false)'),
-});
 export const ExecuteJavaScriptSchema = WindowTargetSchema.extend({
     script: z.string().describe('JavaScript code to execute in the webview context. ' +
         'If returning a value, it must be JSON-serializable. ' +
         'For functions that return values, use IIFE syntax: "(() => { return value; })()" not "() => { return value; }"'),
     args: z.array(z.unknown()).optional().describe('Arguments to pass to the script'),
+    timeout: z.number().int().positive().optional().describe('Execution timeout in milliseconds'),
 });
 export const FocusElementSchema = WindowTargetSchema.extend({
     selector: z.string().describe('CSS selector for element to focus'),
+    strategy: selectorStrategyField,
+    nth: nthField,
 });
 export const FindElementSchema = WindowTargetSchema.extend({
     selector: z.string().describe('The selector to find: CSS selector (default), XPath expression, text content, or ref ID (e.g., "ref=e3"). ' +
         'Interpretation depends on strategy.'),
     strategy: selectorStrategyField,
+    nth: nthField,
+    limit: z.number().int().min(1).max(50).optional().default(5)
+        .describe('Maximum number of matches to return. Total match count is always reported.'),
+    properties: z.array(z.string()).optional().describe('Computed CSS properties to include for each match, e.g. ["display","opacity","font-size"].'),
+    visibleOnly: z.boolean().optional().default(true)
+        .describe('Return only rendered elements. Set false to include display:none and off-screen nodes.'),
+    includeHtml: z.boolean().optional().default(false)
+        .describe('Include outerHTML for each match, truncated to 2000 characters.'),
 });
 export const GetConsoleLogsSchema = WindowTargetSchema.extend({
     filter: z.string().optional().describe('Regex or keyword to filter logs'),
@@ -100,7 +113,7 @@ export const DomSnapshotSchema = WindowTargetSchema.extend({
 // Implementation Functions
 // ============================================================================
 export async function interact(options) {
-    const { action, selector, strategy, x, y, duration, scrollX, scrollY, fromX, fromY, toX, toY, windowId, appIdentifier } = options;
+    const { action, selector, strategy, nth, x, y, duration, scrollX, scrollY, fromX, fromY, toX, toY, windowId, appIdentifier } = options;
     // Handle swipe action separately since it has different logic
     if (action === 'swipe') {
         return performSwipe({ fromX, fromY, toX, toY, duration, windowId, appIdentifier });
@@ -110,12 +123,13 @@ export async function interact(options) {
         if (!selector) {
             throw new Error('Focus action requires a selector');
         }
-        return focusElement({ selector, strategy, windowId, appIdentifier });
+        return focusElement({ selector, strategy, nth, windowId, appIdentifier });
     }
     const script = buildScript(SCRIPTS.interact, {
         action,
         selector: selector ?? null,
         strategy: strategy ?? 'css',
+        nth: nth ?? null,
         x: x ?? null,
         y: y ?? null,
         duration: duration ?? 500,
@@ -145,9 +159,11 @@ async function performSwipe(options) {
     }
 }
 export async function screenshot(options = {}) {
-    const { quality, format = 'jpeg', windowId, filePath, appIdentifier, maxWidth } = options;
+    const { quality, format = 'jpeg', windowId, filePath, appIdentifier, maxWidth, allowScreenCapture } = options;
     // Use the native screenshot function from webview-executor
-    const result = await captureScreenshot({ format, quality, windowId, appIdentifier, maxWidth });
+    const result = await captureScreenshot({
+        format, quality, windowId, appIdentifier, maxWidth, allowScreenCapture,
+    });
     // If filePath is provided, write to file instead of returning base64
     if (filePath) {
         // Find the image content in the result
@@ -162,15 +178,15 @@ export async function screenshot(options = {}) {
     return result;
 }
 export async function keyboard(options) {
-    const { action, selectorOrKey, strategy, textOrModifiers, modifiers, windowId, appIdentifier } = options;
+    const { action, selectorOrKey, strategy, nth, textOrModifiers, modifiers, windowId, appIdentifier } = options;
     // Handle the different parameter combinations based on action
     if (action === 'type') {
         const selector = selectorOrKey;
         const text = textOrModifiers;
-        if (!selector || !text) {
+        if (!selector || text === undefined) {
             throw new Error('Type action requires both selector and text parameters');
         }
-        const script = buildTypeScript(selector, text, strategy);
+        const script = buildTypeScript(selector, text, strategy, nth);
         try {
             return await executeInWebview(script, windowId, appIdentifier);
         }
@@ -205,24 +221,8 @@ export async function waitFor(options) {
         throw new Error(`Wait failed: ${message}`);
     }
 }
-export async function getStyles(options) {
-    const { selector, strategy, properties, multiple = false, windowId, appIdentifier } = options;
-    const script = buildScript(SCRIPTS.getStyles, {
-        selector,
-        strategy: strategy ?? 'css',
-        properties: properties || [],
-        multiple,
-    });
-    try {
-        return await executeInWebview(script, windowId, appIdentifier);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Get styles failed: ${message}`);
-    }
-}
 export async function executeJavaScript(options) {
-    const { script, args, windowId, appIdentifier } = options;
+    const { script, args, timeout, windowId, appIdentifier } = options;
     // If args are provided, we need to inject them into the script context
     const wrappedScript = args && args.length > 0
         ? `
@@ -233,7 +233,13 @@ export async function executeJavaScript(options) {
       `
         : script;
     try {
-        const { result, windowLabel, warning } = await executeInWebviewWithContext(wrappedScript, windowId, appIdentifier);
+        const execution = timeout === undefined
+            ? await executeInWebviewWithContext(wrappedScript, windowId, appIdentifier)
+            : {
+                result: await executeAsyncInWebview(buildTimedScript(wrappedScript), windowId, timeout, appIdentifier),
+                windowLabel: windowId ?? 'main',
+            };
+        const { result, windowLabel, warning } = execution;
         // Build response with window context
         let response = result;
         if (warning) {
@@ -248,9 +254,16 @@ export async function executeJavaScript(options) {
         throw new Error(`JavaScript execution failed: ${message}`);
     }
 }
+function buildTimedScript(script) {
+    const trimmed = script.trim();
+    if (/\breturn\b/.test(trimmed) && !trimmed.startsWith('(')) {
+        return `return (async () => { ${trimmed} })();`;
+    }
+    return `return (${trimmed});`;
+}
 export async function focusElement(options) {
-    const { selector, strategy, windowId, appIdentifier } = options;
-    const script = buildScript(SCRIPTS.focus, { selector, strategy: strategy ?? 'css' });
+    const { selector, strategy, nth, windowId, appIdentifier } = options;
+    const script = buildScript(SCRIPTS.focus, { selector, strategy: strategy ?? 'css', nth: nth ?? null });
     try {
         return await executeInWebview(script, windowId, appIdentifier);
     }
@@ -263,8 +276,17 @@ export async function focusElement(options) {
  * Find an element using various selector strategies.
  */
 export async function findElement(options) {
-    const { selector, strategy, windowId, appIdentifier } = options;
-    const script = buildScript(SCRIPTS.findElement, { selector, strategy });
+    const { selector, strategy, nth, limit, properties, visibleOnly, includeHtml, windowId, appIdentifier } = options;
+    await ensureAriaApiLoaded(windowId, appIdentifier);
+    const script = buildScript(SCRIPTS.findElement, {
+        selector,
+        strategy,
+        nth: nth ?? null,
+        limit: limit ?? 5,
+        properties: properties || [],
+        visibleOnly: visibleOnly ?? true,
+        includeHtml: includeHtml ?? false,
+    });
     try {
         return await executeInWebview(script, windowId, appIdentifier);
     }
@@ -277,9 +299,9 @@ export async function findElement(options) {
  * Get console logs from the webview.
  */
 export async function getConsoleLogs(options = {}) {
-    const { filter, since, windowId, appIdentifier } = options;
+    const { lines = 50, level, maxChars = 20000, maxCharsPerEntry = 2000, filter, since, windowId, appIdentifier } = options;
     try {
-        return await getConsoleLogsFromCapture(filter, since, windowId, appIdentifier);
+        return await getConsoleLogsFromCapture({ filter, since, lines, windowId, appIdentifier, level, maxChars, maxCharsPerEntry });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/monitor/logs.d.ts

@@ -2,28 +2,40 @@ import { z } from 'zod';
 export declare const ReadLogsSchema: z.ZodObject<{
     source: z.ZodEnum<["console", "android", "ios", "system"]>;
     lines: z.ZodDefault<z.ZodNumber>;
+    level: z.ZodOptional<z.ZodEnum<["log", "debug", "info", "warn", "error"]>>;
+    maxChars: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxCharsPerEntry: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     filter: z.ZodOptional<z.ZodString>;
     since: z.ZodOptional<z.ZodString>;
     windowId: z.ZodOptional<z.ZodString>;
     appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
 }, "strip", z.ZodTypeAny, {
     lines: number;
+    maxChars: number;
+    maxCharsPerEntry: number;
     source: "android" | "ios" | "console" | "system";
     filter?: string | undefined;
+    since?: string | undefined;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
-    since?: string | undefined;
+    level?: "error" | "log" | "debug" | "info" | "warn" | undefined;
 }, {
     source: "android" | "ios" | "console" | "system";
     filter?: string | undefined;
     lines?: number | undefined;
+    since?: string | undefined;
     windowId?: string | undefined;
     appIdentifier?: string | number | undefined;
-    since?: string | undefined;
+    level?: "error" | "log" | "debug" | "info" | "warn" | undefined;
+    maxChars?: number | undefined;
+    maxCharsPerEntry?: number | undefined;
 }>;
 export interface ReadLogsOptions {
     source: 'console' | 'android' | 'ios' | 'system';
     lines?: number;
+    level?: 'log' | 'debug' | 'info' | 'warn' | 'error';
+    maxChars?: number;
+    maxCharsPerEntry?: number;
     filter?: string;
     since?: string;
     windowId?: string;

package/dist/monitor/logs.js

@@ -47,19 +47,25 @@ function findAdbPath() {
 export const ReadLogsSchema = z.object({
     source: z.enum(['console', 'android', 'ios', 'system'])
         .describe('Log source: "console" for webview JS logs, "android" for logcat, "ios" for simulator, "system" for desktop'),
-    lines: z.number().default(50),
+    lines: z.number().int().positive().default(50),
+    level: z.enum(['log', 'debug', 'info', 'warn', 'error']).optional()
+        .describe('Only return entries at this console level.'),
+    maxChars: z.number().int().min(500).max(100000).optional().default(20000)
+        .describe('Maximum characters in the response. Entries are truncated and the oldest are dropped to fit.'),
+    maxCharsPerEntry: z.number().int().min(100).max(20000).optional().default(2000)
+        .describe('Maximum characters kept from each log entry.'),
     filter: z.string().optional().describe('Regex or keyword to filter logs'),
     since: z.string().optional().describe('ISO timestamp to filter logs since (e.g. 2023-10-27T10:00:00Z)'),
     windowId: z.string().optional().describe('Window label for console logs (defaults to "main")'),
     appIdentifier: z.union([z.string(), z.number()]).optional().describe('App port or bundle ID for console logs. Defaults to the only connected app or the default app if multiple are connected.'),
 });
 export async function readLogs(options) {
-    const { source, lines = 50, filter, since, windowId, appIdentifier } = options;
+    const { source, lines = 50, level, maxChars = 20000, maxCharsPerEntry = 2000, filter, since, windowId, appIdentifier } = options;
     try {
         let output = '';
         // Handle console logs (webview JS logs)
         if (source === 'console') {
-            return await getConsoleLogs({ filter, since, windowId, appIdentifier });
+            return await getConsoleLogs({ lines, level, maxChars, maxCharsPerEntry, filter, since, windowId, appIdentifier });
         }
         if (source === 'android') {
             const adbPath = findAdbPath();
@@ -134,16 +140,42 @@ export async function readLogs(options) {
                 return `Error reading system logs: ${e}`;
             }
         }
+        // Apply level filter
+        if (level) {
+            const levelPrefix = `[ ${level.toUpperCase()} ]`;
+            output = output.split('\n').filter((line) => { return line.includes(levelPrefix); }).join('\n');
+        }
+        // Apply regex filter
         if (filter) {
             try {
                 const regex = new RegExp(filter, 'i');
-                return output.split('\n').filter((line) => { return regex.test(line); }).join('\n');
+                output = output.split('\n').filter((line) => { return regex.test(line); }).join('\n');
             }
             catch (e) {
                 return `Invalid filter regex: ${e}`;
             }
         }
-        return output;
+        // Apply character budget
+        const outputLines = output.split('\n');
+        let budget = maxChars, dropped = 0;
+        const finalLines = [];
+        for (let i = outputLines.length - 1; i >= 0; i--) {
+            let line = outputLines[i];
+            if (line.length > maxCharsPerEntry) {
+                line = line.slice(0, maxCharsPerEntry) + '…[' + (line.length - maxCharsPerEntry) + ' more chars]';
+            }
+            if (line.length > budget) {
+                dropped = i + 1;
+                break;
+            }
+            budget -= line.length + 1; // +1 for newline
+            finalLines.unshift(line);
+        }
+        if (dropped > 0) {
+            finalLines.unshift('[ ' + dropped + ' older entries dropped to fit maxChars=' + maxChars +
+                '. Narrow with level, filter, or since. ]');
+        }
+        return finalLines.join('\n');
     }
     catch (error) {
         return `Error reading logs: ${error}`;