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.
Files changed (93) hide show
  1. package/LICENSE +21 -0
  2. package/dist/acp/agent.js +601 -0
  3. package/dist/acp/backend.js +2 -0
  4. package/dist/acp/config-options.js +26 -0
  5. package/dist/acp/mock-backend.js +277 -0
  6. package/dist/acp/sdk-backend.js +495 -0
  7. package/dist/browser/mcp-acp-client.js +81 -0
  8. package/dist/browser/provider.js +1045 -0
  9. package/dist/browser/schemas.js +221 -0
  10. package/dist/capability-registry.js +92 -0
  11. package/dist/client-heartbeat.js +118 -0
  12. package/dist/compose/schemas.js +90 -0
  13. package/dist/contacts/schemas.js +26 -0
  14. package/dist/installer/cli.js +70 -0
  15. package/dist/installer/common.js +93 -0
  16. package/dist/installer/index.js +341 -0
  17. package/dist/installer/mcp-clients.js +555 -0
  18. package/dist/installer/mcp.js +166 -0
  19. package/dist/installer/platforms.js +277 -0
  20. package/dist/logger.js +54 -0
  21. package/dist/mail/schemas.js +98 -0
  22. package/dist/mutation/schemas.js +31 -0
  23. package/dist/native-host/broker-ipc.js +344 -0
  24. package/dist/native-host/framing.js +76 -0
  25. package/dist/native-host/main.js +520 -0
  26. package/dist/native-host/mcp-server.js +322 -0
  27. package/dist/native-host/mcp-stdio-bridge.js +179 -0
  28. package/dist/native-host/mcp-stdio-main.js +13 -0
  29. package/dist/native-host/relay.js +84 -0
  30. package/dist/native-host/skills-startup.js +167 -0
  31. package/dist/native-host/transport.js +248 -0
  32. package/dist/permission-store.js +207 -0
  33. package/dist/repl/fs-sandbox.js +187 -0
  34. package/dist/repl/provider.js +252 -0
  35. package/dist/repl/runtime.js +436 -0
  36. package/dist/repl/types.js +10 -0
  37. package/dist/repl/worker.js +731 -0
  38. package/dist/skills/extension.js +99 -0
  39. package/dist/skills/grants-file.js +145 -0
  40. package/dist/skills/isolated-runner.js +259 -0
  41. package/dist/skills/mock-session-factory.js +49 -0
  42. package/dist/skills/package-roots.js +25 -0
  43. package/dist/skills/pi-bridge.js +8 -0
  44. package/dist/skills/pi-integration.js +110 -0
  45. package/dist/skills/planner.js +128 -0
  46. package/dist/skills/registry.js +104 -0
  47. package/dist/skills/skills-protocol.js +253 -0
  48. package/dist/skills/skills-service.js +195 -0
  49. package/dist/tool-bridge.js +8 -0
  50. package/dist/workspace.js +70 -0
  51. package/extensions/pi-browser-tools.ts +65 -0
  52. package/extensions/pi-browser.ts +60 -0
  53. package/extensions/pi-skills.ts +14 -0
  54. package/native/pi-agent-host +2 -0
  55. package/native/pi-browser-host +5 -0
  56. package/native/pi-browser-host.cmd +3 -0
  57. package/node_modules/@pi-browser/protocol/.bundled-by-trusted-user-agent +0 -0
  58. package/node_modules/@pi-browser/protocol/dist/acp.d.ts +10 -0
  59. package/node_modules/@pi-browser/protocol/dist/acp.js +9 -0
  60. package/node_modules/@pi-browser/protocol/dist/browser-tools.d.ts +33 -0
  61. package/node_modules/@pi-browser/protocol/dist/browser-tools.js +478 -0
  62. package/node_modules/@pi-browser/protocol/dist/callers.d.ts +108 -0
  63. package/node_modules/@pi-browser/protocol/dist/callers.js +56 -0
  64. package/node_modules/@pi-browser/protocol/dist/compose-tools.d.ts +30 -0
  65. package/node_modules/@pi-browser/protocol/dist/compose-tools.js +175 -0
  66. package/node_modules/@pi-browser/protocol/dist/contacts-tools.d.ts +23 -0
  67. package/node_modules/@pi-browser/protocol/dist/contacts-tools.js +63 -0
  68. package/node_modules/@pi-browser/protocol/dist/control-tools.d.ts +32 -0
  69. package/node_modules/@pi-browser/protocol/dist/control-tools.js +201 -0
  70. package/node_modules/@pi-browser/protocol/dist/errors.d.ts +63 -0
  71. package/node_modules/@pi-browser/protocol/dist/errors.js +109 -0
  72. package/node_modules/@pi-browser/protocol/dist/index.d.ts +16 -0
  73. package/node_modules/@pi-browser/protocol/dist/index.js +16 -0
  74. package/node_modules/@pi-browser/protocol/dist/integration.d.ts +409 -0
  75. package/node_modules/@pi-browser/protocol/dist/integration.js +260 -0
  76. package/node_modules/@pi-browser/protocol/dist/jsonrpc.d.ts +33 -0
  77. package/node_modules/@pi-browser/protocol/dist/jsonrpc.js +31 -0
  78. package/node_modules/@pi-browser/protocol/dist/mail-mutation-tools.d.ts +27 -0
  79. package/node_modules/@pi-browser/protocol/dist/mail-mutation-tools.js +88 -0
  80. package/node_modules/@pi-browser/protocol/dist/mail-tools.d.ts +133 -0
  81. package/node_modules/@pi-browser/protocol/dist/mail-tools.js +245 -0
  82. package/node_modules/@pi-browser/protocol/dist/permission.d.ts +113 -0
  83. package/node_modules/@pi-browser/protocol/dist/permission.js +257 -0
  84. package/node_modules/@pi-browser/protocol/dist/skills.d.ts +304 -0
  85. package/node_modules/@pi-browser/protocol/dist/skills.js +473 -0
  86. package/node_modules/@pi-browser/protocol/dist/tool-capabilities.d.ts +18 -0
  87. package/node_modules/@pi-browser/protocol/dist/tool-capabilities.js +52 -0
  88. package/node_modules/@pi-browser/protocol/dist/transport.d.ts +17 -0
  89. package/node_modules/@pi-browser/protocol/dist/transport.js +17 -0
  90. package/node_modules/@pi-browser/protocol/package.json +14 -0
  91. package/package.json +71 -6
  92. package/skills/browser-walk/SKILL.md +98 -0
  93. package/README.md +0 -3
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Draft-first Thunderbird compose tool definitions (THUNDERBIRD-PLAN §15–17, T3).
3
+ *
4
+ * These tools let the agent OPEN a populated compose window and READ/EDIT its
5
+ * fields, so the user can review it and press Send. They are deliberately
6
+ * NON-sending: there is no send/save-draft tool here — the user is the one who
7
+ * sends. The schemas are transport-neutral (same as the mail tools): the
8
+ * Thunderbird side implements them (compose-dispatcher) and the Pi side
9
+ * registers them as agent tools, gated on the "compose" capability.
10
+ *
11
+ * Safety model (plan §15, §21):
12
+ * - `compose_prepare_*` open a compose window pre-filled; the user reviews it.
13
+ * - `compose_get`/`compose_update` read/edit an already-open window.
14
+ * - No `sendMessage` / `saveMessage` is exposed, so nothing can be sent by the
15
+ * agent. Recipients are mailbox strings; the body is HTML.
16
+ */
17
+ export interface ComposeToolDef {
18
+ name: string;
19
+ description: string;
20
+ /** JSON Schema (draft-07 compatible) for the tool arguments. */
21
+ inputSchema: Record<string, unknown>;
22
+ /** compose_get is read-only; the prepare/update tools mutate the compose window. */
23
+ readOnly: boolean;
24
+ }
25
+ export declare const COMPOSE_TOOLS: readonly ComposeToolDef[];
26
+ export declare function getComposeTool(name: string): ComposeToolDef | undefined;
27
+ export declare function isComposeTool(name: string): boolean;
28
+ export declare const COMPOSE_TOOL_NAMES: readonly string[];
29
+ export declare const COMPOSE_TOOL_TIMEOUT_MS = 30000;
30
+ //# sourceMappingURL=compose-tools.d.ts.map
@@ -0,0 +1,175 @@
1
+ /**
2
+ * Draft-first Thunderbird compose tool definitions (THUNDERBIRD-PLAN §15–17, T3).
3
+ *
4
+ * These tools let the agent OPEN a populated compose window and READ/EDIT its
5
+ * fields, so the user can review it and press Send. They are deliberately
6
+ * NON-sending: there is no send/save-draft tool here — the user is the one who
7
+ * sends. The schemas are transport-neutral (same as the mail tools): the
8
+ * Thunderbird side implements them (compose-dispatcher) and the Pi side
9
+ * registers them as agent tools, gated on the "compose" capability.
10
+ *
11
+ * Safety model (plan §15, §21):
12
+ * - `compose_prepare_*` open a compose window pre-filled; the user reviews it.
13
+ * - `compose_get`/`compose_update` read/edit an already-open window.
14
+ * - No `sendMessage` / `saveMessage` is exposed, so nothing can be sent by the
15
+ * agent. Recipients are mailbox strings; the body is HTML.
16
+ */
17
+ const OBJECT_SCHEMA_BASE = {
18
+ type: "object",
19
+ additionalProperties: false,
20
+ };
21
+ const composeTabId = {
22
+ type: "number",
23
+ description: "Compose window tab id, returned by the compose_prepare_* tools; identifies the window to read or update.",
24
+ };
25
+ const messageIdProp = {
26
+ type: "number",
27
+ description: "Thunderbird numeric message id of the message to reply/forward (from the current context or a search result). Transient: valid only within the current session.",
28
+ };
29
+ const toProp = {
30
+ type: "string",
31
+ description: 'Recipients in mailbox format ("Name <a@example.com>" or just "a@example.com"); separate several with commas.',
32
+ };
33
+ const ccProp = { type: "string", description: 'CC recipients in mailbox format ("Name <a@example.com>"), comma-separated.' };
34
+ const bccProp = { type: "string", description: 'BCC recipients in mailbox format ("Name <a@example.com>"), comma-separated.' };
35
+ const subjectProp = { type: "string", description: "The message subject line." };
36
+ const bodyProp = { type: "string", description: "The message body (HTML)." };
37
+ const contentTypeUnion = {
38
+ anyOf: [
39
+ { type: "string", const: "text/html" },
40
+ { type: "string", const: "text/plain" },
41
+ ],
42
+ description: "Body MIME type (default text/html).",
43
+ };
44
+ const replyTypeUnion = {
45
+ anyOf: [
46
+ { type: "string", const: "replyToSender" },
47
+ { type: "string", const: "replyToList" },
48
+ { type: "string", const: "replyToAll" },
49
+ ],
50
+ description: "Who the reply is addressed to (default replyToSender).",
51
+ };
52
+ const forwardTypeUnion = {
53
+ anyOf: [
54
+ { type: "string", const: "forwardInline" },
55
+ { type: "string", const: "forwardAsAttachment" },
56
+ ],
57
+ description: "How the message is forwarded (default forwardInline).",
58
+ };
59
+ const attachmentNameProp = {
60
+ type: "string",
61
+ description: 'The attachment filename, e.g. "report.pdf".',
62
+ };
63
+ const attachmentContentProp = {
64
+ type: "string",
65
+ description: "The file content, base64-encoded.",
66
+ };
67
+ const attachmentContentTypeProp = {
68
+ type: "string",
69
+ description: 'The MIME type, e.g. "application/pdf" (default application/octet-stream).',
70
+ };
71
+ export const COMPOSE_TOOLS = [
72
+ {
73
+ name: "compose_prepare_new",
74
+ description: "Open a NEW message compose window pre-filled with the given recipients, subject, and body. The window opens for the user to review and send; this tool does not send.",
75
+ inputSchema: {
76
+ ...OBJECT_SCHEMA_BASE,
77
+ properties: {
78
+ to: toProp,
79
+ cc: ccProp,
80
+ bcc: bccProp,
81
+ subject: subjectProp,
82
+ body: bodyProp,
83
+ contentType: contentTypeUnion,
84
+ },
85
+ },
86
+ readOnly: false,
87
+ },
88
+ {
89
+ name: "compose_prepare_reply",
90
+ description: "Open a REPLY compose window for a message, pre-filled with the reply. The recipient is derived from the message; the window opens for the user to review and send. This tool does not send.",
91
+ inputSchema: {
92
+ ...OBJECT_SCHEMA_BASE,
93
+ properties: {
94
+ messageId: messageIdProp,
95
+ replyType: replyTypeUnion,
96
+ cc: ccProp,
97
+ bcc: bccProp,
98
+ subject: subjectProp,
99
+ body: bodyProp,
100
+ },
101
+ required: ["messageId"],
102
+ },
103
+ readOnly: false,
104
+ },
105
+ {
106
+ name: "compose_prepare_forward",
107
+ description: "Open a FORWARD compose window for a message, pre-filled with the forwarding. The window opens for the user to review and send. This tool does not send.",
108
+ inputSchema: {
109
+ ...OBJECT_SCHEMA_BASE,
110
+ properties: {
111
+ messageId: messageIdProp,
112
+ forwardType: forwardTypeUnion,
113
+ to: toProp,
114
+ cc: ccProp,
115
+ bcc: bccProp,
116
+ subject: subjectProp,
117
+ body: bodyProp,
118
+ },
119
+ required: ["messageId"],
120
+ },
121
+ readOnly: false,
122
+ },
123
+ {
124
+ name: "compose_get",
125
+ description: "Read the current fields (recipients, subject, body) of a compose window opened by the compose_prepare_* tools.",
126
+ inputSchema: {
127
+ ...OBJECT_SCHEMA_BASE,
128
+ properties: { tabId: composeTabId },
129
+ required: ["tabId"],
130
+ },
131
+ readOnly: true,
132
+ },
133
+ {
134
+ name: "compose_update",
135
+ description: "Update the fields of an open compose window (recipients, subject, body). The window stays open for the user to review and send; this tool does not send.",
136
+ inputSchema: {
137
+ ...OBJECT_SCHEMA_BASE,
138
+ properties: {
139
+ tabId: composeTabId,
140
+ to: toProp,
141
+ cc: ccProp,
142
+ bcc: bccProp,
143
+ subject: subjectProp,
144
+ body: bodyProp,
145
+ contentType: contentTypeUnion,
146
+ },
147
+ required: ["tabId"],
148
+ },
149
+ readOnly: false,
150
+ },
151
+ {
152
+ name: "compose_add_attachment",
153
+ description: "Attach a file to an open compose window (give its base64 content, a filename, and a MIME type). The window stays open for the user to review and send; this tool does not send.",
154
+ inputSchema: {
155
+ ...OBJECT_SCHEMA_BASE,
156
+ properties: {
157
+ tabId: composeTabId,
158
+ name: attachmentNameProp,
159
+ content: attachmentContentProp,
160
+ contentType: attachmentContentTypeProp,
161
+ },
162
+ required: ["tabId", "name", "content"],
163
+ },
164
+ readOnly: false,
165
+ },
166
+ ];
167
+ export function getComposeTool(name) {
168
+ return COMPOSE_TOOLS.find((t) => t.name === name);
169
+ }
170
+ export function isComposeTool(name) {
171
+ return COMPOSE_TOOLS.some((t) => t.name === name);
172
+ }
173
+ export const COMPOSE_TOOL_NAMES = COMPOSE_TOOLS.map((t) => t.name);
174
+ export const COMPOSE_TOOL_TIMEOUT_MS = 30_000;
175
+ //# sourceMappingURL=compose-tools.js.map
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Thunderbird contacts (address book) tool definitions (THUNDERBIRD-PLAN.md §41, T6).
3
+ *
4
+ * Read-only. Lets the agent resolve a recipient from the address book, e.g.
5
+ * "Draft a message to Sarah from Acme." Contact data is untrusted external data
6
+ * (plan §31–32): it is tool output only and never merged into the user prompt.
7
+ *
8
+ * Gated on the `contacts` capability; the add-on declares the `addressBooks`
9
+ * permission (read). There are no contacts mutation tools (create/update/delete).
10
+ */
11
+ export interface ContactsToolDef {
12
+ name: string;
13
+ description: string;
14
+ inputSchema: Record<string, unknown>;
15
+ /** Both contacts tools are read-only. */
16
+ readOnly: boolean;
17
+ }
18
+ export declare const CONTACTS_TOOLS: readonly ContactsToolDef[];
19
+ export declare function getContactsTool(name: string): ContactsToolDef | undefined;
20
+ export declare function isContactsTool(name: string): boolean;
21
+ export declare const CONTACTS_TOOL_NAMES: readonly string[];
22
+ export declare const CONTACTS_TOOL_TIMEOUT_MS = 30000;
23
+ //# sourceMappingURL=contacts-tools.d.ts.map
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Thunderbird contacts (address book) tool definitions (THUNDERBIRD-PLAN.md §41, T6).
3
+ *
4
+ * Read-only. Lets the agent resolve a recipient from the address book, e.g.
5
+ * "Draft a message to Sarah from Acme." Contact data is untrusted external data
6
+ * (plan §31–32): it is tool output only and never merged into the user prompt.
7
+ *
8
+ * Gated on the `contacts` capability; the add-on declares the `addressBooks`
9
+ * permission (read). There are no contacts mutation tools (create/update/delete).
10
+ */
11
+ const OBJECT_SCHEMA_BASE = {
12
+ type: "object",
13
+ additionalProperties: false,
14
+ };
15
+ export const CONTACTS_TOOLS = [
16
+ {
17
+ name: "contacts_search",
18
+ description: "Search the address book by name, email, or organization (e.g. \"Sarah Acme\"). Returns normalized contacts (id, name, emails, organization) plus the raw properties (all card fields).",
19
+ inputSchema: {
20
+ ...OBJECT_SCHEMA_BASE,
21
+ properties: {
22
+ query: { type: "string", description: "One or more space-separated search terms." },
23
+ limit: { type: "number", description: "Maximum number of results to return (default 10)." },
24
+ },
25
+ required: ["query"],
26
+ },
27
+ readOnly: true,
28
+ },
29
+ {
30
+ name: "contacts_list",
31
+ description: "List address-book contacts with optional filtering and pagination. Use for \"who's in my address book\" / browsing; contacts_search is a faster indexed lookup by term. Returns { contacts, count, total, cursor, nextCursor }; each contact includes its raw properties.",
32
+ inputSchema: {
33
+ ...OBJECT_SCHEMA_BASE,
34
+ properties: {
35
+ filter: { type: "string", description: "Only contacts whose name, email, or organization contains this (case-insensitive)." },
36
+ limit: { type: "number", description: "Maximum contacts per page (default 10, max 50)." },
37
+ cursor: { type: "number", description: "Offset into the full (filtered) list for pagination; pass the previous nextCursor." },
38
+ },
39
+ },
40
+ readOnly: true,
41
+ },
42
+ {
43
+ name: "contacts_get",
44
+ description: "Get a single contact by its id (from a contacts_search result). Returns the contact (name, emails, organization) plus the raw properties (all card fields).",
45
+ inputSchema: {
46
+ ...OBJECT_SCHEMA_BASE,
47
+ properties: {
48
+ contactId: { type: "string", description: "The contact id (cardKey) from a contacts_search result." },
49
+ },
50
+ required: ["contactId"],
51
+ },
52
+ readOnly: true,
53
+ },
54
+ ];
55
+ export function getContactsTool(name) {
56
+ return CONTACTS_TOOLS.find((t) => t.name === name);
57
+ }
58
+ export function isContactsTool(name) {
59
+ return CONTACTS_TOOLS.some((t) => t.name === name);
60
+ }
61
+ export const CONTACTS_TOOL_NAMES = CONTACTS_TOOLS.map((t) => t.name);
62
+ export const CONTACTS_TOOL_TIMEOUT_MS = 30_000;
63
+ //# sourceMappingURL=contacts-tools.js.map
@@ -0,0 +1,32 @@
1
+ /**
2
+ * MCP-compatible Pi session control tool definitions (PRODUCT.md §26, Phase 5).
3
+ *
4
+ * Complement to BROWSER_TOOLS: browser tools operate the session's bound
5
+ * tab, control tools operate the add-on's Pi session surface (lifecycle,
6
+ * tab binding, state). Like browser tools they are:
7
+ *
8
+ * - served by the Firefox add-on through its MCP server on the
9
+ * ACP channel (same tools/list + tools/call surface),
10
+ * - invoked only by the Pi agent through the native host — a web page
11
+ * can never call them (§49 invariant 4),
12
+ * - transport-independent: identical names, arguments, and results on
13
+ * every BrowserToolTransport.
14
+ *
15
+ * Every argument carries an explicit sessionId (or targets the bound tab
16
+ * of one); there is never a silent fallback to another session or tab
17
+ * (§49 invariant 5).
18
+ */
19
+ export interface ControlToolDef {
20
+ name: string;
21
+ description: string;
22
+ /** JSON Schema (draft-07 compatible) for the tool arguments. */
23
+ inputSchema: Record<string, unknown>;
24
+ /** Read-only tools only report state; mutating tools change sessions/binding. */
25
+ readOnly: boolean;
26
+ }
27
+ export declare const CONTROL_TOOLS: readonly ControlToolDef[];
28
+ export declare function getControlTool(name: string): ControlToolDef | undefined;
29
+ export declare function isControlTool(name: string): boolean;
30
+ export declare function isMutatingControlTool(name: string): boolean;
31
+ export declare const CONTROL_TOOL_NAMES: readonly string[];
32
+ //# sourceMappingURL=control-tools.d.ts.map
@@ -0,0 +1,201 @@
1
+ /**
2
+ * MCP-compatible Pi session control tool definitions (PRODUCT.md §26, Phase 5).
3
+ *
4
+ * Complement to BROWSER_TOOLS: browser tools operate the session's bound
5
+ * tab, control tools operate the add-on's Pi session surface (lifecycle,
6
+ * tab binding, state). Like browser tools they are:
7
+ *
8
+ * - served by the Firefox add-on through its MCP server on the
9
+ * ACP channel (same tools/list + tools/call surface),
10
+ * - invoked only by the Pi agent through the native host — a web page
11
+ * can never call them (§49 invariant 4),
12
+ * - transport-independent: identical names, arguments, and results on
13
+ * every BrowserToolTransport.
14
+ *
15
+ * Every argument carries an explicit sessionId (or targets the bound tab
16
+ * of one); there is never a silent fallback to another session or tab
17
+ * (§49 invariant 5).
18
+ */
19
+ const OBJECT_SCHEMA_BASE = {
20
+ type: "object",
21
+ additionalProperties: false,
22
+ };
23
+ const SESSION_ID = {
24
+ type: "string",
25
+ description: "ACP session id (e.g. from pi_get_state).",
26
+ };
27
+ export const CONTROL_TOOLS = [
28
+ {
29
+ name: "pi_get_state",
30
+ description: "Get the state of the Pi Browser integration: connection status, the known Pi sessions " +
31
+ "(id, title, cwd, streaming flag, config options, bound tab) and the currently active session.",
32
+ inputSchema: { ...OBJECT_SCHEMA_BASE, properties: {} },
33
+ readOnly: true,
34
+ },
35
+ {
36
+ name: "pi_new_session",
37
+ description: "Create a new Pi session (ACP session/new) with the given working directory. " +
38
+ "Returns the new session id. The session immediately has the browser tools available " +
39
+ "once a tab is bound to it.",
40
+ inputSchema: {
41
+ ...OBJECT_SCHEMA_BASE,
42
+ properties: {
43
+ cwd: { type: "string", description: "Working directory for the new session (absolute path)." },
44
+ },
45
+ required: ["cwd"],
46
+ },
47
+ readOnly: false,
48
+ },
49
+ {
50
+ name: "pi_select_session",
51
+ description: "Make a Pi session the active one in the Firefox sidebar. Loads (or re-resumes) its " +
52
+ "transcript on the host. Use before prompting a session that is not currently active.",
53
+ inputSchema: {
54
+ ...OBJECT_SCHEMA_BASE,
55
+ properties: { sessionId: SESSION_ID },
56
+ required: ["sessionId"],
57
+ },
58
+ readOnly: false,
59
+ },
60
+ {
61
+ name: "pi_prompt",
62
+ description: "Send a prompt to a Pi session (ACP session/prompt). Returns immediately with " +
63
+ "{accepted: true}; the turn then streams via session updates. Poll pi_get_state " +
64
+ "(streaming flag) or wait for the turn to finish.",
65
+ inputSchema: {
66
+ ...OBJECT_SCHEMA_BASE,
67
+ properties: {
68
+ sessionId: SESSION_ID,
69
+ text: { type: "string", description: "Prompt text." },
70
+ },
71
+ required: ["sessionId", "text"],
72
+ },
73
+ readOnly: false,
74
+ },
75
+ {
76
+ name: "pi_cancel",
77
+ description: "Cancel the currently streaming turn of a Pi session (ACP session/cancel).",
78
+ inputSchema: {
79
+ ...OBJECT_SCHEMA_BASE,
80
+ properties: { sessionId: SESSION_ID },
81
+ required: ["sessionId"],
82
+ },
83
+ readOnly: false,
84
+ },
85
+ {
86
+ name: "pi_close_session",
87
+ description: "Close a Pi session on the host (ACP session/close). It can be resumed later.",
88
+ inputSchema: {
89
+ ...OBJECT_SCHEMA_BASE,
90
+ properties: { sessionId: SESSION_ID },
91
+ required: ["sessionId"],
92
+ },
93
+ readOnly: false,
94
+ },
95
+ {
96
+ name: "pi_set_config_option",
97
+ description: "Set a session config option (ACP session/set_config_option), e.g. configId \"model\" or " +
98
+ "\"thinking\" with a value id reported by pi_get_state.",
99
+ inputSchema: {
100
+ ...OBJECT_SCHEMA_BASE,
101
+ properties: {
102
+ sessionId: SESSION_ID,
103
+ configId: { type: "string", description: "Config option id, e.g. \"model\" or \"thinking\"." },
104
+ value: {
105
+ anyOf: [{ type: "string" }, { type: "boolean" }],
106
+ description: "Value id (string) or flag (boolean) for the option.",
107
+ },
108
+ },
109
+ required: ["sessionId", "configId", "value"],
110
+ },
111
+ readOnly: false,
112
+ },
113
+ {
114
+ name: "pi_bind_current_tab",
115
+ description: "Bind the currently active Firefox tab to a Pi session. After this, the session's " +
116
+ "browser tools (browser_get_page, browser_click, ...) operate on that tab only.",
117
+ inputSchema: {
118
+ ...OBJECT_SCHEMA_BASE,
119
+ properties: { sessionId: SESSION_ID },
120
+ required: ["sessionId"],
121
+ },
122
+ readOnly: false,
123
+ },
124
+ {
125
+ name: "pi_bind_tab",
126
+ description: "Bind an existing Firefox tab to a Pi session: the session's browser tools (browser_get_page, " +
127
+ "browser_click, ...) operate on that tab. The tab id comes from pi_list_tabs. Replaces the " +
128
+ "session's current binding and releases the tab from any other session bound to it.",
129
+ inputSchema: {
130
+ ...OBJECT_SCHEMA_BASE,
131
+ properties: {
132
+ sessionId: SESSION_ID,
133
+ tabId: { type: "number", description: "Firefox tab id (from pi_list_tabs)." },
134
+ },
135
+ required: ["sessionId", "tabId"],
136
+ },
137
+ readOnly: false,
138
+ },
139
+ {
140
+ name: "pi_open_tab",
141
+ description: "Open a new browser tab at the given URL and bind the session to it — works even when the " +
142
+ "session has no bound tab. The new tab is owned by the session and closed automatically when " +
143
+ "the session unbinds; the previously bound tab (if any) stays open and is restored when the " +
144
+ "new tab is closed. Returns {tabId, url}.",
145
+ inputSchema: {
146
+ ...OBJECT_SCHEMA_BASE,
147
+ properties: {
148
+ sessionId: SESSION_ID,
149
+ url: { type: "string", description: 'URL for the new tab, e.g. "https://example.com".' },
150
+ },
151
+ required: ["sessionId", "url"],
152
+ },
153
+ readOnly: false,
154
+ },
155
+ {
156
+ name: "pi_list_tabs",
157
+ description: "List all open Firefox tabs: {tabs: [{id, url, title, bound}]} — bound marks the session's " +
158
+ "current tab. Use with pi_bind_tab to bind a specific tab. Works without a bound tab " +
159
+ "(unlike browser_list_tabs).",
160
+ inputSchema: {
161
+ ...OBJECT_SCHEMA_BASE,
162
+ properties: { sessionId: SESSION_ID },
163
+ required: ["sessionId"],
164
+ },
165
+ readOnly: true,
166
+ },
167
+ {
168
+ name: "pi_unbind_tab",
169
+ description: "Remove the tab binding of a Pi session; its browser tools fail until re-bound.",
170
+ inputSchema: {
171
+ ...OBJECT_SCHEMA_BASE,
172
+ properties: { sessionId: SESSION_ID },
173
+ required: ["sessionId"],
174
+ },
175
+ readOnly: false,
176
+ },
177
+ {
178
+ name: "pi_open_bound_tab",
179
+ description: "Activate the tab bound to a Pi session (focus its window and make the tab visible). " +
180
+ "Use before browser_screenshot, which can only capture the visible tab.",
181
+ inputSchema: {
182
+ ...OBJECT_SCHEMA_BASE,
183
+ properties: { sessionId: SESSION_ID },
184
+ required: ["sessionId"],
185
+ },
186
+ readOnly: false,
187
+ },
188
+ ];
189
+ const TOOL_BY_NAME = new Map(CONTROL_TOOLS.map((t) => [t.name, t]));
190
+ export function getControlTool(name) {
191
+ return TOOL_BY_NAME.get(name);
192
+ }
193
+ export function isControlTool(name) {
194
+ return TOOL_BY_NAME.has(name);
195
+ }
196
+ export function isMutatingControlTool(name) {
197
+ const tool = TOOL_BY_NAME.get(name);
198
+ return tool !== undefined && !tool.readOnly;
199
+ }
200
+ export const CONTROL_TOOL_NAMES = CONTROL_TOOLS.map((t) => t.name);
201
+ //# sourceMappingURL=control-tools.js.map
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Structured integration errors (PRODUCT.md §44).
3
+ *
4
+ * Neither side of the link may rely on parsing human-readable error
5
+ * strings. Every protocol-level failure carries a stable code, mapped to a
6
+ * dedicated JSON-RPC application error code (-320xx) and echoed in
7
+ * `error.data.code` for readability.
8
+ */
9
+ import type { JsonRpcErrorObject } from "./jsonrpc.js";
10
+ export declare const PI_BROWSER_ERROR: {
11
+ readonly NATIVE_HOST_NOT_INSTALLED: "NATIVE_HOST_NOT_INSTALLED";
12
+ readonly NATIVE_HOST_VERSION_MISMATCH: "NATIVE_HOST_VERSION_MISMATCH";
13
+ readonly PI_NOT_FOUND: "PI_NOT_FOUND";
14
+ readonly PI_START_FAILED: "PI_START_FAILED";
15
+ readonly ACP_INITIALIZATION_FAILED: "ACP_INITIALIZATION_FAILED";
16
+ readonly ACP_CAPABILITY_UNSUPPORTED: "ACP_CAPABILITY_UNSUPPORTED";
17
+ readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
18
+ readonly SESSION_BUSY: "SESSION_BUSY";
19
+ readonly BROWSER_NOT_BOUND: "BROWSER_NOT_BOUND";
20
+ readonly BROWSER_TAB_CLOSED: "BROWSER_TAB_CLOSED";
21
+ readonly BROWSER_FRAME_NOT_FOUND: "BROWSER_FRAME_NOT_FOUND";
22
+ readonly BROWSER_PERMISSION_DENIED: "BROWSER_PERMISSION_DENIED";
23
+ readonly BROWSER_ELEMENT_STALE: "BROWSER_ELEMENT_STALE";
24
+ readonly BROWSER_TOOL_TIMEOUT: "BROWSER_TOOL_TIMEOUT";
25
+ readonly BROWSER_DOWNLOAD_TOO_LARGE: "BROWSER_DOWNLOAD_TOO_LARGE";
26
+ readonly MCP_UNAVAILABLE: "MCP_UNAVAILABLE";
27
+ readonly MCP_TOOL_NOT_FOUND: "MCP_TOOL_NOT_FOUND";
28
+ readonly PROTOCOL_VERSION_MISMATCH: "PROTOCOL_VERSION_MISMATCH";
29
+ readonly INTERNAL: "INTERNAL";
30
+ readonly MAIL_NO_CONTEXT: "MAIL_NO_CONTEXT";
31
+ readonly MAIL_MESSAGE_NOT_FOUND: "MAIL_MESSAGE_NOT_FOUND";
32
+ readonly MAIL_ATTACHMENT_NOT_FOUND: "MAIL_ATTACHMENT_NOT_FOUND";
33
+ readonly MAIL_CURSOR_EXPIRED: "MAIL_CURSOR_EXPIRED";
34
+ };
35
+ export type PiBrowserErrorCode = (typeof PI_BROWSER_ERROR)[keyof typeof PI_BROWSER_ERROR];
36
+ export declare const PI_BROWSER_ERROR_CODES: ReadonlyMap<PiBrowserErrorCode, number>;
37
+ export declare function isPiBrowserErrorCode(value: unknown): value is PiBrowserErrorCode;
38
+ /** JSON-RPC numeric code for a Pi Browser error code. */
39
+ export declare function piBrowserErrorNumeric(code: PiBrowserErrorCode): number;
40
+ /** Build a JSON-RPC error object carrying a structured Pi Browser code. */
41
+ export declare function toErrorObject(code: PiBrowserErrorCode, message: string, data?: unknown): JsonRpcErrorObject;
42
+ /**
43
+ * Recover the structured code from a JSON-RPC error object. Prefers the
44
+ * explicit `data.piBrowserError` string, falls back to the reserved numeric
45
+ * range, returns undefined for plain JSON-RPC/protocol errors.
46
+ */
47
+ export declare function codeFromErrorObject(err: JsonRpcErrorObject | undefined | null): PiBrowserErrorCode | undefined;
48
+ /** Error type used internally on both sides of the link. */
49
+ export declare class PiBrowserProtocolError extends Error {
50
+ readonly code: PiBrowserErrorCode;
51
+ readonly data?: unknown | undefined;
52
+ constructor(code: PiBrowserErrorCode, message: string, data?: unknown | undefined);
53
+ toErrorObject(): JsonRpcErrorObject;
54
+ }
55
+ /** Standard JSON-RPC error codes for protocol-level (non-Pi-Browser) failures. */
56
+ export declare const JSONRPC_ERROR: {
57
+ readonly PARSE: -32700;
58
+ readonly INVALID_REQUEST: -32600;
59
+ readonly METHOD_NOT_FOUND: -32601;
60
+ readonly INVALID_PARAMS: -32602;
61
+ readonly INTERNAL: -32603;
62
+ };
63
+ //# sourceMappingURL=errors.d.ts.map