trusted-user-agent 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +232 -2
  3. package/dist/acp/agent.js +719 -0
  4. package/dist/acp/agents/connection.js +298 -0
  5. package/dist/acp/agents/manager.js +363 -0
  6. package/dist/acp/agents/registry.js +201 -0
  7. package/dist/acp/agents/relay-session.js +371 -0
  8. package/dist/acp/agents/session-index.js +102 -0
  9. package/dist/acp/backend.js +2 -0
  10. package/dist/acp/config-options.js +26 -0
  11. package/dist/acp/mock-backend.js +277 -0
  12. package/dist/acp/sdk-backend.js +495 -0
  13. package/dist/browser/mcp-acp-client.js +81 -0
  14. package/dist/browser/provider.js +1049 -0
  15. package/dist/browser/schemas.js +221 -0
  16. package/dist/capability-registry.js +92 -0
  17. package/dist/client-heartbeat.js +118 -0
  18. package/dist/compose/schemas.js +90 -0
  19. package/dist/contacts/schemas.js +26 -0
  20. package/dist/installer/cli.js +70 -0
  21. package/dist/installer/common.js +93 -0
  22. package/dist/installer/index.js +366 -0
  23. package/dist/installer/mcp-clients.js +555 -0
  24. package/dist/installer/mcp.js +166 -0
  25. package/dist/installer/platforms.js +277 -0
  26. package/dist/logger.js +54 -0
  27. package/dist/mail/schemas.js +98 -0
  28. package/dist/mutation/schemas.js +31 -0
  29. package/dist/native-host/broker-ipc.js +344 -0
  30. package/dist/native-host/framing.js +76 -0
  31. package/dist/native-host/main.js +545 -0
  32. package/dist/native-host/mcp-server.js +333 -0
  33. package/dist/native-host/mcp-stdio-bridge.js +184 -0
  34. package/dist/native-host/mcp-stdio-main.js +13 -0
  35. package/dist/native-host/relay.js +84 -0
  36. package/dist/native-host/skills-startup.js +167 -0
  37. package/dist/native-host/transport.js +248 -0
  38. package/dist/permission-store.js +207 -0
  39. package/dist/repl/fs-sandbox.js +187 -0
  40. package/dist/repl/provider.js +252 -0
  41. package/dist/repl/runtime.js +436 -0
  42. package/dist/repl/types.js +10 -0
  43. package/dist/repl/worker.js +731 -0
  44. package/dist/skills/extension.js +99 -0
  45. package/dist/skills/grants-file.js +145 -0
  46. package/dist/skills/isolated-runner.js +259 -0
  47. package/dist/skills/mock-session-factory.js +49 -0
  48. package/dist/skills/package-roots.js +25 -0
  49. package/dist/skills/pi-bridge.js +8 -0
  50. package/dist/skills/pi-integration.js +110 -0
  51. package/dist/skills/planner.js +128 -0
  52. package/dist/skills/registry.js +104 -0
  53. package/dist/skills/skills-protocol.js +253 -0
  54. package/dist/skills/skills-service.js +195 -0
  55. package/dist/tool-bridge.js +8 -0
  56. package/dist/workspace.js +70 -0
  57. package/extensions/pi-browser-tools.ts +65 -0
  58. package/extensions/pi-browser.ts +60 -0
  59. package/extensions/pi-skills.ts +14 -0
  60. package/native/pi-agent-host +2 -0
  61. package/native/pi-browser-host +5 -0
  62. package/native/pi-browser-host.cmd +3 -0
  63. package/node_modules/@pi-browser/protocol/.bundled-by-trusted-user-agent +0 -0
  64. package/node_modules/@pi-browser/protocol/dist/acp.d.ts +10 -0
  65. package/node_modules/@pi-browser/protocol/dist/acp.js +9 -0
  66. package/node_modules/@pi-browser/protocol/dist/agents.d.ts +51 -0
  67. package/node_modules/@pi-browser/protocol/dist/agents.js +44 -0
  68. package/node_modules/@pi-browser/protocol/dist/browser-tools.d.ts +33 -0
  69. package/node_modules/@pi-browser/protocol/dist/browser-tools.js +478 -0
  70. package/node_modules/@pi-browser/protocol/dist/callers.d.ts +123 -0
  71. package/node_modules/@pi-browser/protocol/dist/callers.js +58 -0
  72. package/node_modules/@pi-browser/protocol/dist/compose-tools.d.ts +30 -0
  73. package/node_modules/@pi-browser/protocol/dist/compose-tools.js +175 -0
  74. package/node_modules/@pi-browser/protocol/dist/contacts-tools.d.ts +23 -0
  75. package/node_modules/@pi-browser/protocol/dist/contacts-tools.js +63 -0
  76. package/node_modules/@pi-browser/protocol/dist/control-tools.d.ts +32 -0
  77. package/node_modules/@pi-browser/protocol/dist/control-tools.js +201 -0
  78. package/node_modules/@pi-browser/protocol/dist/errors.d.ts +63 -0
  79. package/node_modules/@pi-browser/protocol/dist/errors.js +109 -0
  80. package/node_modules/@pi-browser/protocol/dist/index.d.ts +17 -0
  81. package/node_modules/@pi-browser/protocol/dist/index.js +17 -0
  82. package/node_modules/@pi-browser/protocol/dist/integration.d.ts +414 -0
  83. package/node_modules/@pi-browser/protocol/dist/integration.js +270 -0
  84. package/node_modules/@pi-browser/protocol/dist/jsonrpc.d.ts +33 -0
  85. package/node_modules/@pi-browser/protocol/dist/jsonrpc.js +31 -0
  86. package/node_modules/@pi-browser/protocol/dist/mail-mutation-tools.d.ts +27 -0
  87. package/node_modules/@pi-browser/protocol/dist/mail-mutation-tools.js +88 -0
  88. package/node_modules/@pi-browser/protocol/dist/mail-tools.d.ts +133 -0
  89. package/node_modules/@pi-browser/protocol/dist/mail-tools.js +245 -0
  90. package/node_modules/@pi-browser/protocol/dist/permission.d.ts +113 -0
  91. package/node_modules/@pi-browser/protocol/dist/permission.js +257 -0
  92. package/node_modules/@pi-browser/protocol/dist/skills.d.ts +304 -0
  93. package/node_modules/@pi-browser/protocol/dist/skills.js +473 -0
  94. package/node_modules/@pi-browser/protocol/dist/tool-capabilities.d.ts +18 -0
  95. package/node_modules/@pi-browser/protocol/dist/tool-capabilities.js +52 -0
  96. package/node_modules/@pi-browser/protocol/dist/transport.d.ts +17 -0
  97. package/node_modules/@pi-browser/protocol/dist/transport.js +17 -0
  98. package/node_modules/@pi-browser/protocol/package.json +14 -0
  99. package/package.json +69 -4
  100. package/skills/browser-walk/SKILL.md +98 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mathieu Gosbee
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,233 @@
1
- # Temporary Holding Version
1
+ # trusted-user-agent
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Let AI agents use **Firefox** and **Thunderbird**, with your approval.
4
+
5
+ `trusted-user-agent` is the host half of
6
+ [Pi Browser Agent](https://github.com/matbeedotcom/pi-agent-firefox). The add-ons run inside
7
+ your browser and mail client. This package runs on your machine and connects them to agents:
8
+
9
+ - **Any MCP client** (Claude Code, Codex, Cursor, Gemini CLI, VS Code, pi) gets the
10
+ `pi-browser` MCP server. It reads and drives a browser tab, and reads, searches, files and
11
+ drafts mail, while Firefox or Thunderbird is running.
12
+ - **The add-ons' own chat** (Firefox sidebar, Thunderbird Pi Space and pane) talks to an
13
+ embedded [pi](https://pi.dev) agent through this host over the Agent Client Protocol (ACP),
14
+ or, if you pick it for a session, to **Claude Code**, **Codex** or another ACP agent, with the
15
+ browser and mail tools at hand.
16
+
17
+ It installs the `com.matbee.agent` Native Messaging host, which both add-ons share, and gives
18
+ you the `trusted-ua` command to set it up.
19
+
20
+ ## Requirements
21
+
22
+ - **Node.js 22 or newer**
23
+ - **Firefox** with the Pi Browser add-on and/or **Thunderbird** with the Pi Thunderbird add-on
24
+ (both are on the [releases page](https://github.com/matbeedotcom/pi-agent-firefox/releases))
25
+ - Linux, macOS or Windows
26
+
27
+ ## Quick start
28
+
29
+ ```sh
30
+ npm i -g trusted-user-agent
31
+ trusted-ua install # register the native host for Firefox and Thunderbird
32
+ trusted-ua mcp install all # add the pi-browser MCP server to every MCP client found
33
+ trusted-ua doctor # check the host and whether an add-on has connected
34
+ ```
35
+
36
+ Then install the add-ons:
37
+
38
+ - **Firefox:** download `pi-browser-firefox-<version>.xpi` from the
39
+ [latest release](https://github.com/matbeedotcom/pi-agent-firefox/releases/latest) and open it
40
+ in Firefox (it is signed).
41
+ - **Thunderbird:** download `pi-thunderbird-<version>.xpi`, then go to Add-ons and Themes → ⚙ →
42
+ *Install Add-on From File…*.
43
+
44
+ The add-ons find the host by themselves within about 10 seconds. You don't need to restart
45
+ anything. If you install the add-on first, it shows a *Connect* screen until the host is there.
46
+
47
+ > Install globally. `trusted-ua install` refuses to run from a temporary location (an `npx`
48
+ > cache or the temp directory), because the registration would break when npm cleans it up.
49
+
50
+ ## Using the tools from your agent
51
+
52
+ After `trusted-ua mcp install <client>`, your agent sees a `pi-browser` MCP server. It starts
53
+ before Firefox or Thunderbird does, and tool calls work while an app with the add-on is running.
54
+
55
+ | Client | Command | Where the entry goes |
56
+ |--------|---------|----------------------|
57
+ | pi | `trusted-ua mcp install` | `~/.pi/agent/mcp.json` |
58
+ | Claude Code | `trusted-ua mcp install claude` | user scope, through `claude mcp add-json` |
59
+ | Codex | `trusted-ua mcp install codex` | `~/.codex/config.toml` (through `codex mcp add` when available) |
60
+ | Cursor | `trusted-ua mcp install cursor` | `~/.cursor/mcp.json` |
61
+ | Gemini CLI | `trusted-ua mcp install gemini` | `~/.gemini/settings.json` |
62
+ | VS Code | `trusted-ua mcp install vscode` | the user `mcp.json` |
63
+ | Every client found | `trusted-ua mcp install all` | each of the above that is installed |
64
+
65
+ The installer edits only the `pi-browser` entry. It leaves your other servers and settings
66
+ alone, and it never rewrites a config file it can't parse. It reports the error instead.
67
+
68
+ ### What the agent can do
69
+
70
+ | App | Tools |
71
+ |-----|-------|
72
+ | Firefox | `browser_*`: list, open, bind and close tabs; read the page, DOM or accessibility tree; click, type, scroll, wait for selectors; read the console and network requests; navigate and reload; take screenshots. Also `javascript`, a persistent REPL bound to the tab (`page`, `tabs` and a workspace-confined `fs`). |
73
+ | Thunderbird | `mail_*` (accounts, folders, search, read messages and attachments, tag, mark read, move, archive), `compose_*` (prepare new mail, replies and forwards, add attachments), `contacts_*` (list, search, get). |
74
+
75
+ Browser tools act on a tab bound to the agent's connection. The agent calls
76
+ `browser_list_tabs` and then `browser_bind_tab`, or opens a new tab with `browser_open_tab`.
77
+ An agent can't take a tab that one of your Pi chats has bound.
78
+
79
+ Page and mail content reach the agent as untrusted tool data, never as instructions.
80
+
81
+ ### How approval works
82
+
83
+ - **Each MCP connection is its own session.** It has its own approvals and its own
84
+ `javascript` REPL, and it ends when the agent disconnects.
85
+ - **You approve each agent once per app.** The first call from a new agent asks
86
+ *"Allow codex to use Firefox tools?"* with *Allow this time*, *Always allow codex* and
87
+ *Deny*. Firefox and Thunderbird ask separately, so allowing an agent in the browser doesn't
88
+ open your mailbox to it.
89
+ - **Tool calls still ask** as set on the add-on's permissions page (Ask / Deny / Always
90
+ approve), and each prompt names the agent: *"claude-code wants to take a screenshot"*.
91
+ - **Prompts come to you.** They open a small approval window in the app that runs the tool,
92
+ even when the sidebar or Pi Space is closed. **Closing the window denies** whatever is
93
+ waiting. While a prompt waits, the toolbar or Pi Space button shows a badge.
94
+ - **You can turn it off.** In the add-on, go to Pi settings → permissions → *Other apps (MCP)*.
95
+ You can switch external access off there, or revoke agents you allowed or denied.
96
+
97
+ Agent names are what agents report about themselves and are not verified. Any program running
98
+ as your user can reach the host, so the approval is about knowing and consenting. It is not
99
+ a security boundary between programs on your machine.
100
+
101
+ ## Chat with Claude Code or Codex in the add-ons
102
+
103
+ The add-ons' new-session panel has an **Agent** choice: **pi** (the default), **Claude Code**,
104
+ **Codex**, or an ACP agent you add yourself. The last choice is remembered per app, and
105
+ sessions that don't use pi are labelled in the session list.
106
+
107
+ Install the agent's ACP adapter and log in with the agent's own CLI:
108
+
109
+ | Agent | Adapter | Log in |
110
+ |-------|---------|--------|
111
+ | Claude Code | `npm i -g @agentclientprotocol/claude-agent-acp` | run `claude` once and log in |
112
+ | Codex | `npm i -g @agentclientprotocol/codex-acp` | `codex login` |
113
+
114
+ `trusted-ua status` lists which agents are available. Agents that aren't found show disabled in
115
+ the panel, with the missing command.
116
+
117
+ - **Nothing to set up in the agent's config.** Each session gets the `pi-browser` tools tied to
118
+ that sidebar session: its bound tab, its approvals, and prompts in the sidebar or pane. It can
119
+ reach the other app's tools when both apps run.
120
+ - **Two kinds of prompts.** Tool prompts (*"Allow this action?"*) are the add-on's own, as for
121
+ pi. Agent prompts (*"Codex wants to run a command"*, with the command or diff) are the agent's
122
+ own permission requests, with its own options. The add-on never remembers those answers.
123
+ - **One process per agent**, shared by its sessions in both apps. After 15 minutes without
124
+ activity the process stops. The session stays open, and your next message starts the agent
125
+ again and reloads the conversation.
126
+ - The agents work in the session's folder with their own tools and approval rules. New sessions
127
+ default to a fresh folder under `~/.pi/workspaces`.
128
+
129
+ Add agents or change a built-in one in `~/.pi/browser/agents.json` (no restart needed):
130
+
131
+ ```json
132
+ {
133
+ "agents": {
134
+ "claude": { "idleTimeoutMinutes": 30 },
135
+ "my-agent": { "name": "My agent", "command": "my-agent", "args": ["--acp"] },
136
+ "codex": { "disabled": true }
137
+ }
138
+ }
139
+ ```
140
+
141
+ Fields: `name`, `command`, `args`, `env`, `idleTimeoutMinutes` (0 means never stop),
142
+ `loginHint` and `disabled`.
143
+
144
+ ## Firefox and Thunderbird together
145
+
146
+ Both add-ons use the same host. The first app to connect becomes the broker and owns the
147
+ sessions. The second app's host process relays into it over private OS IPC: a `0600` Unix
148
+ socket in `~/.pi/run`, or a per-user named pipe on Windows. Nothing listens on TCP.
149
+
150
+ So one session can use both apps. A chat in the Firefox sidebar can search your mail, and an
151
+ agent connected over MCP can read an email and then reproduce its bug in a tab.
152
+ `trusted-ua status` shows the broker and per-app heartbeats.
153
+
154
+ ## Command reference
155
+
156
+ ```
157
+ trusted-ua [install|status|doctor|uninstall] [firefox|thunderbird|mozilla]
158
+ trusted-ua mcp [install|status|uninstall] [pi|claude|codex|cursor|gemini|vscode|all]
159
+ ```
160
+
161
+ | Command | Effect |
162
+ |---------|--------|
163
+ | `trusted-ua` / `trusted-ua status` | Host registration, add-on heartbeat, broker state, and which chat agents (Claude Code, Codex, ...) are available |
164
+ | `trusted-ua install [app]` | Register (or repair) the native host. `app` defaults to `mozilla`, which means both apps |
165
+ | `trusted-ua doctor [app]` | `status` plus a live probe of the host |
166
+ | `trusted-ua uninstall [app]` | Remove the registration (the package files stay) |
167
+ | `trusted-ua mcp install [client]` | Add or update the `pi-browser` MCP entry (default client: `pi`) |
168
+ | `trusted-ua mcp status [client]` | Report each entry as missing, current or stale (for example after the package moved) |
169
+ | `trusted-ua mcp uninstall [client]` | Remove only the `pi-browser` entry |
170
+
171
+ After upgrading or moving the package, run `trusted-ua install` and
172
+ `trusted-ua mcp install <client>` again. `status` and `mcp status` tell you when an entry is
173
+ stale.
174
+
175
+ ### What `install` writes
176
+
177
+ | Where | What |
178
+ |-------|------|
179
+ | The package's `native/` directory | The host launcher, pinned to the `node` that ran the install |
180
+ | Linux | `~/.mozilla/native-messaging-hosts/com.matbee.agent.json` |
181
+ | macOS | `~/Library/Application Support/Mozilla/NativeMessagingHosts/com.matbee.agent.json` (Firefox) and `~/Library/Mozilla/NativeMessagingHosts/com.matbee.agent.json` (Thunderbird) |
182
+ | Windows | `HKCU\SOFTWARE\Mozilla\NativeMessagingHosts\com.matbee.agent`, pointing at a manifest in the package's `native/` directory |
183
+ | `~/.agents/skills/browser-walk/SKILL.md` | A skill that teaches agents to walk a tab: observe, act, verify, save |
184
+
185
+ ## Using it as a pi package
186
+
187
+ The same package is a [pi](https://pi.dev) package. It adds the `/pi-browser` command, which
188
+ works like `trusted-ua`:
189
+
190
+ ```sh
191
+ pi install git:github.com/matbeedotcom/pi-agent-firefox@v0.4.0
192
+ ```
193
+
194
+ In pi: `/pi-browser install`, `/pi-browser doctor`, `/pi-browser mcp install [client]`.
195
+
196
+ ## Configuration
197
+
198
+ The Pi chat in the add-ons runs on the embedded pi SDK and uses your normal pi setup
199
+ (`~/.pi/agent`: models, API keys, extensions, skills). Approvals the add-ons store live in
200
+ `~/.pi/browser/`, next to `agents.json` (chat agents) and `agent-sessions.json` (the list of
201
+ Claude Code / Codex sessions started from the add-ons).
202
+
203
+ | Variable | Effect |
204
+ |----------|--------|
205
+ | `PI_BROWSER_LOG_FILE` | Host log path. Set it to `off` to disable logging |
206
+ | `PI_BROWSER_LOG_LEVEL` | Host log level |
207
+ | `PI_BROWSER_AGENT_DIR` | pi agent directory for the embedded agent (default: pi's own) |
208
+ | `PI_BROWSER_PREWARM` | `0` turns off the warm-up session the host starts at launch |
209
+
210
+ The host's stdout carries only protocol data. Logs go to stderr and the log file.
211
+
212
+ ## Troubleshooting
213
+
214
+ - **The add-on says it can't find the host.** Run `trusted-ua doctor`. If the host is not
215
+ installed, run `trusted-ua install`. If it reports a stale launcher, the package moved
216
+ (for example after a Node upgrade), so run `install` again.
217
+ - **`doctor` says the add-on heartbeat is stale.** Reload the add-on or restart the app.
218
+ - **The agent's browser calls fail with `BROWSER_NOT_BOUND`.** The agent has to bind a tab
219
+ first (`browser_bind_tab` or `browser_open_tab`).
220
+ - **Nothing happens when the agent calls a tool.** Look for the approval window or the badge
221
+ on the Pi toolbar / Pi Space button.
222
+ - **Claude Code or Codex is greyed out in the new-session panel.** Its ACP adapter isn't on
223
+ your `PATH`. Install it (see above), or set its `command` in `~/.pi/browser/agents.json`.
224
+ - **"Codex needs you to log in".** Log in with the agent's own CLI (`codex login`, or run
225
+ `claude` once), then create the session again.
226
+
227
+ More: [debugging guide](https://github.com/matbeedotcom/pi-agent-firefox/blob/main/docs/DEBUGGING-TOOLS.md),
228
+ [project README](https://github.com/matbeedotcom/pi-agent-firefox#readme),
229
+ [product spec and security invariants](https://github.com/matbeedotcom/pi-agent-firefox/blob/main/PRODUCT.md).
230
+
231
+ ## License
232
+
233
+ MIT