An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
docs(files): the file analyst, its three verdicts, and why a report travels once, inside the message
Shahriared1f25bd6a0d
diff --git a/README.md b/README.mdindex 59784af..fb16977 100644--- a/README.md+++ b/README.md@@ -55,6 +55,7 @@ Either way two steps are left, both inside the browser: **Load unpacked** `~/bro- **Keep What It Wrote**: A script that worked can be kept as a tool of your own, named after the site it belongs to (`youtube.com:watch:darken-page-except-video-player`) and run later by typing `/`. The code stays in the browser; no MCP client can reach it- **Voice, Text, or Demonstration**: Dictate in the side panel, type anywhere, or record yourself doing a job once and later say "do it like last time"- **Point at What You Mean (A-Eye)**: Press the lens, hover the page, click the thing — the element and its content ride along with your next message, and the agent can hand the lens back when *it* needs you to pick+- **Hand It a File**: Drop a CSV, a log or — on Claude Code — a PDF or a screenshot on the panel, and a separate, short-lived session of your agent reads it and writes a report into that conversation. An archive, a program or anything over 10 MB is turned away with the reason before any agent starts- **Teach It a Site Once**: Point it at a site and it explores and writes reusable notes, so every later session already knows its way around- **Instant Commands**: "Go back", "scroll to the top", "open github.com" run in the browser in milliseconds instead of becoming an agent round trip- **Guardrails, Not Vibes**: A declarative policy gates consequential actions, confines each run to the sites it is about, and marks every byte of page text as untrusted data — tunable per rule from a Settings tab, with nothing overridden until you say sodiff --git a/docs/guide/features/files.md b/docs/guide/features/files.mdindex 7586d6c..b5c9554 100644--- a/docs/guide/features/files.md+++ b/docs/guide/features/files.md@@ -7,17 +7,59 @@ Getting a file into a page, and getting one back out.## Files you hand itAttach a file in the side panel — press **Attach a file** on the composer, or **drop one anywhere on-the panel**, which takes several at once. Browsentic reads each **once, at attach time**, and keeps-notes about what it is. Anything over 10 MB is refused.+the panel**, which takes several at once. The file belongs to **the conversation in that tab**: its+chip shows there and nowhere else, and only that conversation's agent hears about it.-From then on the agent sees those notes — never your filesystem — plus two tools:+Each file gets its own **file analyst** — a separate, one-shot session of the agent you picked,+started the moment you attach, with no browser and nothing to open but that one file. It writes a+report and ends: the process is stopped as soon as the report is in, its copy of the file is+deleted, and Claude Code and Codex are told not to keep the session.++What it reads:++| Kind | Up to | On |+| --- | --- | --- |+| Text — CSV, JSON, Markdown, logs, code, anything in UTF-8 | 5 MB | every agent |+| PDF | 10 MB | Claude Code |+| Images — PNG, JPEG, GIF, WebP | 5 MB | Claude Code |++The bytes decide the kind, not the name: a PNG called `notes.txt` is read as an image. Anything else+— a ZIP archive, which Word, Excel and PowerPoint files are too, a program, audio or video — is+turned away before any agent starts, and so is anything over 10 MB, which the browser does not+even store.++Every file ends with one of three verdicts, and its chip says which:++| Verdict | The chip shows | |+| --- | --- | --- |+| **analyzed** | its summary | Read. The report holds a summary, the file's outline, the specifics worth keeping and terse notes |+| **rejected** | the reason, in amber | Not a file Browsentic reads, or one that would not open — encrypted, corrupted. Trying again changes nothing |+| **failed** | the reason, in red, and **Retry** | The analyst broke — it timed out, or the agent could not start. Retry reads it again |++The report reaches the agent **once**, inside the next message you send in that conversation, so it+becomes part of the agent's own session and every later turn still has it. A rejected or failed+file is reported too, with its reason, so the agent can tell you why it cannot answer from it. The+timeline marks the hand-over:++```+Handed to the agent: expenses.csv — analyzed · backup.zip — rejected (unsupported type)+```++Send while a file is still being read and the turn waits for it, with a `readFile` row on the+timeline. A file attached while a run is going reaches the agent with your next message — a running+agent cannot be given anything new. Switch to another agent, or start a conversation it cannot+resume, and it is given every report again, since it holds none of them.++The agent never sees your filesystem, and never the file itself — only the report, plus two tools:| | || --- | --- |-| `page_listFiles` | Re-read the list, with each file's summary |+| `page_listFiles` | List the stored files, with each one's summary || `page_attachFile` | Put one into an `<input type="file">` on the page |So the agent knows what it is uploading without being able to open anything you did not hand it.+Removing a chip stops its analyst if it is still reading, and a conversation's files are deleted+with it when it leaves history.---diff --git a/docs/internals/agent-runs.md b/docs/internals/agent-runs.mdindex 365e801..0da9037 100644--- a/docs/internals/agent-runs.md+++ b/docs/internals/agent-runs.md@@ -150,7 +150,9 @@ point — see [Guardrails § Spawn containment](guardrails.md#spawn-containment)for that agent, and the file is re-read at spawn time. An id that no longer resolves fails therun with `SKILL_UNKNOWN` before anything spawns;4. optional **fetched data** (a site's own `robots.txt`/`sitemap.xml`, during mapping);-5. optional **attached files** — notes Browsentic made when each file was attached, capped at 8 KB;+5. optional **attached files** — one line for each file whose report this conversation's agent+ already holds, with the id `page_attachFile` takes. The reports themselves travel in the+ message ([below](#the-file-analyst));6. optional **recordings** index, capped at 4 KB;7. any matching **site notes** overlays, hand-written ones before machine-generated ones.@@ -161,6 +163,66 @@ Every untrusted block gets its own framing paragraph re-stating that its content---+## The file analyst++Attaching a file in the panel starts a **file analyst**: a one-shot session of the active agent CLI,+one per file, detached from any run — `FileAnalyses` in+[`file-analyst.ts`](../../src/daemon/agent/file-analyst.ts).++```+panel ──putBytes──► storage.local the bytes, under the file's own key+panel ──attach────► background ──indexFile sessionId = the tab's conversation+ ──analyzeFile──► daemon ──screenFile──► rejected, unread+ └─runAgentJson (task mode, Read only)+ ◄──fileReport── report process stopped, copy deleted, entry dropped+```++1. **Screening, before anything spawns.** `screenFile()` decides the kind from the bytes — `%PDF-`,+ the PNG, JPEG, GIF and WebP signatures, and otherwise UTF-8 with no NUL in the first 64 KB is+ text — never from the name or the browser's MIME type. An empty file, a ZIP or any other binary,+ a file over the store cap (10 MB, which arrives as a size with no bytes) or over its kind's limit+ (text 5 MB, PDF 10 MB, image 5 MB), and a kind the active runner does not list in `Runner.opens`+ all come back `rejected` without an agent being started.+2. **The one-shot.** The file is written to the runner's task workspace at `0600`, named for the+ kind its bytes proved, because an agent picks how to open a file by its extension. The prompt+ frames the file as untrusted data and asks for one JSON object after `=== REPORT ===` — summary,+ outline, facts, notes, coverage — or a `rejected` verdict when the file will not open.+ `validateFileReport()` clamps every field, and an answer that does not parse is `failed`.+3. **Ending it.** `runJson()` takes an `accept` callback: the moment stdout holds an answer it+ accepts, the task settles and the CLI is stopped (SIGTERM, then SIGKILL after 5 s) rather than+ waited out. `finally` deletes the scratch copy and drops the registry entry; the report alone is+ kept for up to two minutes, for a turn sent while it was still being written. Claude Code is run+ with `--no-session-persistence` and Codex with `--ephemeral`, so neither keeps the session; the+ other five have no such flag and keep it in their own history, as they do for titles.+4. **Bounds.** Two analysts run at once and the rest queue. Removing the chip, ending the+ conversation or the browser disconnecting aborts one with `CANCELLED`, which is told apart from+ the 60-second `TIMEOUT`.++Every outcome is a `FileReport` with a verdict: `analyzed`, `rejected` (trying again changes+nothing) or `failed` (it may).++### Handing a report over++A report travels **once**, inside the next instruction of the conversation the file was attached in+— `handOver()` in [`attachments.ts`](../../src/daemon/agent/attachments.ts) — under an+`# Attached files` heading framed as untrusted, ahead of `# The user's message`. That puts it in the+agent CLI's own session history, so every resumed turn still has it, and the system prompt only has+to name the file.++- `AttachedFile.delivered` is the browser's record: the file's `deliveredTo` matches the+ conversation's `agentSessionId`. The background sets it when a run that carried the report — its+ `attachments` event — ends in `done`.+- The daemon has the last word. A turn that is not resuming a session treats every file as fresh,+ so a different agent, or a conversation that could not be resumed, is given every report again.+- A file with no report yet is waited for through `awaitAnalysis()`, with a `browsentic.readFile`+ row on the timeline. One that no analyst is reading any more goes over as `failed`.+- The block is capped at 16 KB. Reports that do not fit stay fresh for the next turn.++A headless CLI takes nothing on stdin once it is running, so a file attached mid-run reaches the+agent with the next message.++---+## Skill routingSkills are markdown with YAML-ish front matter, loaded from three directories, later shadowingdiff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.mdindex 264f499..2c39c2f 100644--- a/docs/internals/guardrails.md+++ b/docs/internals/guardrails.md@@ -397,10 +397,19 @@ one is **visible in the log rather than assumed away**.### Two spawn modes-`run` drives the browser. `task` is a one-shot — summarizing an attached file, turning a raw-recording trace into steps — that must not reach the browser at all, which is asserted by requiring-`{"mcpServers":{}}` (or `mcp_servers={}`, or Grok's `--deny MCPTool`) in its argv. `Read` is deliberately left out of `task`'s-deny list, because some tasks are handed a file in the scratch workspace.+`run` drives the browser. `task` is a one-shot — the file analyst reading an attached file, turning+a raw recording trace into steps — that must not reach the browser at all, which is asserted by+requiring `{"mcpServers":{}}` (or `mcp_servers={}`, or Grok's `--deny MCPTool`) in its argv. `Read`+is deliberately left out of `task`'s deny list, because some tasks are handed a file in the scratch+workspace.++The file analyst adds three things to that. A file is screened before anything spawns, so an+archive, an executable or an oversized file never reaches an agent at all. The one-shot is stopped+the moment its answer is in rather than left to exit, and its copy of the file is deleted. And the+session is not kept where the CLI allows it: Claude Code runs a task with+`--no-session-persistence` and Codex with `--ephemeral`. Antigravity, Mistral Vibe, Grok Build,+Cursor CLI and Qwen Code have no such switch, so a task's session stays in that CLI's own history,+inside the per-mode task workspace it was started in.### Sealing the environmentdiff --git a/docs/internals/state.md b/docs/internals/state.mdindex 73298ae..2ef88c5 100644--- a/docs/internals/state.md+++ b/docs/internals/state.md@@ -41,7 +41,7 @@ re-checking the registry. It therefore behaves like state: it decides which verssurvives deleting both directories above, and it is why a reinstall could land on a months-oldbuild. `browsentic update` replaces it; `browsentic uninstall` deletes it.-## The three exceptions+## The exceptions**Held secrets** never reach disk at all. A credential the sanitizer seals out of a page is kept inthe extension's `browser.storage.session` under `browsentic/secrets`, capped at 64 entries, expiring@@ -49,6 +49,12 @@ after two hours and emptied by the browser on restart. The daemon never receives**Recordings** stay in the extension's own storage, not on disk. Removing the extension removes them.+**Attached files** stay there too: the bytes under `browsentic:file:<id>`, and the index under+`browsentic:files`, where each entry records the conversation it belongs to, the file analyst's+report and the agent session that report was handed to. A conversation's files are deleted when it+leaves history. The daemon holds a copy only while the analyst reads it, in the agent's task+workspace at `0600`, and deletes it when the report is in.+**Tab sessions** live in `browser.storage.session` under `browsentic/tabSessions`, so they are gonewhen the browser closes. So do **diagnostics buffers** (`browsentic/diagnostics`), monitors andtimers — none of what a page reported about itself outlives the browser that reported it.diff --git a/docs/reference/errors.md b/docs/reference/errors.mdindex 26d0032..685f7f8 100644--- a/docs/reference/errors.md+++ b/docs/reference/errors.md@@ -101,6 +101,22 @@ refuses it again.| `DOWNLOAD_MISSING` | Daemon | It was captured but is no longer on disk — swept, or deleted. Capture it again || `DOWNLOAD_SAVE_FAILED` | Daemon | The file could not be moved into the download folder. The message carries the reason |+## Attached files++These are not tool errors. They are the reason on a file analyst's report: shown on the file's chip,+and handed to the agent with the file so it can say why it cannot answer from it.++| Code | Verdict | Meaning and next move |+| --- | --- | --- |+| `UNSUPPORTED_TYPE` | rejected | Not text, a PDF or an image — an archive, an Office file, a program — or a PDF or image the active agent cannot open. The message names the agents that can |+| `FILE_TOO_LARGE` | rejected | Over 10 MB, or over its kind's limit: text 5 MB, PDF 10 MB, image 5 MB |+| `EMPTY` | rejected | The file has no bytes |+| `UNREADABLE` | rejected | The analyst opened it and could not read it — encrypted, password-protected or corrupted |+| `TIMEOUT` | failed | The analyst took longer than 60 seconds. **Retry** on the chip reads it again |+| `CANCELLED` | failed | The file was removed, its conversation ended, or the browser disconnected while it was being read |+| `FILE_NOT_FOUND` | failed | The browser no longer holds the file's bytes. Attach it again |+| `AGENT_FAILED` | failed | The agent could not start, or returned something that was not a report. The message says which |+---## See also