Skip to content

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.

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.md
index 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 so
diff --git a/docs/guide/features/files.md b/docs/guide/features/files.md
index 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 it
Attach 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.md
index 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 the
run 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 routing
Skills are markdown with YAML-ish front matter, loaded from three directories, later shadowing
diff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.md
index 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 environment
diff --git a/docs/internals/state.md b/docs/internals/state.md
index 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 vers
survives deleting both directories above, and it is why a reinstall could land on a months-old
build. `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 in
the 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 gone
when the browser closes. So do **diagnostics buffers** (`browsentic/diagnostics`), monitors and
timers — 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.md
index 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