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
@@ -0,0 +1,270 @@
1
+ export const PI_BROWSER = {
2
+ /** Package name. */
3
+ name: "pi-browser",
4
+ /** Package release version (npm version of trusted-user-agent). */
5
+ version: "0.4.0",
6
+ /**
7
+ * Pi Browser integration protocol version (bump on breaking changes to
8
+ * x-pi-browser/* semantics or integration metadata). v2 = 2026-09-11
9
+ * identity rename (add-on IDs to @matbee.com, host name to com.matbee.agent).
10
+ * v3 = 2026-09-12: x-pi-browser/tool_update — long-running tools (mail_search)
11
+ * stream batches/progress to the host while the original x-pi-browser/tool
12
+ * request is still pending; MailSearchResult gains complete/sortComplete/scanned.
13
+ */
14
+ protocolVersion: 3,
15
+ // 2026-11-20 (v0.3.0, external MCP callers): additive only, so the version
16
+ // stays 3 — add-ons reject any other value, and mixed versions must keep
17
+ // working. New: the `pi-browser/caller` MCP notification (broker socket),
18
+ // `_meta.piBrowser.caller` / `callerApproval` on session/request_permission,
19
+ // the x-pi-browser/permission_withdrawn notification, and caller /
20
+ // externalAccess fields on x-pi-browser/permissions|permission_set|
21
+ // permission_clear. Older peers ignore all of them (see callers.ts).
22
+ // 2026-11-20 (v0.4.0, sidebar ACP agents): additive again — the
23
+ // x-pi-browser/agents request, `_meta.piBrowser.agent` on session/new,
24
+ // listed sessions and relayed permission requests, `parentSession` on
25
+ // `pi-browser/caller`, and the "cancelled" permission_withdrawn reason
26
+ // (see agents.ts). Older peers create and see pi sessions only.
27
+ /**
28
+ * Browser tool schema version (bump when tool schemas change).
29
+ * v2 = 2026-09-12: added browser_evaluate, browser_get_accessibility_tree,
30
+ * browser_get_console, browser_get_network, browser_element_at, browser_navigate;
31
+ * widened browser_get_dom coverage (more element kinds + per-element fields).
32
+ * v3 = 2026-09-12: frame targeting (optional `frame` parameter on the nine
33
+ * content-frame tools), browser_get_dom now traverses open shadow roots and
34
+ * reports iframes/stats; new BROWSER_FRAME_NOT_FOUND error.
35
+ * v4 = 2026-09-12: host-side `javascript` REPL tool (BROWSER-USE-REPL-PLAN.md,
36
+ * option C) — a persistent V8 cell interpreter; `page.*`/`tabs.*` primitives
37
+ * execute the existing browser tools against the session's current tab. The
38
+ * tool is hosted by the native host, not by the add-on (see REPL_TOOLS).
39
+ * v5 = 2026-09-12: REPL add-on deltas — browser_click_at, browser_focus,
40
+ * browser_scroll, browser_type_focused (content-script interaction),
41
+ * browser_open_tab / browser_close_tab / browser_list_tabs (REPL-owned
42
+ * auxiliary tabs, closed at session unbind), and browser_get_accessibility_tree
43
+ * `format: "nodes"` (structured snapshot for page.snapshot()).
44
+ * v6 = 2026-09-12: `javascript` REPL gains an `fs` global — a workspace-
45
+ * scoped filesystem (read/write/append/list/stat/exists/mkdir/rename/
46
+ * unlink/rm) confined to the session's task workspace (lexical + symlink
47
+ * escape rejection); no add-on-side change (host-side realm global).
48
+ * v8 = 2026-09-12: mail_search became incremental — results carry
49
+ * `complete`, `sortComplete`, and `scanned`, and long searches stream
50
+ * partial batches over x-pi-browser/tool_update (protocol v3).
51
+ */
52
+ browserToolVersion: 8,
53
+ /** Stable Firefox Native Messaging host name (manifest `name`). */
54
+ nativeHost: "dev.pi.browser",
55
+ /** Stable Firefox add-on ID (gecko.id). Must match allowed_extensions. */
56
+ extensionId: "pi-agent-firefox@matbee.com",
57
+ };
58
+ /** Valid agent capabilities (for parsing/normalization). */
59
+ export const AGENT_CAPABILITIES = [
60
+ "browser",
61
+ "mail",
62
+ "compose",
63
+ "attachments",
64
+ "contacts",
65
+ "mailModify",
66
+ ];
67
+ /** Agent-level integration identity (application-neutral). */
68
+ export const PI_AGENT = {
69
+ /**
70
+ * Native Messaging host name (manifest `name`), shared by both
71
+ * applications. 2026-09-11: renamed from the `dev.pi.*` placeholders to a
72
+ * name under the project-owned matbee domain.
73
+ */
74
+ nativeHost: "com.matbee.agent",
75
+ /** Legacy host name kept for already-registered Firefox installations. */
76
+ legacyNativeHost: "dev.pi.browser",
77
+ /**
78
+ * Add-on IDs the native host manifest authorizes. `pi-agent-firefox@matbee.com`
79
+ * and `pi-agent-thunderbird@matbee.com` are the production add-on IDs (2026-09-11
80
+ * rename from the `@pi.dev` placeholders to a domain the project owns);
81
+ * `pi-firefox@matbee.com` remains authorized for compatibility.
82
+ */
83
+ authorizedExtensions: ["pi-agent-firefox@matbee.com", "pi-firefox@matbee.com", "pi-agent-thunderbird@matbee.com"],
84
+ /**
85
+ * Agent integration protocol version (bump on breaking _meta.piAgent
86
+ * changes). v2 = 2026-09-11 identity rename.
87
+ */
88
+ protocolVersion: 2,
89
+ };
90
+ export const PI_AGENT_META = {
91
+ version: PI_BROWSER.version,
92
+ protocolVersion: PI_AGENT.protocolVersion,
93
+ capabilities: [],
94
+ };
95
+ /** Filter an arbitrary list down to known capabilities, preserving order. */
96
+ export function normalizeCapabilities(values) {
97
+ if (!Array.isArray(values))
98
+ return [];
99
+ const out = [];
100
+ for (const v of values) {
101
+ if (typeof v === "string" && AGENT_CAPABILITIES.includes(v) && !out.includes(v)) {
102
+ out.push(v);
103
+ }
104
+ }
105
+ return out;
106
+ }
107
+ /**
108
+ * Parse the integration hello from ACP `initialize` params.
109
+ * Returns undefined when absent/malformed (legacy clients); the caller
110
+ * falls back to browser compatibility defaults.
111
+ */
112
+ export function parseAgentHello(params) {
113
+ const meta = params?._meta?.piAgent;
114
+ if (typeof meta !== "object" || meta === null)
115
+ return undefined;
116
+ const m = meta;
117
+ const client = m.client;
118
+ if (typeof client?.application !== "string" || client.application !== "firefox" && client.application !== "thunderbird") {
119
+ return undefined;
120
+ }
121
+ return {
122
+ type: "pi.agent.hello",
123
+ client: {
124
+ application: client.application,
125
+ extensionId: typeof client.extensionId === "string" ? client.extensionId : "",
126
+ version: typeof client.version === "string" ? client.version : "",
127
+ },
128
+ capabilities: normalizeCapabilities(m.capabilities),
129
+ };
130
+ }
131
+ /** Build the `_meta.piAgent` client hello block for ACP `initialize` params. */
132
+ export function buildAgentHelloMeta(hello) {
133
+ return {
134
+ piAgent: {
135
+ type: "pi.agent.hello",
136
+ client: hello.client,
137
+ capabilities: normalizeCapabilities(hello.capabilities),
138
+ },
139
+ };
140
+ }
141
+ /**
142
+ * Broker/relay private IPC (THUNDERBIRD-PLAN.md §26–27).
143
+ *
144
+ * One host process is the broker (owns the ACP agent + Pi sessions); later
145
+ * app connections attach to it as relays over private OS IPC (Unix socket,
146
+ * no localhost TCP). Native Messaging remains the externally visible
147
+ * Mozilla security boundary — the relay only forwards bytes.
148
+ */
149
+ export const PI_BROKER = {
150
+ /** Run directory name under $HOME (0700; env PI_BROWSER_BROKER_DIR overrides). */
151
+ runDir: "run",
152
+ /** Unix socket file name inside the run directory (0600). */
153
+ socketFile: "agent-broker.sock",
154
+ /**
155
+ * MCP server socket file name inside the run directory (0600). Exposes
156
+ * the browser tools as a plain MCP server (JSONL JSON-RPC) so separate
157
+ * pi-subagent child processes — which have no ACP channel and no
158
+ * in-process tool bridge — can reach them over MCP.
159
+ */
160
+ mcpSocketFile: "agent-broker-mcp.sock",
161
+ /** Broker state file name inside the run directory (0600: pid + token). */
162
+ stateFile: "agent-broker.json",
163
+ /** First frame a relay sends after connecting (carries the token). */
164
+ handshake: "pi.broker.handshake",
165
+ /** First frame the broker sends back once the token is accepted. */
166
+ handshakeAck: "pi.broker.handshakeAck",
167
+ /** Broker IPC protocol version (bump on breaking handshake changes). */
168
+ version: 1,
169
+ };
170
+ export const PI_BROWSER_META = {
171
+ version: PI_BROWSER.version,
172
+ protocolVersion: PI_BROWSER.protocolVersion,
173
+ browserToolVersion: PI_BROWSER.browserToolVersion,
174
+ };
175
+ /** Private extension methods (PRODUCT.md §30). Never used for ACP session semantics. */
176
+ export const X_PI_BROWSER = {
177
+ /** Firefox → host: liveness/version probe used by /pi-browser status|doctor. */
178
+ ping: "x-pi-browser/ping",
179
+ /** Host → Firefox: browser tool invocation (legacy compatibility transport). */
180
+ tool: "x-pi-browser/tool",
181
+ /** Firefox → host: browser-side notifications (tab closed/navigated, binding changed). */
182
+ notify: "x-pi-browser/notify",
183
+ /**
184
+ * Host → session-owner client: a tool's approval prompt is being shown in
185
+ * ANOTHER app (cross-app routing). The owner's UI is where the user is
186
+ * watching the session, so it should draw attention to where the prompt
187
+ * actually is (e.g. "approval needed in the mail client"). The owner
188
+ * displays it; it does NOT answer it (the executing client owns the
189
+ * canonical session/request_permission round-trip).
190
+ */
191
+ permission_prompted: "x-pi-browser/permission_prompted",
192
+ /**
193
+ * Client → host: incremental progress for a tool call that is still
194
+ * pending (the x-pi-browser/tool request has not answered yet). The host
195
+ * maps batches onto ACP session/update tool_call_update so the model can
196
+ * see results before the final answer; the final tool response is
197
+ * unchanged, so clients that ignore updates stay compatible.
198
+ * The update never authorizes anything — it only reports results of the
199
+ * already-approved call.
200
+ */
201
+ tool_update: "x-pi-browser/tool_update",
202
+ /**
203
+ * Host → all clients: the set of connected capability providers changed
204
+ * (a peer app connected or disconnected). Carries the current union so
205
+ * each UI can update its "capabilities:" line. Display-only; additive —
206
+ * legacy hosts never send it and clients ignore it when absent.
207
+ */
208
+ capabilities_changed: "x-pi-browser/capabilities_changed",
209
+ /**
210
+ * Client → host: fetch the permission configuration — every approval-
211
+ * gated tool with its persistent "always allow" state. The add-on
212
+ * Configuration page renders from this (PRODUCT.md §55).
213
+ */
214
+ permissions: "x-pi-browser/permissions",
215
+ /**
216
+ * Client → host: set one tool's persistent state (ask | deny | allow)
217
+ * from the Configuration page.
218
+ */
219
+ permission_set: "x-pi-browser/permission_set",
220
+ /**
221
+ * Client → host: clear the persistent "always allow" state of one tool
222
+ * (or of every tool when `tool` is omitted).
223
+ */
224
+ permission_clear: "x-pi-browser/permission_clear",
225
+ /**
226
+ * Client → host: compile a page plan for a verified source identity
227
+ * (skills-runtime-design.md §2, §7). The source identity is supplied by
228
+ * the addon coordinator, never a page payload.
229
+ */
230
+ skills_plan: "x-pi-browser/skills_plan",
231
+ /**
232
+ * Client → host: submit a verified skill event. Responds with an ack:
233
+ * accepted (jobs launched), no-match, stale-plan (re-plan), unavailable,
234
+ * or duplicate (coordinator redelivery).
235
+ */
236
+ skills_event: "x-pi-browser/skills_event",
237
+ /** Client → host: cancel pending skill work for one interaction. */
238
+ skills_cancel: "x-pi-browser/skills_cancel",
239
+ /** Client → host: probe the skill runtime (queue, live plans, stats). */
240
+ skills_status: "x-pi-browser/skills_status",
241
+ /**
242
+ * Host → client: resolve a contextRef against the coordinator's bounded
243
+ * snapshot store (privacy by request: only the requested fields return).
244
+ */
245
+ skills_context: "x-pi-browser/skills_context",
246
+ /**
247
+ * Host → client: deliver a skill job outcome for a submitted event. The
248
+ * coordinator routes it to the gate/UI and acks delivery; the request ID
249
+ * makes delivery explicit (design §7: results require request IDs).
250
+ */
251
+ skills_result: "x-pi-browser/skills_result",
252
+ /**
253
+ * Client → host: the agents a new session can run on (built-in pi plus
254
+ * configured external ACP agents), with availability. See agents.ts.
255
+ */
256
+ agents: "x-pi-browser/agents",
257
+ };
258
+ /** Human-facing name for an application (permission banners, prompts). */
259
+ export function applicationDisplayName(app) {
260
+ return app === "thunderbird" ? "Thunderbird (mail)" : "Firefox (browser)";
261
+ }
262
+ /** MCP protocol version spoken inside mcp/message (MCP-over-ACP). */
263
+ export const MCP_PROTOCOL_VERSION = "2025-06-18";
264
+ /** Default per-tool deadline the host enforces when Firefox does not answer. */
265
+ export const BROWSER_TOOL_TIMEOUT_MS = 30_000;
266
+ /** Long deadline for screenshot calls (capture can be slow on busy pages). */
267
+ export const BROWSER_SCREENSHOT_TIMEOUT_MS = 60_000;
268
+ /** Long deadline for file downloads (images/videos can be several MB). */
269
+ export const BROWSER_DOWNLOAD_TIMEOUT_MS = 120_000;
270
+ //# sourceMappingURL=integration.js.map
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Minimal JSON-RPC 2.0 envelope types shared by both sides of the
3
+ * Native Messaging link. The native host frames these objects with
4
+ * Firefox's 4-byte little-endian length prefix; the browser runtime
5
+ * handles framing on the add-on side.
6
+ */
7
+ export interface JsonRpcRequest {
8
+ jsonrpc: "2.0";
9
+ id: number;
10
+ method: string;
11
+ params?: unknown;
12
+ }
13
+ export interface JsonRpcErrorObject {
14
+ code: number;
15
+ message: string;
16
+ data?: unknown;
17
+ }
18
+ export interface JsonRpcResponse {
19
+ jsonrpc: "2.0";
20
+ id: number;
21
+ result?: unknown;
22
+ error?: JsonRpcErrorObject;
23
+ }
24
+ export interface JsonRpcNotification {
25
+ jsonrpc: "2.0";
26
+ method: string;
27
+ params?: unknown;
28
+ }
29
+ export type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
30
+ export declare function isJsonRpcRequest(msg: unknown): msg is JsonRpcRequest;
31
+ export declare function isJsonRpcResponse(msg: unknown): msg is JsonRpcResponse;
32
+ export declare function isJsonRpcNotification(msg: unknown): msg is JsonRpcNotification;
33
+ //# sourceMappingURL=jsonrpc.d.ts.map
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Minimal JSON-RPC 2.0 envelope types shared by both sides of the
3
+ * Native Messaging link. The native host frames these objects with
4
+ * Firefox's 4-byte little-endian length prefix; the browser runtime
5
+ * handles framing on the add-on side.
6
+ */
7
+ export function isJsonRpcRequest(msg) {
8
+ if (typeof msg !== "object" || msg === null)
9
+ return false;
10
+ const m = msg;
11
+ return (m.jsonrpc === "2.0" &&
12
+ typeof m.id === "number" &&
13
+ typeof m.method === "string" &&
14
+ m.result === undefined &&
15
+ m.error === undefined);
16
+ }
17
+ export function isJsonRpcResponse(msg) {
18
+ if (typeof msg !== "object" || msg === null)
19
+ return false;
20
+ const m = msg;
21
+ return (m.jsonrpc === "2.0" &&
22
+ typeof m.id === "number" &&
23
+ (m.result !== undefined || m.error !== undefined));
24
+ }
25
+ export function isJsonRpcNotification(msg) {
26
+ if (typeof msg !== "object" || msg === null)
27
+ return false;
28
+ const m = msg;
29
+ return m.jsonrpc === "2.0" && m.id === undefined && typeof m.method === "string";
30
+ }
31
+ //# sourceMappingURL=jsonrpc.js.map
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Thunderbird mail-ORGANIZATION tool definitions (THUNDERBIRD-PLAN.md §39, T4).
3
+ *
4
+ * These are the mutation surface: mark read/unread, apply tags, archive, and move
5
+ * selected messages. They are deliberately NON-deleting: there is no delete, no
6
+ * permanent-delete, no messagesModifyPermanent. Archive and move are reversible.
7
+ *
8
+ * Safety model (plan §39 + goal constraints):
9
+ * - Every tool acts ONLY on explicitly-selected message ids (from the current
10
+ * context / selection), never bulk or global.
11
+ * - Numeric messageIds are transient (valid within the session).
12
+ * - Gated on the `mailModify` capability (distinct from read-only `mail`); the
13
+ * add-on declares messagesUpdate / messagesMove / messagesTags (NOT messagesDelete).
14
+ */
15
+ export interface MailMutationToolDef {
16
+ name: string;
17
+ description: string;
18
+ inputSchema: Record<string, unknown>;
19
+ /** All mutation tools are non-read-only. */
20
+ readOnly: boolean;
21
+ }
22
+ export declare const MAIL_MUTATION_TOOLS: readonly MailMutationToolDef[];
23
+ export declare function getMailMutationTool(name: string): MailMutationToolDef | undefined;
24
+ export declare function isMailMutationTool(name: string): boolean;
25
+ export declare const MAIL_MUTATION_TOOL_NAMES: readonly string[];
26
+ export declare const MAIL_MUTATION_TOOL_TIMEOUT_MS = 30000;
27
+ //# sourceMappingURL=mail-mutation-tools.d.ts.map
@@ -0,0 +1,88 @@
1
+ /**
2
+ * Thunderbird mail-ORGANIZATION tool definitions (THUNDERBIRD-PLAN.md §39, T4).
3
+ *
4
+ * These are the mutation surface: mark read/unread, apply tags, archive, and move
5
+ * selected messages. They are deliberately NON-deleting: there is no delete, no
6
+ * permanent-delete, no messagesModifyPermanent. Archive and move are reversible.
7
+ *
8
+ * Safety model (plan §39 + goal constraints):
9
+ * - Every tool acts ONLY on explicitly-selected message ids (from the current
10
+ * context / selection), never bulk or global.
11
+ * - Numeric messageIds are transient (valid within the session).
12
+ * - Gated on the `mailModify` capability (distinct from read-only `mail`); the
13
+ * add-on declares messagesUpdate / messagesMove / messagesTags (NOT messagesDelete).
14
+ */
15
+ const OBJECT_SCHEMA_BASE = {
16
+ type: "object",
17
+ additionalProperties: false,
18
+ };
19
+ const messageIdsProp = {
20
+ type: "array",
21
+ items: { type: "number" },
22
+ description: "The Thunderbird numeric message ids to act on (from the current context or selection). Transient: valid only within the current session.",
23
+ };
24
+ export const MAIL_MUTATION_TOOLS = [
25
+ {
26
+ name: "mail_mark_read",
27
+ description: "Mark explicitly-selected messages as read or unread (default read).",
28
+ inputSchema: {
29
+ ...OBJECT_SCHEMA_BASE,
30
+ properties: {
31
+ messageIds: messageIdsProp,
32
+ read: { type: "boolean", description: "Set read (true, default) or unread (false)." },
33
+ },
34
+ required: ["messageIds"],
35
+ },
36
+ readOnly: false,
37
+ },
38
+ {
39
+ name: "mail_set_tags",
40
+ description: "Apply tags to explicitly-selected messages (e.g. Finance, Work). Additive by default: new tags are added to each message's existing tags; pass additive=false to replace them.",
41
+ inputSchema: {
42
+ ...OBJECT_SCHEMA_BASE,
43
+ properties: {
44
+ messageIds: messageIdsProp,
45
+ tags: {
46
+ type: "array",
47
+ items: { type: "string" },
48
+ description: 'Tag names to apply, e.g. ["Finance"].',
49
+ },
50
+ additive: { type: "boolean", description: "Add to existing tags (true, default) or replace them (false)." },
51
+ },
52
+ required: ["messageIds", "tags"],
53
+ },
54
+ readOnly: false,
55
+ },
56
+ {
57
+ name: "mail_archive",
58
+ description: "Archive the explicitly-selected messages (moves them to the account's Archive folder). Reversible — not permanent deletion.",
59
+ inputSchema: {
60
+ ...OBJECT_SCHEMA_BASE,
61
+ properties: { messageIds: messageIdsProp },
62
+ required: ["messageIds"],
63
+ },
64
+ readOnly: false,
65
+ },
66
+ {
67
+ name: "mail_move",
68
+ description: "Move the explicitly-selected messages to a folder (by folder id from mail_list_folders). Reversible — not permanent deletion.",
69
+ inputSchema: {
70
+ ...OBJECT_SCHEMA_BASE,
71
+ properties: {
72
+ messageIds: messageIdsProp,
73
+ folderId: { type: "string", description: "Destination folder id (from mail_list_folders)." },
74
+ },
75
+ required: ["messageIds", "folderId"],
76
+ },
77
+ readOnly: false,
78
+ },
79
+ ];
80
+ export function getMailMutationTool(name) {
81
+ return MAIL_MUTATION_TOOLS.find((t) => t.name === name);
82
+ }
83
+ export function isMailMutationTool(name) {
84
+ return MAIL_MUTATION_TOOLS.some((t) => t.name === name);
85
+ }
86
+ export const MAIL_MUTATION_TOOL_NAMES = MAIL_MUTATION_TOOLS.map((t) => t.name);
87
+ export const MAIL_MUTATION_TOOL_TIMEOUT_MS = 30_000;
88
+ //# sourceMappingURL=mail-mutation-tools.js.map
@@ -0,0 +1,133 @@
1
+ /**
2
+ * Read-only Thunderbird mail tool definitions (THUNDERBIRD-PLAN §9–14).
3
+ *
4
+ * These schemas are transport-independent: the same names, arguments, and
5
+ * results are used whether tools are invoked over the private
6
+ * x-pi-browser/tool compatibility transport or over MCP. The Thunderbird
7
+ * side implements the tools; the Pi side registers them as agent tools.
8
+ *
9
+ * Safety model (plan §8, §14, §21):
10
+ * - Every tool here is read-only. No send, delete, move, or compose exists.
11
+ * - Numeric `messageId` is transient (it does not survive a restart or a
12
+ * folder move). `headerMessageId` is the durable identifier; prefer it.
13
+ * - Email bodies/headers/attachments are UNTRUSTED content: they are only
14
+ * ever returned as tool output, never merged into a user prompt.
15
+ */
16
+ export interface MailToolDef {
17
+ name: string;
18
+ description: string;
19
+ /** JSON Schema (draft-07 compatible) for the tool arguments. */
20
+ inputSchema: Record<string, unknown>;
21
+ /** True for every T2 tool — none of them mutate state. */
22
+ readOnly: boolean;
23
+ }
24
+ export declare const MAIL_TOOLS: readonly MailToolDef[];
25
+ export declare function getMailTool(name: string): MailToolDef | undefined;
26
+ export declare function isMailTool(name: string): boolean;
27
+ export declare const MAIL_TOOL_NAMES: readonly string[];
28
+ /**
29
+ * Default per-mail-tool deadline. Full-text searches may have to decode MIME
30
+ * bodies across every folder; on a real mailbox that can exceed the browser
31
+ * tool deadline, so allow two minutes for the search to finish.
32
+ */
33
+ export declare const MAIL_TOOL_TIMEOUT_MS = 120000;
34
+ /** Longer deadline for attachment fetches (files can be several MB). */
35
+ export declare const MAIL_ATTACHMENT_TIMEOUT_MS = 60000;
36
+ /**
37
+ * A reference to one message. `messageId` is transient; `headerMessageId`
38
+ * is the durable Message-ID header and should be the one you store.
39
+ */
40
+ export interface MailMessageRef {
41
+ /** Transient Thunderbird numeric id — valid only in the current session. */
42
+ messageId: number;
43
+ /** Durable Message-ID header, when available. Prefer this for persistence. */
44
+ headerMessageId?: string;
45
+ subject?: string;
46
+ /** RFC 5322 mailbox string, e.g. "Name <addr@example>." */
47
+ author?: string;
48
+ /** RFC 5322 mailbox strings for the To: recipients. */
49
+ recipients?: string[];
50
+ cc?: string[];
51
+ date?: string;
52
+ read?: boolean;
53
+ flagged?: boolean;
54
+ /** Applied tag names (omitted when none). */
55
+ tags?: string[];
56
+ size?: number;
57
+ /** Human-friendly folder name. */
58
+ folder?: string;
59
+ folderId?: string;
60
+ }
61
+ export type MailAttachmentType = "attachment" | "inline" | "cloudFile";
62
+ export interface MailAttachmentRef {
63
+ /** MIME part identifier — pass back to mail_get_attachment. */
64
+ partName: string;
65
+ name: string;
66
+ contentType: string;
67
+ size: number;
68
+ contentDisposition?: string;
69
+ type?: MailAttachmentType;
70
+ /** Present for cloud-file links (e.g. Google Drive) instead of a file. */
71
+ linkUrl?: string;
72
+ }
73
+ export interface MailIdentityRef {
74
+ identityId: string;
75
+ name?: string;
76
+ email?: string;
77
+ isDefault?: boolean;
78
+ }
79
+ export interface MailAccountRef {
80
+ id: string;
81
+ name: string;
82
+ type?: string;
83
+ identities: MailIdentityRef[];
84
+ }
85
+ export interface MailFolderRef {
86
+ id: string;
87
+ name: string;
88
+ path?: string;
89
+ accountId?: string;
90
+ isRoot?: boolean;
91
+ isUnified?: boolean;
92
+ isVirtual?: boolean;
93
+ isTag?: boolean;
94
+ isFavorite?: boolean;
95
+ }
96
+ /**
97
+ * The current Thunderbird mail context — what the user is looking at right
98
+ * now. This is the answer to "what am I looking at?" and the seed for
99
+ * "summarize this email."
100
+ */
101
+ export interface ThunderbirdContext {
102
+ /** The active mail tab, or null when no mail tab is focused. */
103
+ tab: {
104
+ tabId: number;
105
+ type: "inbox" | "thread" | "conversation" | "search" | "news" | string;
106
+ } | null;
107
+ selectedFolders: MailFolderRef[];
108
+ selectedMessages: MailMessageRef[];
109
+ displayedMessages: MailMessageRef[];
110
+ }
111
+ /**
112
+ * Paginated search/list result. When `nextCursor` is non-null there are more
113
+ * results; pass it back as `cursor` to continue.
114
+ *
115
+ * Searches are incremental: a result returned before the mailbox scan
116
+ * finishes may only cover part of the mailbox.
117
+ * - `complete` — true only after every matching folder has been searched.
118
+ * While false, the messages are the best matches found so far (and, for
119
+ * a bare single-folder listing, the folder's own sorted view).
120
+ * - `sortComplete` — true only when the messages are the final, globally
121
+ * sorted result set. An early page cannot promise global order (e.g.
122
+ * newest-first) until this is true.
123
+ * - `scanned` — number of messages examined by the search so far (the
124
+ * running match count, not the mailbox size).
125
+ */
126
+ export interface MailSearchResult {
127
+ messages: MailMessageRef[];
128
+ nextCursor: string | null;
129
+ complete?: boolean;
130
+ sortComplete?: boolean;
131
+ scanned?: number;
132
+ }
133
+ //# sourceMappingURL=mail-tools.d.ts.map