trusted-user-agent 0.0.0-stage → 0.3.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.
- package/LICENSE +21 -0
- package/dist/acp/agent.js +601 -0
- package/dist/acp/backend.js +2 -0
- package/dist/acp/config-options.js +26 -0
- package/dist/acp/mock-backend.js +277 -0
- package/dist/acp/sdk-backend.js +495 -0
- package/dist/browser/mcp-acp-client.js +81 -0
- package/dist/browser/provider.js +1045 -0
- package/dist/browser/schemas.js +221 -0
- package/dist/capability-registry.js +92 -0
- package/dist/client-heartbeat.js +118 -0
- package/dist/compose/schemas.js +90 -0
- package/dist/contacts/schemas.js +26 -0
- package/dist/installer/cli.js +70 -0
- package/dist/installer/common.js +93 -0
- package/dist/installer/index.js +341 -0
- package/dist/installer/mcp-clients.js +555 -0
- package/dist/installer/mcp.js +166 -0
- package/dist/installer/platforms.js +277 -0
- package/dist/logger.js +54 -0
- package/dist/mail/schemas.js +98 -0
- package/dist/mutation/schemas.js +31 -0
- package/dist/native-host/broker-ipc.js +344 -0
- package/dist/native-host/framing.js +76 -0
- package/dist/native-host/main.js +520 -0
- package/dist/native-host/mcp-server.js +322 -0
- package/dist/native-host/mcp-stdio-bridge.js +179 -0
- package/dist/native-host/mcp-stdio-main.js +13 -0
- package/dist/native-host/relay.js +84 -0
- package/dist/native-host/skills-startup.js +167 -0
- package/dist/native-host/transport.js +248 -0
- package/dist/permission-store.js +207 -0
- package/dist/repl/fs-sandbox.js +187 -0
- package/dist/repl/provider.js +252 -0
- package/dist/repl/runtime.js +436 -0
- package/dist/repl/types.js +10 -0
- package/dist/repl/worker.js +731 -0
- package/dist/skills/extension.js +99 -0
- package/dist/skills/grants-file.js +145 -0
- package/dist/skills/isolated-runner.js +259 -0
- package/dist/skills/mock-session-factory.js +49 -0
- package/dist/skills/package-roots.js +25 -0
- package/dist/skills/pi-bridge.js +8 -0
- package/dist/skills/pi-integration.js +110 -0
- package/dist/skills/planner.js +128 -0
- package/dist/skills/registry.js +104 -0
- package/dist/skills/skills-protocol.js +253 -0
- package/dist/skills/skills-service.js +195 -0
- package/dist/tool-bridge.js +8 -0
- package/dist/workspace.js +70 -0
- package/extensions/pi-browser-tools.ts +65 -0
- package/extensions/pi-browser.ts +60 -0
- package/extensions/pi-skills.ts +14 -0
- package/native/pi-agent-host +2 -0
- package/native/pi-browser-host +5 -0
- package/native/pi-browser-host.cmd +3 -0
- package/node_modules/@pi-browser/protocol/.bundled-by-trusted-user-agent +0 -0
- package/node_modules/@pi-browser/protocol/dist/acp.d.ts +10 -0
- package/node_modules/@pi-browser/protocol/dist/acp.js +9 -0
- package/node_modules/@pi-browser/protocol/dist/browser-tools.d.ts +33 -0
- package/node_modules/@pi-browser/protocol/dist/browser-tools.js +478 -0
- package/node_modules/@pi-browser/protocol/dist/callers.d.ts +108 -0
- package/node_modules/@pi-browser/protocol/dist/callers.js +56 -0
- package/node_modules/@pi-browser/protocol/dist/compose-tools.d.ts +30 -0
- package/node_modules/@pi-browser/protocol/dist/compose-tools.js +175 -0
- package/node_modules/@pi-browser/protocol/dist/contacts-tools.d.ts +23 -0
- package/node_modules/@pi-browser/protocol/dist/contacts-tools.js +63 -0
- package/node_modules/@pi-browser/protocol/dist/control-tools.d.ts +32 -0
- package/node_modules/@pi-browser/protocol/dist/control-tools.js +201 -0
- package/node_modules/@pi-browser/protocol/dist/errors.d.ts +63 -0
- package/node_modules/@pi-browser/protocol/dist/errors.js +109 -0
- package/node_modules/@pi-browser/protocol/dist/index.d.ts +16 -0
- package/node_modules/@pi-browser/protocol/dist/index.js +16 -0
- package/node_modules/@pi-browser/protocol/dist/integration.d.ts +409 -0
- package/node_modules/@pi-browser/protocol/dist/integration.js +260 -0
- package/node_modules/@pi-browser/protocol/dist/jsonrpc.d.ts +33 -0
- package/node_modules/@pi-browser/protocol/dist/jsonrpc.js +31 -0
- package/node_modules/@pi-browser/protocol/dist/mail-mutation-tools.d.ts +27 -0
- package/node_modules/@pi-browser/protocol/dist/mail-mutation-tools.js +88 -0
- package/node_modules/@pi-browser/protocol/dist/mail-tools.d.ts +133 -0
- package/node_modules/@pi-browser/protocol/dist/mail-tools.js +245 -0
- package/node_modules/@pi-browser/protocol/dist/permission.d.ts +113 -0
- package/node_modules/@pi-browser/protocol/dist/permission.js +257 -0
- package/node_modules/@pi-browser/protocol/dist/skills.d.ts +304 -0
- package/node_modules/@pi-browser/protocol/dist/skills.js +473 -0
- package/node_modules/@pi-browser/protocol/dist/tool-capabilities.d.ts +18 -0
- package/node_modules/@pi-browser/protocol/dist/tool-capabilities.js +52 -0
- package/node_modules/@pi-browser/protocol/dist/transport.d.ts +17 -0
- package/node_modules/@pi-browser/protocol/dist/transport.js +17 -0
- package/node_modules/@pi-browser/protocol/package.json +14 -0
- package/package.json +71 -6
- package/skills/browser-walk/SKILL.md +98 -0
- package/README.md +0 -3
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
export const PI_BROWSER_ERROR = {
|
|
2
|
+
NATIVE_HOST_NOT_INSTALLED: "NATIVE_HOST_NOT_INSTALLED",
|
|
3
|
+
NATIVE_HOST_VERSION_MISMATCH: "NATIVE_HOST_VERSION_MISMATCH",
|
|
4
|
+
PI_NOT_FOUND: "PI_NOT_FOUND",
|
|
5
|
+
PI_START_FAILED: "PI_START_FAILED",
|
|
6
|
+
ACP_INITIALIZATION_FAILED: "ACP_INITIALIZATION_FAILED",
|
|
7
|
+
ACP_CAPABILITY_UNSUPPORTED: "ACP_CAPABILITY_UNSUPPORTED",
|
|
8
|
+
SESSION_NOT_FOUND: "SESSION_NOT_FOUND",
|
|
9
|
+
SESSION_BUSY: "SESSION_BUSY",
|
|
10
|
+
BROWSER_NOT_BOUND: "BROWSER_NOT_BOUND",
|
|
11
|
+
BROWSER_TAB_CLOSED: "BROWSER_TAB_CLOSED",
|
|
12
|
+
BROWSER_FRAME_NOT_FOUND: "BROWSER_FRAME_NOT_FOUND",
|
|
13
|
+
BROWSER_PERMISSION_DENIED: "BROWSER_PERMISSION_DENIED",
|
|
14
|
+
BROWSER_ELEMENT_STALE: "BROWSER_ELEMENT_STALE",
|
|
15
|
+
BROWSER_TOOL_TIMEOUT: "BROWSER_TOOL_TIMEOUT",
|
|
16
|
+
BROWSER_DOWNLOAD_TOO_LARGE: "BROWSER_DOWNLOAD_TOO_LARGE",
|
|
17
|
+
MCP_UNAVAILABLE: "MCP_UNAVAILABLE",
|
|
18
|
+
MCP_TOOL_NOT_FOUND: "MCP_TOOL_NOT_FOUND",
|
|
19
|
+
PROTOCOL_VERSION_MISMATCH: "PROTOCOL_VERSION_MISMATCH",
|
|
20
|
+
INTERNAL: "INTERNAL",
|
|
21
|
+
MAIL_NO_CONTEXT: "MAIL_NO_CONTEXT",
|
|
22
|
+
MAIL_MESSAGE_NOT_FOUND: "MAIL_MESSAGE_NOT_FOUND",
|
|
23
|
+
MAIL_ATTACHMENT_NOT_FOUND: "MAIL_ATTACHMENT_NOT_FOUND",
|
|
24
|
+
MAIL_CURSOR_EXPIRED: "MAIL_CURSOR_EXPIRED",
|
|
25
|
+
};
|
|
26
|
+
/** JSON-RPC reserved range for application errors. */
|
|
27
|
+
const APP_ERROR_BASE = -32099;
|
|
28
|
+
const ORDER = [
|
|
29
|
+
PI_BROWSER_ERROR.NATIVE_HOST_NOT_INSTALLED,
|
|
30
|
+
PI_BROWSER_ERROR.NATIVE_HOST_VERSION_MISMATCH,
|
|
31
|
+
PI_BROWSER_ERROR.PI_NOT_FOUND,
|
|
32
|
+
PI_BROWSER_ERROR.PI_START_FAILED,
|
|
33
|
+
PI_BROWSER_ERROR.ACP_INITIALIZATION_FAILED,
|
|
34
|
+
PI_BROWSER_ERROR.ACP_CAPABILITY_UNSUPPORTED,
|
|
35
|
+
PI_BROWSER_ERROR.SESSION_NOT_FOUND,
|
|
36
|
+
PI_BROWSER_ERROR.SESSION_BUSY,
|
|
37
|
+
PI_BROWSER_ERROR.BROWSER_NOT_BOUND,
|
|
38
|
+
PI_BROWSER_ERROR.BROWSER_TAB_CLOSED,
|
|
39
|
+
PI_BROWSER_ERROR.BROWSER_FRAME_NOT_FOUND,
|
|
40
|
+
PI_BROWSER_ERROR.BROWSER_PERMISSION_DENIED,
|
|
41
|
+
PI_BROWSER_ERROR.BROWSER_ELEMENT_STALE,
|
|
42
|
+
PI_BROWSER_ERROR.BROWSER_TOOL_TIMEOUT,
|
|
43
|
+
PI_BROWSER_ERROR.BROWSER_DOWNLOAD_TOO_LARGE,
|
|
44
|
+
PI_BROWSER_ERROR.MCP_UNAVAILABLE,
|
|
45
|
+
PI_BROWSER_ERROR.MCP_TOOL_NOT_FOUND,
|
|
46
|
+
PI_BROWSER_ERROR.PROTOCOL_VERSION_MISMATCH,
|
|
47
|
+
PI_BROWSER_ERROR.INTERNAL,
|
|
48
|
+
PI_BROWSER_ERROR.MAIL_NO_CONTEXT,
|
|
49
|
+
PI_BROWSER_ERROR.MAIL_MESSAGE_NOT_FOUND,
|
|
50
|
+
PI_BROWSER_ERROR.MAIL_ATTACHMENT_NOT_FOUND,
|
|
51
|
+
PI_BROWSER_ERROR.MAIL_CURSOR_EXPIRED,
|
|
52
|
+
];
|
|
53
|
+
export const PI_BROWSER_ERROR_CODES = new Map(ORDER.map((code, i) => [code, APP_ERROR_BASE + 1 + i]));
|
|
54
|
+
const NUMERIC_TO_CODE = new Map([...PI_BROWSER_ERROR_CODES].map(([c, n]) => [n, c]));
|
|
55
|
+
export function isPiBrowserErrorCode(value) {
|
|
56
|
+
return typeof value === "string" && PI_BROWSER_ERROR_CODES.has(value);
|
|
57
|
+
}
|
|
58
|
+
/** JSON-RPC numeric code for a Pi Browser error code. */
|
|
59
|
+
export function piBrowserErrorNumeric(code) {
|
|
60
|
+
return PI_BROWSER_ERROR_CODES.get(code) ?? APP_ERROR_BASE;
|
|
61
|
+
}
|
|
62
|
+
/** Build a JSON-RPC error object carrying a structured Pi Browser code. */
|
|
63
|
+
export function toErrorObject(code, message, data) {
|
|
64
|
+
return {
|
|
65
|
+
code: piBrowserErrorNumeric(code),
|
|
66
|
+
message,
|
|
67
|
+
data: {
|
|
68
|
+
piBrowserError: code,
|
|
69
|
+
...(typeof data === "object" && data !== null ? data : {}),
|
|
70
|
+
},
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Recover the structured code from a JSON-RPC error object. Prefers the
|
|
75
|
+
* explicit `data.piBrowserError` string, falls back to the reserved numeric
|
|
76
|
+
* range, returns undefined for plain JSON-RPC/protocol errors.
|
|
77
|
+
*/
|
|
78
|
+
export function codeFromErrorObject(err) {
|
|
79
|
+
if (!err)
|
|
80
|
+
return undefined;
|
|
81
|
+
const data = err.data;
|
|
82
|
+
if (data && isPiBrowserErrorCode(data.piBrowserError))
|
|
83
|
+
return data.piBrowserError;
|
|
84
|
+
const byNumeric = NUMERIC_TO_CODE.get(err.code);
|
|
85
|
+
return byNumeric;
|
|
86
|
+
}
|
|
87
|
+
/** Error type used internally on both sides of the link. */
|
|
88
|
+
export class PiBrowserProtocolError extends Error {
|
|
89
|
+
code;
|
|
90
|
+
data;
|
|
91
|
+
constructor(code, message, data) {
|
|
92
|
+
super(message);
|
|
93
|
+
this.code = code;
|
|
94
|
+
this.data = data;
|
|
95
|
+
this.name = "PiBrowserProtocolError";
|
|
96
|
+
}
|
|
97
|
+
toErrorObject() {
|
|
98
|
+
return toErrorObject(this.code, this.message, this.data);
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
/** Standard JSON-RPC error codes for protocol-level (non-Pi-Browser) failures. */
|
|
102
|
+
export const JSONRPC_ERROR = {
|
|
103
|
+
PARSE: -32700,
|
|
104
|
+
INVALID_REQUEST: -32600,
|
|
105
|
+
METHOD_NOT_FOUND: -32601,
|
|
106
|
+
INVALID_PARAMS: -32602,
|
|
107
|
+
INTERNAL: -32603,
|
|
108
|
+
};
|
|
109
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
export * from "./acp.js";
|
|
2
|
+
export * from "./jsonrpc.js";
|
|
3
|
+
export * from "./transport.js";
|
|
4
|
+
export * from "./integration.js";
|
|
5
|
+
export * from "./errors.js";
|
|
6
|
+
export * from "./browser-tools.js";
|
|
7
|
+
export * from "./control-tools.js";
|
|
8
|
+
export * from "./mail-tools.js";
|
|
9
|
+
export * from "./compose-tools.js";
|
|
10
|
+
export * from "./mail-mutation-tools.js";
|
|
11
|
+
export * from "./contacts-tools.js";
|
|
12
|
+
export * from "./permission.js";
|
|
13
|
+
export * from "./tool-capabilities.js";
|
|
14
|
+
export * from "./callers.js";
|
|
15
|
+
export * from "./skills.js";
|
|
16
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
export * from "./acp.js";
|
|
2
|
+
export * from "./jsonrpc.js";
|
|
3
|
+
export * from "./transport.js";
|
|
4
|
+
export * from "./integration.js";
|
|
5
|
+
export * from "./errors.js";
|
|
6
|
+
export * from "./browser-tools.js";
|
|
7
|
+
export * from "./control-tools.js";
|
|
8
|
+
export * from "./mail-tools.js";
|
|
9
|
+
export * from "./compose-tools.js";
|
|
10
|
+
export * from "./mail-mutation-tools.js";
|
|
11
|
+
export * from "./contacts-tools.js";
|
|
12
|
+
export * from "./permission.js";
|
|
13
|
+
export * from "./tool-capabilities.js";
|
|
14
|
+
export * from "./callers.js";
|
|
15
|
+
export * from "./skills.js";
|
|
16
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,409 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pi Browser integration protocol: identity, versioning, and the private
|
|
3
|
+
* `x-pi-browser/*` compatibility namespace.
|
|
4
|
+
*
|
|
5
|
+
* The private namespace is a transport compatibility layer only (see
|
|
6
|
+
* PRODUCT.md §29–30). Tool names, arguments, and results are defined by
|
|
7
|
+
* the MCP-compatible schemas in browser-tools.ts and must stay identical
|
|
8
|
+
* when the transport migrates to MCP-over-ACP.
|
|
9
|
+
*/
|
|
10
|
+
import type { MailSearchResult } from "./mail-tools.js";
|
|
11
|
+
export declare const PI_BROWSER: {
|
|
12
|
+
/** Package name. */
|
|
13
|
+
readonly name: "pi-browser";
|
|
14
|
+
/** Package release version (npm version of trusted-user-agent). */
|
|
15
|
+
readonly version: "0.3.0";
|
|
16
|
+
/**
|
|
17
|
+
* Pi Browser integration protocol version (bump on breaking changes to
|
|
18
|
+
* x-pi-browser/* semantics or integration metadata). v2 = 2026-09-11
|
|
19
|
+
* identity rename (add-on IDs to @matbee.com, host name to com.matbee.agent).
|
|
20
|
+
* v3 = 2026-09-12: x-pi-browser/tool_update — long-running tools (mail_search)
|
|
21
|
+
* stream batches/progress to the host while the original x-pi-browser/tool
|
|
22
|
+
* request is still pending; MailSearchResult gains complete/sortComplete/scanned.
|
|
23
|
+
*/
|
|
24
|
+
readonly protocolVersion: 3;
|
|
25
|
+
/**
|
|
26
|
+
* Browser tool schema version (bump when tool schemas change).
|
|
27
|
+
* v2 = 2026-09-12: added browser_evaluate, browser_get_accessibility_tree,
|
|
28
|
+
* browser_get_console, browser_get_network, browser_element_at, browser_navigate;
|
|
29
|
+
* widened browser_get_dom coverage (more element kinds + per-element fields).
|
|
30
|
+
* v3 = 2026-09-12: frame targeting (optional `frame` parameter on the nine
|
|
31
|
+
* content-frame tools), browser_get_dom now traverses open shadow roots and
|
|
32
|
+
* reports iframes/stats; new BROWSER_FRAME_NOT_FOUND error.
|
|
33
|
+
* v4 = 2026-09-12: host-side `javascript` REPL tool (BROWSER-USE-REPL-PLAN.md,
|
|
34
|
+
* option C) — a persistent V8 cell interpreter; `page.*`/`tabs.*` primitives
|
|
35
|
+
* execute the existing browser tools against the session's current tab. The
|
|
36
|
+
* tool is hosted by the native host, not by the add-on (see REPL_TOOLS).
|
|
37
|
+
* v5 = 2026-09-12: REPL add-on deltas — browser_click_at, browser_focus,
|
|
38
|
+
* browser_scroll, browser_type_focused (content-script interaction),
|
|
39
|
+
* browser_open_tab / browser_close_tab / browser_list_tabs (REPL-owned
|
|
40
|
+
* auxiliary tabs, closed at session unbind), and browser_get_accessibility_tree
|
|
41
|
+
* `format: "nodes"` (structured snapshot for page.snapshot()).
|
|
42
|
+
* v6 = 2026-09-12: `javascript` REPL gains an `fs` global — a workspace-
|
|
43
|
+
* scoped filesystem (read/write/append/list/stat/exists/mkdir/rename/
|
|
44
|
+
* unlink/rm) confined to the session's task workspace (lexical + symlink
|
|
45
|
+
* escape rejection); no add-on-side change (host-side realm global).
|
|
46
|
+
* v8 = 2026-09-12: mail_search became incremental — results carry
|
|
47
|
+
* `complete`, `sortComplete`, and `scanned`, and long searches stream
|
|
48
|
+
* partial batches over x-pi-browser/tool_update (protocol v3).
|
|
49
|
+
*/
|
|
50
|
+
readonly browserToolVersion: 8;
|
|
51
|
+
/** Stable Firefox Native Messaging host name (manifest `name`). */
|
|
52
|
+
readonly nativeHost: "dev.pi.browser";
|
|
53
|
+
/** Stable Firefox add-on ID (gecko.id). Must match allowed_extensions. */
|
|
54
|
+
readonly extensionId: "pi-agent-firefox@matbee.com";
|
|
55
|
+
};
|
|
56
|
+
/** Mozilla applications that can attach as capability providers. */
|
|
57
|
+
export type AgentApplication = "firefox" | "thunderbird";
|
|
58
|
+
/** Capability domains a client exposes to Pi (THUNDERBIRD-PLAN.md §28). */
|
|
59
|
+
export type AgentCapability = "browser" | "mail" | "compose" | "attachments" | "contacts" | "mailModify";
|
|
60
|
+
/** Valid agent capabilities (for parsing/normalization). */
|
|
61
|
+
export declare const AGENT_CAPABILITIES: readonly AgentCapability[];
|
|
62
|
+
/** Agent-level integration identity (application-neutral). */
|
|
63
|
+
export declare const PI_AGENT: {
|
|
64
|
+
/**
|
|
65
|
+
* Native Messaging host name (manifest `name`), shared by both
|
|
66
|
+
* applications. 2026-09-11: renamed from the `dev.pi.*` placeholders to a
|
|
67
|
+
* name under the project-owned matbee domain.
|
|
68
|
+
*/
|
|
69
|
+
readonly nativeHost: "com.matbee.agent";
|
|
70
|
+
/** Legacy host name kept for already-registered Firefox installations. */
|
|
71
|
+
readonly legacyNativeHost: "dev.pi.browser";
|
|
72
|
+
/**
|
|
73
|
+
* Add-on IDs the native host manifest authorizes. `pi-agent-firefox@matbee.com`
|
|
74
|
+
* and `pi-agent-thunderbird@matbee.com` are the production add-on IDs (2026-09-11
|
|
75
|
+
* rename from the `@pi.dev` placeholders to a domain the project owns);
|
|
76
|
+
* `pi-firefox@matbee.com` remains authorized for compatibility.
|
|
77
|
+
*/
|
|
78
|
+
readonly authorizedExtensions: readonly ["pi-agent-firefox@matbee.com", "pi-firefox@matbee.com", "pi-agent-thunderbird@matbee.com"];
|
|
79
|
+
/**
|
|
80
|
+
* Agent integration protocol version (bump on breaking _meta.piAgent
|
|
81
|
+
* changes). v2 = 2026-09-11 identity rename.
|
|
82
|
+
*/
|
|
83
|
+
readonly protocolVersion: 2;
|
|
84
|
+
};
|
|
85
|
+
/** Client identity declared in the integration hello. */
|
|
86
|
+
export interface AgentClientIdentity {
|
|
87
|
+
application: AgentApplication;
|
|
88
|
+
extensionId: string;
|
|
89
|
+
version: string;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Integration hello (THUNDERBIRD-PLAN.md §24). Sent by the client in the
|
|
93
|
+
* ACP `initialize` params under `_meta.piAgent`.
|
|
94
|
+
*/
|
|
95
|
+
export interface AgentHello {
|
|
96
|
+
type: "pi.agent.hello";
|
|
97
|
+
client: AgentClientIdentity;
|
|
98
|
+
capabilities: AgentCapability[];
|
|
99
|
+
}
|
|
100
|
+
/** `_meta.piAgent` exchanged during ACP initialization. */
|
|
101
|
+
export interface PiAgentMeta {
|
|
102
|
+
version: string;
|
|
103
|
+
protocolVersion: number;
|
|
104
|
+
/** Which client is attached (host echo of the hello). */
|
|
105
|
+
application?: AgentApplication;
|
|
106
|
+
/** Capabilities the host accepts from this client. */
|
|
107
|
+
capabilities: AgentCapability[];
|
|
108
|
+
/**
|
|
109
|
+
* Union of capabilities across ALL connected clients (broker mode) as of
|
|
110
|
+
* initialize — the session tool surface (plan §29). Lets the add-on UI
|
|
111
|
+
* show peer-app capabilities (e.g. browsing from the mail client). Absent
|
|
112
|
+
* on legacy hosts and in standalone single-app mode (use `capabilities`).
|
|
113
|
+
* Live changes arrive via x-pi-browser/capabilities_changed.
|
|
114
|
+
*/
|
|
115
|
+
connectedCapabilities?: AgentCapability[];
|
|
116
|
+
}
|
|
117
|
+
export declare const PI_AGENT_META: PiAgentMeta;
|
|
118
|
+
/** Filter an arbitrary list down to known capabilities, preserving order. */
|
|
119
|
+
export declare function normalizeCapabilities(values: unknown): AgentCapability[];
|
|
120
|
+
/**
|
|
121
|
+
* Parse the integration hello from ACP `initialize` params.
|
|
122
|
+
* Returns undefined when absent/malformed (legacy clients); the caller
|
|
123
|
+
* falls back to browser compatibility defaults.
|
|
124
|
+
*/
|
|
125
|
+
export declare function parseAgentHello(params: unknown): AgentHello | undefined;
|
|
126
|
+
/** Build the `_meta.piAgent` client hello block for ACP `initialize` params. */
|
|
127
|
+
export declare function buildAgentHelloMeta(hello: Omit<AgentHello, "type">): {
|
|
128
|
+
piAgent: AgentHello;
|
|
129
|
+
};
|
|
130
|
+
/**
|
|
131
|
+
* Broker/relay private IPC (THUNDERBIRD-PLAN.md §26–27).
|
|
132
|
+
*
|
|
133
|
+
* One host process is the broker (owns the ACP agent + Pi sessions); later
|
|
134
|
+
* app connections attach to it as relays over private OS IPC (Unix socket,
|
|
135
|
+
* no localhost TCP). Native Messaging remains the externally visible
|
|
136
|
+
* Mozilla security boundary — the relay only forwards bytes.
|
|
137
|
+
*/
|
|
138
|
+
export declare const PI_BROKER: {
|
|
139
|
+
/** Run directory name under $HOME (0700; env PI_BROWSER_BROKER_DIR overrides). */
|
|
140
|
+
readonly runDir: "run";
|
|
141
|
+
/** Unix socket file name inside the run directory (0600). */
|
|
142
|
+
readonly socketFile: "agent-broker.sock";
|
|
143
|
+
/**
|
|
144
|
+
* MCP server socket file name inside the run directory (0600). Exposes
|
|
145
|
+
* the browser tools as a plain MCP server (JSONL JSON-RPC) so separate
|
|
146
|
+
* pi-subagent child processes — which have no ACP channel and no
|
|
147
|
+
* in-process tool bridge — can reach them over MCP.
|
|
148
|
+
*/
|
|
149
|
+
readonly mcpSocketFile: "agent-broker-mcp.sock";
|
|
150
|
+
/** Broker state file name inside the run directory (0600: pid + token). */
|
|
151
|
+
readonly stateFile: "agent-broker.json";
|
|
152
|
+
/** First frame a relay sends after connecting (carries the token). */
|
|
153
|
+
readonly handshake: "pi.broker.handshake";
|
|
154
|
+
/** First frame the broker sends back once the token is accepted. */
|
|
155
|
+
readonly handshakeAck: "pi.broker.handshakeAck";
|
|
156
|
+
/** Broker IPC protocol version (bump on breaking handshake changes). */
|
|
157
|
+
readonly version: 1;
|
|
158
|
+
};
|
|
159
|
+
/** Metadata exchanged during ACP initialization (PRODUCT.md §45). */
|
|
160
|
+
export interface PiBrowserMeta {
|
|
161
|
+
version: string;
|
|
162
|
+
protocolVersion: number;
|
|
163
|
+
browserToolVersion: number;
|
|
164
|
+
/**
|
|
165
|
+
* Where the host provisions per-task workspaces (initialize only; e.g.
|
|
166
|
+
* ~/.pi/workspaces). A session created with an empty cwd gets a fresh
|
|
167
|
+
* directory under it — the add-on UIs show this as the default working
|
|
168
|
+
* directory. Optional: older hosts omit it.
|
|
169
|
+
*/
|
|
170
|
+
workspaceRoot?: string;
|
|
171
|
+
}
|
|
172
|
+
export declare const PI_BROWSER_META: PiBrowserMeta;
|
|
173
|
+
/** Private extension methods (PRODUCT.md §30). Never used for ACP session semantics. */
|
|
174
|
+
export declare const X_PI_BROWSER: {
|
|
175
|
+
/** Firefox → host: liveness/version probe used by /pi-browser status|doctor. */
|
|
176
|
+
readonly ping: "x-pi-browser/ping";
|
|
177
|
+
/** Host → Firefox: browser tool invocation (legacy compatibility transport). */
|
|
178
|
+
readonly tool: "x-pi-browser/tool";
|
|
179
|
+
/** Firefox → host: browser-side notifications (tab closed/navigated, binding changed). */
|
|
180
|
+
readonly notify: "x-pi-browser/notify";
|
|
181
|
+
/**
|
|
182
|
+
* Host → session-owner client: a tool's approval prompt is being shown in
|
|
183
|
+
* ANOTHER app (cross-app routing). The owner's UI is where the user is
|
|
184
|
+
* watching the session, so it should draw attention to where the prompt
|
|
185
|
+
* actually is (e.g. "approval needed in the mail client"). The owner
|
|
186
|
+
* displays it; it does NOT answer it (the executing client owns the
|
|
187
|
+
* canonical session/request_permission round-trip).
|
|
188
|
+
*/
|
|
189
|
+
readonly permission_prompted: "x-pi-browser/permission_prompted";
|
|
190
|
+
/**
|
|
191
|
+
* Client → host: incremental progress for a tool call that is still
|
|
192
|
+
* pending (the x-pi-browser/tool request has not answered yet). The host
|
|
193
|
+
* maps batches onto ACP session/update tool_call_update so the model can
|
|
194
|
+
* see results before the final answer; the final tool response is
|
|
195
|
+
* unchanged, so clients that ignore updates stay compatible.
|
|
196
|
+
* The update never authorizes anything — it only reports results of the
|
|
197
|
+
* already-approved call.
|
|
198
|
+
*/
|
|
199
|
+
readonly tool_update: "x-pi-browser/tool_update";
|
|
200
|
+
/**
|
|
201
|
+
* Host → all clients: the set of connected capability providers changed
|
|
202
|
+
* (a peer app connected or disconnected). Carries the current union so
|
|
203
|
+
* each UI can update its "capabilities:" line. Display-only; additive —
|
|
204
|
+
* legacy hosts never send it and clients ignore it when absent.
|
|
205
|
+
*/
|
|
206
|
+
readonly capabilities_changed: "x-pi-browser/capabilities_changed";
|
|
207
|
+
/**
|
|
208
|
+
* Client → host: fetch the permission configuration — every approval-
|
|
209
|
+
* gated tool with its persistent "always allow" state. The add-on
|
|
210
|
+
* Configuration page renders from this (PRODUCT.md §55).
|
|
211
|
+
*/
|
|
212
|
+
readonly permissions: "x-pi-browser/permissions";
|
|
213
|
+
/**
|
|
214
|
+
* Client → host: set one tool's persistent state (ask | deny | allow)
|
|
215
|
+
* from the Configuration page.
|
|
216
|
+
*/
|
|
217
|
+
readonly permission_set: "x-pi-browser/permission_set";
|
|
218
|
+
/**
|
|
219
|
+
* Client → host: clear the persistent "always allow" state of one tool
|
|
220
|
+
* (or of every tool when `tool` is omitted).
|
|
221
|
+
*/
|
|
222
|
+
readonly permission_clear: "x-pi-browser/permission_clear";
|
|
223
|
+
/**
|
|
224
|
+
* Client → host: compile a page plan for a verified source identity
|
|
225
|
+
* (skills-runtime-design.md §2, §7). The source identity is supplied by
|
|
226
|
+
* the addon coordinator, never a page payload.
|
|
227
|
+
*/
|
|
228
|
+
readonly skills_plan: "x-pi-browser/skills_plan";
|
|
229
|
+
/**
|
|
230
|
+
* Client → host: submit a verified skill event. Responds with an ack:
|
|
231
|
+
* accepted (jobs launched), no-match, stale-plan (re-plan), unavailable,
|
|
232
|
+
* or duplicate (coordinator redelivery).
|
|
233
|
+
*/
|
|
234
|
+
readonly skills_event: "x-pi-browser/skills_event";
|
|
235
|
+
/** Client → host: cancel pending skill work for one interaction. */
|
|
236
|
+
readonly skills_cancel: "x-pi-browser/skills_cancel";
|
|
237
|
+
/** Client → host: probe the skill runtime (queue, live plans, stats). */
|
|
238
|
+
readonly skills_status: "x-pi-browser/skills_status";
|
|
239
|
+
/**
|
|
240
|
+
* Host → client: resolve a contextRef against the coordinator's bounded
|
|
241
|
+
* snapshot store (privacy by request: only the requested fields return).
|
|
242
|
+
*/
|
|
243
|
+
readonly skills_context: "x-pi-browser/skills_context";
|
|
244
|
+
/**
|
|
245
|
+
* Host → client: deliver a skill job outcome for a submitted event. The
|
|
246
|
+
* coordinator routes it to the gate/UI and acks delivery; the request ID
|
|
247
|
+
* makes delivery explicit (design §7: results require request IDs).
|
|
248
|
+
*/
|
|
249
|
+
readonly skills_result: "x-pi-browser/skills_result";
|
|
250
|
+
};
|
|
251
|
+
/** Params for x-pi-browser/ping (Firefox → host). */
|
|
252
|
+
export interface PingParams {
|
|
253
|
+
clientVersion?: string;
|
|
254
|
+
}
|
|
255
|
+
/** Result for x-pi-browser/ping. */
|
|
256
|
+
export interface PingResult {
|
|
257
|
+
pong: true;
|
|
258
|
+
meta: PiBrowserMeta;
|
|
259
|
+
/** Whether the host reached a Pi SDK model runtime (diagnostic only). */
|
|
260
|
+
backendReady: boolean;
|
|
261
|
+
}
|
|
262
|
+
/** Params for x-pi-browser/tool (host → Firefox). */
|
|
263
|
+
export interface BrowserToolCallParams {
|
|
264
|
+
sessionId: string;
|
|
265
|
+
tool: string;
|
|
266
|
+
arguments: Record<string, unknown>;
|
|
267
|
+
/** Soft timeout hint for the Firefox side; the host also enforces its own deadline. */
|
|
268
|
+
timeoutMs?: number;
|
|
269
|
+
/**
|
|
270
|
+
* Stable id for this call, generated by the host. The client echoes it in
|
|
271
|
+
* x-pi-browser/tool_update notifications so the host can route updates to
|
|
272
|
+
* the pending call (and reject updates for unknown calls). Older clients
|
|
273
|
+
* never send updates, so it is optional on the wire.
|
|
274
|
+
*/
|
|
275
|
+
toolCallId?: string;
|
|
276
|
+
}
|
|
277
|
+
/** Params for x-pi-browser/tool_update (client → host). */
|
|
278
|
+
export interface BrowserToolUpdateParams {
|
|
279
|
+
sessionId: string;
|
|
280
|
+
/** Matches the tool call currently executing in this session. */
|
|
281
|
+
toolCallId: string;
|
|
282
|
+
/** Only long-running tools stream updates today. */
|
|
283
|
+
tool: "mail_search";
|
|
284
|
+
/**
|
|
285
|
+
* Monotonic per-tool-call sequence number (client-assigned, starting at 1).
|
|
286
|
+
* The host rejects gaps and duplicates to keep the stream ordered.
|
|
287
|
+
*/
|
|
288
|
+
sequence?: number;
|
|
289
|
+
update: {
|
|
290
|
+
kind: "batch";
|
|
291
|
+
result: MailSearchResult;
|
|
292
|
+
} | {
|
|
293
|
+
kind: "progress";
|
|
294
|
+
scanned: number;
|
|
295
|
+
/** Wall-clock age of the search (since the first call), client-measured. */
|
|
296
|
+
elapsedMs?: number;
|
|
297
|
+
/** Duration of the most recently drained backend page, client-measured. */
|
|
298
|
+
pageMs?: number;
|
|
299
|
+
} | {
|
|
300
|
+
kind: "complete";
|
|
301
|
+
};
|
|
302
|
+
}
|
|
303
|
+
/**
|
|
304
|
+
* Firefox → host notification payload. Allows the host to invalidate
|
|
305
|
+
* per-session state (e.g. element references) without waiting for a tool
|
|
306
|
+
* call to fail.
|
|
307
|
+
*/
|
|
308
|
+
export type BrowserNotifyEvent = "tab_closed" | "tab_navigated" | "binding_changed" | "binding_removed";
|
|
309
|
+
export interface BrowserNotifyParams {
|
|
310
|
+
sessionId: string;
|
|
311
|
+
event: BrowserNotifyEvent;
|
|
312
|
+
data?: Record<string, unknown>;
|
|
313
|
+
}
|
|
314
|
+
/** Params for x-pi-browser/capabilities_changed (host → client). */
|
|
315
|
+
export interface CapabilitiesChangedParams {
|
|
316
|
+
/** Union of all connected clients' capabilities (canonical order). */
|
|
317
|
+
capabilities: AgentCapability[];
|
|
318
|
+
}
|
|
319
|
+
/** Params for x-pi-browser/permission_prompted (host → session-owner client). */
|
|
320
|
+
export interface PermissionPromptedParams {
|
|
321
|
+
sessionId: string;
|
|
322
|
+
/** The tool call the approval belongs to (matches the session/update stream). */
|
|
323
|
+
toolCallId: string;
|
|
324
|
+
/** The tool being approved. */
|
|
325
|
+
tool: string;
|
|
326
|
+
/** The application whose UI is showing the approval prompt. */
|
|
327
|
+
application: AgentApplication;
|
|
328
|
+
}
|
|
329
|
+
/** Human-facing name for an application (permission banners, prompts). */
|
|
330
|
+
export declare function applicationDisplayName(app: AgentApplication): string;
|
|
331
|
+
/** MCP protocol version spoken inside mcp/message (MCP-over-ACP). */
|
|
332
|
+
export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
|
|
333
|
+
/** Default per-tool deadline the host enforces when Firefox does not answer. */
|
|
334
|
+
export declare const BROWSER_TOOL_TIMEOUT_MS = 30000;
|
|
335
|
+
/** Long deadline for screenshot calls (capture can be slow on busy pages). */
|
|
336
|
+
export declare const BROWSER_SCREENSHOT_TIMEOUT_MS = 60000;
|
|
337
|
+
/** Long deadline for file downloads (images/videos can be several MB). */
|
|
338
|
+
export declare const BROWSER_DOWNLOAD_TIMEOUT_MS = 120000;
|
|
339
|
+
/** Tool group the Configuration page renders (labels live in permission.ts). */
|
|
340
|
+
export type PermissionToolGroup = "browser" | "repl" | "control" | "mail" | "compose" | "mail-mutations" | "contacts";
|
|
341
|
+
/**
|
|
342
|
+
* One approval-gated tool as reported by x-pi-browser/permissions.
|
|
343
|
+
* `state` is the tool's persistent decision: "ask" (prompt every time),
|
|
344
|
+
* "deny" (refuse without asking) or "allow" (always approved). `managedBy`
|
|
345
|
+
* marks tools whose grant is owned by the application (not the host store)
|
|
346
|
+
* — e.g. browser_evaluate, where Firefox's revocable `userScripts`
|
|
347
|
+
* permission is authoritative; such rows have no toggle. `note` carries an
|
|
348
|
+
* extra explanation for rows without a toggle.
|
|
349
|
+
*/
|
|
350
|
+
export interface PermissionConfigTool {
|
|
351
|
+
name: string;
|
|
352
|
+
description: string;
|
|
353
|
+
group: PermissionToolGroup;
|
|
354
|
+
/** Persistent decision (host store); "ask" = no entry. */
|
|
355
|
+
state: PermissionToolState;
|
|
356
|
+
/** Set when the application owns the grant (row is informational only). */
|
|
357
|
+
managedBy?: AgentApplication;
|
|
358
|
+
/** Extra one-line note for the Configuration page (e.g. per-primitive gating). */
|
|
359
|
+
note?: string;
|
|
360
|
+
}
|
|
361
|
+
/** Result for x-pi-browser/permissions. */
|
|
362
|
+
export interface PermissionConfigResult {
|
|
363
|
+
tools: PermissionConfigTool[];
|
|
364
|
+
/**
|
|
365
|
+
* External MCP callers (v0.3.0+ hosts; absent from older hosts): whether
|
|
366
|
+
* other apps may use the tools over MCP at all (default true).
|
|
367
|
+
*/
|
|
368
|
+
externalAccess?: boolean;
|
|
369
|
+
/** Remembered caller decisions, per app (v0.3.0+ hosts). */
|
|
370
|
+
callers?: import("./callers.js").CallerPermissionEntry[];
|
|
371
|
+
}
|
|
372
|
+
/**
|
|
373
|
+
* A tool's persistent permission state (Configuration page, PRODUCT.md
|
|
374
|
+
* §55). "ask" is the default: the user is prompted on every call. "deny"
|
|
375
|
+
* refuses the tool without asking (structured BROWSER_PERMISSION_DENIED).
|
|
376
|
+
* "allow" approves every call without asking.
|
|
377
|
+
*/
|
|
378
|
+
export type PermissionToolState = "ask" | "deny" | "allow";
|
|
379
|
+
/** Params for x-pi-browser/permission_set. */
|
|
380
|
+
export interface PermissionSetParams {
|
|
381
|
+
/** Set one tool's state (with `state`). */
|
|
382
|
+
tool?: string;
|
|
383
|
+
state?: PermissionToolState;
|
|
384
|
+
/** Set one caller's decision for one app (with `state`; "ask" forgets it). */
|
|
385
|
+
caller?: import("./callers.js").CallerRef;
|
|
386
|
+
/** Turn external MCP access on or off. */
|
|
387
|
+
externalAccess?: boolean;
|
|
388
|
+
}
|
|
389
|
+
/** Result for x-pi-browser/permission_set (echoes what was set). */
|
|
390
|
+
export interface PermissionSetResult {
|
|
391
|
+
tool?: string;
|
|
392
|
+
state?: PermissionToolState;
|
|
393
|
+
caller?: import("./callers.js").CallerRef;
|
|
394
|
+
externalAccess?: boolean;
|
|
395
|
+
}
|
|
396
|
+
/**
|
|
397
|
+
* Params for x-pi-browser/permission_clear: `tool` clears one tool,
|
|
398
|
+
* `caller` forgets one caller decision, neither clears every tool decision
|
|
399
|
+
* (caller decisions are kept).
|
|
400
|
+
*/
|
|
401
|
+
export interface PermissionClearParams {
|
|
402
|
+
tool?: string;
|
|
403
|
+
caller?: import("./callers.js").CallerRef;
|
|
404
|
+
}
|
|
405
|
+
/** Result for x-pi-browser/permission_clear. */
|
|
406
|
+
export interface PermissionClearResult {
|
|
407
|
+
cleared: string[];
|
|
408
|
+
}
|
|
409
|
+
//# sourceMappingURL=integration.d.ts.map
|