ai-browser 0.2.4 → 0.3.0

package/README.md

@@ -84,6 +84,13 @@ Notes:
 - This server currently exposes legacy HTTP+SSE MCP transport (`/mcp/sse` + `/mcp/message`).
 - The message endpoint is `POST /mcp/message?sessionId=...` and is primarily for transport internals.
 
+### 4.1 MCP AI Consumer Guide
+
+For AI-oriented consumption rules (`nextActions`, `hasMore/nextCursor`, `topIssues`, detail levels), see:
+- `docs/18-mcp-ai-consumer-guide.md`
+- `docs/19-mcp-ai-readability-roadmap.md` (P0-P2 roadmap and execution checklist)
+- benchmark command: `npm run baseline:v1` (includes `aiFieldCoverageRate` / `invalidToolCallRate`)
+
 ### 5. Use as a library
 
 ```typescript
@@ -138,12 +145,35 @@ import {
 
 ## MCP Tools
 
-The server currently exposes **35 MCP tools**:
+The server currently exposes **38 MCP tools**:
 - **28 browser primitive tools** (navigation, interaction, tabs, logs, uploads, etc.)
+- **3 composite tools** (multi-step operations in one call)
 - **7 task-runtime tools** (template execution, run tracking, artifacts)
 
 Most browser tools accept an optional `sessionId` — omitting it auto-creates/reuses a default session.
 
+AI-oriented tool responses now include additive helper fields on key tools:
+- `aiSchemaVersion`: schema version for AI helper payload
+- `aiDetailLevel`: applied detail level (`brief` / `normal` / `full`)
+- `aiSummary`: short status sentence for fast decision-making
+- `aiMarkdown`: compact, sectioned markdown with high-signal details
+- `aiHints`: suggested next actions (text)
+- `nextActions`: structured next-step suggestions (`tool`, `args`, `reason`)
+- `deltaSummary`: polling-oriented change summary (`key`, `changes`)
+- `schemaRepairGuidance`: repair-oriented hints for schema verification failures
+
+List-like responses are also normalized with:
+- `hasMore` + `nextCursor` for continuation semantics
+- `topIssues` on log-oriented tools (network/console) for quick fault triage
+
+These fields are additive and backward-compatible; existing JSON fields are unchanged.
+
+You can control verbosity via environment variable `AI_MARKDOWN_DETAIL_LEVEL=brief|normal|full` (default: `normal`).
+
+Optional adaptive policy (prototype): `AI_MARKDOWN_ADAPTIVE_POLICY=1`
+- For polling-heavy tools, detail can auto-shift to `brief`
+- On terminal failure states, detail can auto-escalate to `full`
+
 ### Session Management
 
 | Tool | Description |
@@ -207,6 +237,14 @@ Most browser tools accept an optional `sessionId` — omitting it auto-creates/r
 | `upload_file` | Upload a file to a file input element (**local mode only**) |
 | `get_downloads` | Get downloaded files list |
 
+### Composite Tools (Multi-Step Operations)
+
+| Tool | Description |
+|------|-------------|
+| `fill_form` | Fill multiple form fields and optionally submit in one call (`fields: [{ element_id, value }]`, optional `submit`) |
+| `click_and_wait` | Click an element then wait for stable/navigation/selector (`element_id` + `waitFor: 'stable'\|'navigation'\|'selector'`) |
+| `navigate_and_extract` | Navigate to URL and extract content in one call (`url` + `extract: 'content'\|'elements'\|'both'`) |
+
 ### Task Runtime (Non-LLM Templates)
 
 | Tool | Description |
@@ -335,6 +373,7 @@ npm run build       # Build TypeScript
 npm test            # Run tests
 npm run test:run    # Run tests once
 npm run baseline:v1 # Collect v1 baseline report
+npm run benchmark:v1:expanded # Run expanded readability scenarios (P2 prototype)
 npm run stress:v1   # Run 100-task stress report
 ```
 

package/dist/agent/agent-loop.d.ts

@@ -2,34 +2,58 @@ import { EventEmitter } from 'node:events';
 import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import type { AgentRunResult } from './types.js';
+import type { KnowledgeCardStore } from '../memory/KnowledgeCardStore.js';
 export declare class BrowsingAgent extends EventEmitter {
     private openai;
     private mcpClient;
     private state;
-    private messages;
+    private conversation;
     private model;
     private maxIterations;
     private initialMessages;
     private tools;
-    private recentToolCalls;
+    private toolTracker;
+    private tokenTracker;
+    private pageStateCache;
+    private progressEstimator;
+    private subGoals;
+    private knowledgeStore;
     private stepWarningInjected;
     private pendingInputResolve;
     private pendingInputRequestId;
+    private _askHumanTimer;
+    private recalledDomains;
+    private taskText;
     constructor(options: {
         apiKey?: string;
         baseURL?: string;
         model?: string;
         mcpClient: Client;
         maxIterations?: number;
+        timeout?: number;
         initialMessages?: ChatCompletionMessageParam[];
+        subGoals?: string[];
+        knowledgeStore?: KnowledgeCardStore;
     });
     get sessionId(): string;
     resolveInput(requestId: string, response: Record<string, string>): boolean;
     private emitEvent;
     private discoverTools;
+    private _running;
     run(task: string): Promise<AgentRunResult>;
+    private _run;
     private loop;
     private executeToolCalls;
+    /**
+     * Ask LLM to select relevant site memories from the index.
+     * Returns cards for domains the LLM considers useful for the task (max 3).
+     */
+    private selectMemories;
+    /**
+     * Find the best knowledge card for a domain, checking normalized domain,
+     * full hostname, and subdomain variants in the index.
+     */
+    private findBestCard;
     cleanup(): Promise<void>;
 }
 //# sourceMappingURL=agent-loop.d.ts.map

package/dist/agent/agent-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../../src/agent/agent-loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,0BAA0B,EAAsB,MAAM,sCAAsC,CAAC;AAC3G,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGxE,OAAO,KAAK,EAAc,cAAc,EAA0B,MAAM,YAAY,CAAC;AAgDrF,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,eAAe,CAAgB;IACvC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,mBAAmB,CAA6D;IACxF,OAAO,CAAC,qBAAqB,CAAuB;gBAExC,OAAO,EAAE;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,eAAe,CAAC,EAAE,0BAA0B,EAAE,CAAC;KAChD;IAmBD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO;IAe1E,OAAO,CAAC,SAAS;YAIH,aAAa;IA2DrB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;YA8ClC,IAAI;YAoEJ,gBAAgB;IA6IxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAa/B"}
+{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../../src/agent/agent-loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,0BAA0B,EAAsB,MAAM,sCAAsC,CAAC;AAC3G,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGxE,OAAO,KAAK,EAAc,cAAc,EAA0B,MAAM,YAAY,CAAC;AASrF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAM1E,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,mBAAmB,CAA6D;IACxF,OAAO,CAAC,qBAAqB,CAAuB;IACpD,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAM;gBAEV,OAAO,EAAE;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,eAAe,CAAC,EAAE,0BAA0B,EAAE,CAAC;QAC/C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,cAAc,CAAC,EAAE,kBAAkB,CAAC;KACrC;IA0BD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO;IAe1E,OAAO,CAAC,SAAS;YAIH,aAAa;IA4D3B,OAAO,CAAC,QAAQ,CAAS;IAEnB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;YAYlC,IAAI;YAwGJ,IAAI;YAsFJ,gBAAgB;IAmP9B;;;OAGG;YACW,cAAc;IAmE5B;;;OAGG;IACH,OAAO,CAAC,YAAY;IA2Cd,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAiB/B"}