@picassohq/cli 0.0.0-stage → 1.0.2

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 (232) hide show
  1. package/agents/browser_agent.yaml +53 -0
  2. package/agents/code_reviewer.yaml +49 -0
  3. package/agents/codebase_investigator.yaml +70 -0
  4. package/agents/design_auditor.yaml +50 -0
  5. package/agents/devex_auditor.yaml +50 -0
  6. package/agents/doc_writer.yaml +54 -0
  7. package/agents/engineering_architect.yaml +51 -0
  8. package/agents/generalist.yaml +55 -0
  9. package/agents/migration_planner.yaml +51 -0
  10. package/agents/product_reviewer.yaml +48 -0
  11. package/agents/qa_operator.yaml +52 -0
  12. package/agents/release_engineer.yaml +50 -0
  13. package/agents/security_auditor.yaml +62 -0
  14. package/agents/test_writer.yaml +52 -0
  15. package/assets/first-light-lockup.png +0 -0
  16. package/assets/first-light-tagline.png +0 -0
  17. package/assets/house/README.md +26 -0
  18. package/assets/house/auraone-banner.png +0 -0
  19. package/assets/house/auraone-logo.png +0 -0
  20. package/assets/house/kiro-prism-banner.png +0 -0
  21. package/assets/house/kiro-prism-logo.png +0 -0
  22. package/assets/house/picasso-banner.png +0 -0
  23. package/assets/house/picasso-logo.png +0 -0
  24. package/assets/wordmark-app.png +0 -0
  25. package/assets/wordmark-tight.png +0 -0
  26. package/assets/wordmark.png +0 -0
  27. package/design/styles.css +1042 -0
  28. package/dist/build-info.json +37 -0
  29. package/dist/index.js +3062 -0
  30. package/goals/cli-hardening.yaml +40 -0
  31. package/goals/repo-maintenance.yaml +40 -0
  32. package/package.json +49 -4
  33. package/runtime/dsh/picasso-ecosystem.community.amendments.yml +24 -0
  34. package/runtime/dsh/picasso-ecosystem.community.json +185 -0
  35. package/runtime/dsh/picasso-ecosystem.community.patch.yml +40 -0
  36. package/runtime/dsh/picasso-ecosystem.cordis.patch.yml +143 -0
  37. package/runtime/dsh/picasso-isolation.patch.yml +25 -0
  38. package/runtime/dsh/picasso-providers.patch.yml +373 -0
  39. package/runtime/dsh/picasso-runtime.cordis.yml +738 -0
  40. package/runtime/dsh/picasso-sdk.patch.yml +204 -0
  41. package/runtime/engine-manifest.json +215 -0
  42. package/runtime/package.json +6 -0
  43. package/runtime/packages/picasso-cache-probe/cordis.patch.yml +5 -0
  44. package/runtime/packages/picasso-cache-probe/index.js +477 -0
  45. package/runtime/packages/picasso-cache-probe/package.json +38 -0
  46. package/runtime/packages/picasso-commands/cordis.patch.yml +4 -0
  47. package/runtime/packages/picasso-commands/fresh-review.js +573 -0
  48. package/runtime/packages/picasso-commands/index.js +497 -0
  49. package/runtime/packages/picasso-commands/package.json +28 -0
  50. package/runtime/packages/picasso-instructions/conflicts.js +115 -0
  51. package/runtime/packages/picasso-instructions/formats.js +145 -0
  52. package/runtime/packages/picasso-instructions/frontmatter.js +175 -0
  53. package/runtime/packages/picasso-instructions/glob.js +114 -0
  54. package/runtime/packages/picasso-instructions/globals.js +90 -0
  55. package/runtime/packages/picasso-instructions/imports.js +123 -0
  56. package/runtime/packages/picasso-instructions/index.js +326 -0
  57. package/runtime/packages/picasso-instructions/modes.js +64 -0
  58. package/runtime/packages/picasso-instructions/package.json +30 -0
  59. package/runtime/packages/picasso-instructions/parse.js +134 -0
  60. package/runtime/packages/picasso-instructions/report.js +161 -0
  61. package/runtime/packages/picasso-instructions/resolve.js +939 -0
  62. package/runtime/packages/picasso-instructions/scan.js +181 -0
  63. package/runtime/packages/picasso-instructions/settings.js +150 -0
  64. package/runtime/packages/picasso-instructions/skills.js +345 -0
  65. package/runtime/packages/picasso-lean-context/cordis.patch.yml +13 -0
  66. package/runtime/packages/picasso-lean-context/index.js +6280 -0
  67. package/runtime/packages/picasso-lean-context/package.json +26 -0
  68. package/runtime/packages/picasso-lean-context/read-image-recovery.js +306 -0
  69. package/runtime/packages/picasso-lean-context/timeline.js +418 -0
  70. package/runtime/packages/picasso-librarian/classify.js +146 -0
  71. package/runtime/packages/picasso-librarian/cordis.patch.yml +10 -0
  72. package/runtime/packages/picasso-librarian/index.js +878 -0
  73. package/runtime/packages/picasso-librarian/notes.js +159 -0
  74. package/runtime/packages/picasso-librarian/package.json +34 -0
  75. package/runtime/packages/picasso-librarian/state.js +478 -0
  76. package/runtime/packages/picasso-memory/index.js +1184 -0
  77. package/runtime/packages/picasso-memory/package.json +21 -0
  78. package/runtime/packages/picasso-model-router/connections.js +912 -0
  79. package/runtime/packages/picasso-model-router/cordis.patch.yml +17 -0
  80. package/runtime/packages/picasso-model-router/index.js +1083 -0
  81. package/runtime/packages/picasso-model-router/package.json +30 -0
  82. package/runtime/packages/picasso-options/cordis.patch.yml +4 -0
  83. package/runtime/packages/picasso-options/index.js +263 -0
  84. package/runtime/packages/picasso-options/package.json +28 -0
  85. package/runtime/packages/picasso-progress-reports/cordis.patch.yml +10 -0
  86. package/runtime/packages/picasso-progress-reports/index.js +267 -0
  87. package/runtime/packages/picasso-progress-reports/package.json +30 -0
  88. package/runtime/packages/picasso-progress-reports/report.js +235 -0
  89. package/runtime/packages/picasso-sdk-server/aside.js +142 -0
  90. package/runtime/packages/picasso-sdk-server/connections.js +38 -0
  91. package/runtime/packages/picasso-sdk-server/context-timeline.js +27 -0
  92. package/runtime/packages/picasso-sdk-server/egress-gate.js +520 -0
  93. package/runtime/packages/picasso-sdk-server/failure-policy.js +246 -0
  94. package/runtime/packages/picasso-sdk-server/file-input.js +169 -0
  95. package/runtime/packages/picasso-sdk-server/goal.js +131 -0
  96. package/runtime/packages/picasso-sdk-server/ignore-file.js +458 -0
  97. package/runtime/packages/picasso-sdk-server/ignore-plugin.js +12 -0
  98. package/runtime/packages/picasso-sdk-server/ignore-sandbox.js +122 -0
  99. package/runtime/packages/picasso-sdk-server/ignore-snapshot.js +131 -0
  100. package/runtime/packages/picasso-sdk-server/image-input.js +44 -0
  101. package/runtime/packages/picasso-sdk-server/index.js +891 -0
  102. package/runtime/packages/picasso-sdk-server/instructions.js +34 -0
  103. package/runtime/packages/picasso-sdk-server/jobs.js +113 -0
  104. package/runtime/packages/picasso-sdk-server/mcp-gate.js +51 -0
  105. package/runtime/packages/picasso-sdk-server/model-selection.js +162 -0
  106. package/runtime/packages/picasso-sdk-server/package.json +50 -0
  107. package/runtime/packages/picasso-sdk-server/picasso-records.js +50 -0
  108. package/runtime/packages/picasso-sdk-server/provider-reload.js +84 -0
  109. package/runtime/packages/picasso-sdk-server/queue.js +322 -0
  110. package/runtime/packages/picasso-sdk-server/requester.js +43 -0
  111. package/runtime/packages/picasso-sdk-server/rewind.js +108 -0
  112. package/runtime/packages/picasso-sdk-server/schedule.js +187 -0
  113. package/runtime/packages/picasso-sdk-server/session-grants.js +35 -0
  114. package/runtime/packages/picasso-sdk-server/session-state.js +118 -0
  115. package/runtime/packages/picasso-sdk-server/shell-paths.js +869 -0
  116. package/runtime/packages/picasso-sdk-server/stream-deltas.js +211 -0
  117. package/runtime/packages/picasso-sdk-server/team-tasks.js +451 -0
  118. package/runtime/packages/picasso-sdk-server/tool-output.js +128 -0
  119. package/runtime/packages/picasso-sdk-server/tools-list.js +51 -0
  120. package/runtime/packages/picasso-sdk-server/wave2-hooks.js +612 -0
  121. package/runtime/packages/picasso-sdk-server/workspace-archive.js +170 -0
  122. package/runtime/packages/picasso-sdk-server/workspace-restore.js +180 -0
  123. package/runtime/packages/picasso-web-search/backends.js +412 -0
  124. package/runtime/packages/picasso-web-search/config.js +121 -0
  125. package/runtime/packages/picasso-web-search/cordis.patch.yml +7 -0
  126. package/runtime/packages/picasso-web-search/failure.js +116 -0
  127. package/runtime/packages/picasso-web-search/format.js +42 -0
  128. package/runtime/packages/picasso-web-search/index.js +71 -0
  129. package/runtime/packages/picasso-web-search/package.json +38 -0
  130. package/runtime/packages/picasso-web-search/router.js +156 -0
  131. package/runtime/packages/picasso-x-reader/circle.js +324 -0
  132. package/runtime/packages/picasso-x-reader/command.js +169 -0
  133. package/runtime/packages/picasso-x-reader/cordis.patch.yml +8 -0
  134. package/runtime/packages/picasso-x-reader/index.js +170 -0
  135. package/runtime/packages/picasso-x-reader/package.json +39 -0
  136. package/runtime/packages/picasso-x-reader/read.js +370 -0
  137. package/runtime/packages/picasso-x-reader/rewrite.js +38 -0
  138. package/runtime/packages/picasso-x-reader/settings.js +131 -0
  139. package/runtime/packages/picasso-x-reader/urls.js +154 -0
  140. package/runtime/packages/picasso-x-reader/xmd.js +512 -0
  141. package/runtime/plugins/picasso-auth-bridge/index.js +380 -0
  142. package/runtime/plugins/picasso-auth-bridge/package.json +28 -0
  143. package/runtime/plugins/picasso-auto-approve/index.js +1003 -0
  144. package/runtime/plugins/picasso-auto-approve/package.json +28 -0
  145. package/runtime/plugins/picasso-browser/index.js +424 -0
  146. package/runtime/plugins/picasso-browser/package.json +28 -0
  147. package/runtime/plugins/picasso-checkpoints/evidence.js +210 -0
  148. package/runtime/plugins/picasso-checkpoints/index.js +885 -0
  149. package/runtime/plugins/picasso-checkpoints/package.json +29 -0
  150. package/runtime/plugins/picasso-commands/fresh-review.js +573 -0
  151. package/runtime/plugins/picasso-commands/index.js +497 -0
  152. package/runtime/plugins/picasso-commands/package.json +28 -0
  153. package/runtime/plugins/picasso-instructions/conflicts.js +115 -0
  154. package/runtime/plugins/picasso-instructions/formats.js +145 -0
  155. package/runtime/plugins/picasso-instructions/frontmatter.js +175 -0
  156. package/runtime/plugins/picasso-instructions/glob.js +114 -0
  157. package/runtime/plugins/picasso-instructions/globals.js +90 -0
  158. package/runtime/plugins/picasso-instructions/imports.js +123 -0
  159. package/runtime/plugins/picasso-instructions/index.js +326 -0
  160. package/runtime/plugins/picasso-instructions/modes.js +64 -0
  161. package/runtime/plugins/picasso-instructions/package.json +30 -0
  162. package/runtime/plugins/picasso-instructions/parse.js +134 -0
  163. package/runtime/plugins/picasso-instructions/report.js +161 -0
  164. package/runtime/plugins/picasso-instructions/resolve.js +939 -0
  165. package/runtime/plugins/picasso-instructions/scan.js +181 -0
  166. package/runtime/plugins/picasso-instructions/settings.js +150 -0
  167. package/runtime/plugins/picasso-instructions/skills.js +345 -0
  168. package/runtime/plugins/picasso-lean-context/index.js +6280 -0
  169. package/runtime/plugins/picasso-lean-context/package.json +26 -0
  170. package/runtime/plugins/picasso-lean-context/read-image-recovery.js +306 -0
  171. package/runtime/plugins/picasso-lean-context/timeline.js +418 -0
  172. package/runtime/plugins/picasso-librarian/classify.js +146 -0
  173. package/runtime/plugins/picasso-librarian/index.js +878 -0
  174. package/runtime/plugins/picasso-librarian/notes.js +159 -0
  175. package/runtime/plugins/picasso-librarian/package.json +34 -0
  176. package/runtime/plugins/picasso-librarian/state.js +478 -0
  177. package/runtime/plugins/picasso-lifecycle-hooks/index.js +186 -0
  178. package/runtime/plugins/picasso-lifecycle-hooks/package.json +25 -0
  179. package/runtime/plugins/picasso-mail/inbox.js +207 -0
  180. package/runtime/plugins/picasso-mail/index.js +293 -0
  181. package/runtime/plugins/picasso-mail/package.json +22 -0
  182. package/runtime/plugins/picasso-memory/index.js +1184 -0
  183. package/runtime/plugins/picasso-memory/package.json +21 -0
  184. package/runtime/plugins/picasso-model-router/connections.js +912 -0
  185. package/runtime/plugins/picasso-model-router/index.js +1083 -0
  186. package/runtime/plugins/picasso-model-router/package.json +30 -0
  187. package/runtime/plugins/picasso-options/index.js +263 -0
  188. package/runtime/plugins/picasso-options/package.json +28 -0
  189. package/runtime/plugins/picasso-progress-reports/index.js +267 -0
  190. package/runtime/plugins/picasso-progress-reports/package.json +30 -0
  191. package/runtime/plugins/picasso-progress-reports/report.js +235 -0
  192. package/runtime/plugins/picasso-provider-models/index.js +436 -0
  193. package/runtime/plugins/picasso-provider-models/package.json +28 -0
  194. package/runtime/plugins/picasso-repo-index/index.js +1850 -0
  195. package/runtime/plugins/picasso-repo-index/package.json +28 -0
  196. package/runtime/plugins/picasso-schedule-pause/index.js +344 -0
  197. package/runtime/plugins/picasso-schedule-pause/package.json +28 -0
  198. package/runtime/plugins/picasso-session-lifecycle/index.js +796 -0
  199. package/runtime/plugins/picasso-session-lifecycle/package.json +28 -0
  200. package/runtime/plugins/picasso-trackers/index.js +895 -0
  201. package/runtime/plugins/picasso-trackers/package.json +28 -0
  202. package/runtime/plugins/picasso-web-search/backends.js +412 -0
  203. package/runtime/plugins/picasso-web-search/config.js +121 -0
  204. package/runtime/plugins/picasso-web-search/failure.js +116 -0
  205. package/runtime/plugins/picasso-web-search/format.js +42 -0
  206. package/runtime/plugins/picasso-web-search/index.js +71 -0
  207. package/runtime/plugins/picasso-web-search/package.json +38 -0
  208. package/runtime/plugins/picasso-web-search/router.js +156 -0
  209. package/runtime/plugins/picasso-x-reader/circle.js +324 -0
  210. package/runtime/plugins/picasso-x-reader/command.js +169 -0
  211. package/runtime/plugins/picasso-x-reader/index.js +170 -0
  212. package/runtime/plugins/picasso-x-reader/package.json +39 -0
  213. package/runtime/plugins/picasso-x-reader/read.js +370 -0
  214. package/runtime/plugins/picasso-x-reader/rewrite.js +38 -0
  215. package/runtime/plugins/picasso-x-reader/settings.js +131 -0
  216. package/runtime/plugins/picasso-x-reader/urls.js +154 -0
  217. package/runtime/plugins/picasso-x-reader/xmd.js +512 -0
  218. package/runtime/relay/attachment-text.mjs +737 -0
  219. package/runtime/relay/companion/companion.css +126 -0
  220. package/runtime/relay/companion/companion.js +648 -0
  221. package/runtime/relay/companion/icon.svg +5 -0
  222. package/runtime/relay/companion/index.html +25 -0
  223. package/runtime/relay/companion/manifest.json +13 -0
  224. package/runtime/relay/companion/sw.js +41 -0
  225. package/runtime/relay/main.mjs +38580 -0
  226. package/runtime/relay/model-listing.mjs +614 -0
  227. package/runtime/relay/versions-routes.mjs +1400 -0
  228. package/runtime/verify-plugins.mjs +205 -0
  229. package/runtime-lock/package-lock.json +10779 -0
  230. package/runtime-lock/package.json +7 -0
  231. package/scripts/install-runtime.mjs +400 -0
  232. package/README.md +0 -3
@@ -0,0 +1,28 @@
1
+ {
2
+ "name": "@picasso/auto-approve",
3
+ "version": "0.1.0",
4
+ "private": true,
5
+ "description": "dsh cordis plugin: auto-approves tool executions against an allowlist of tool names — config/env at boot plus a sidecar-persisted autoApprove remote (list/add/remove/clear) that edits policy live (approval/request seam, audited; tools/pre-execute rescue when no approval service is mounted).",
6
+ "type": "module",
7
+ "main": "index.js",
8
+ "scripts": {
9
+ "test": "node --import ../../test/setup/hermetic-preload.mjs --test test/*.test.mjs"
10
+ },
11
+ "exports": {
12
+ ".": "./index.js",
13
+ "./cordis.patch.yml": "./cordis.patch.yml",
14
+ "./package.json": "./package.json"
15
+ },
16
+ "dshTarget": "0.2.2-rc.3",
17
+ "dsh": {
18
+ "bundle": {
19
+ "patch": "./cordis.patch.yml"
20
+ }
21
+ },
22
+ "files": [
23
+ "index.js",
24
+ "cordis.patch.yml",
25
+ "README.md"
26
+ ],
27
+ "license": "UNLICENSED"
28
+ }
@@ -0,0 +1,424 @@
1
+ // @picasso/browser — the agent's browser tools, executed by the Mac app on the thread's own Preview pane.
2
+ //
3
+ // dsh runs the model; the Picasso Mac app owns the only browser. A `browser_*` tool call queues an action on this
4
+ // plugin's Host Remote service (`picassoBrowser/*`), which the helper relay long-polls:
5
+ // take(timeoutMs[, signal]) -> {actions:[{actionId, sessionId, callId, tool, args, issuedAt}], cancelled:[id…]}
6
+ // returns as soon as work is queued, else after timeoutMs with empty arrays.
7
+ // Each action is handed out once; `cancelled` lists ids aborted before completion
8
+ // (tool-call abort or per-action timeout) so the Mac can drop them.
9
+ // complete(actionId, ok, value, error, sessionId) -> {}; unknown or already-settled ids fail
10
+ // `picassoBrowser/unknown-action`; a missing sessionId fails
11
+ // `picassoBrowser/session-required` and one that is not the
12
+ // issuing session's fails `picassoBrowser/session-mismatch` — stale,
13
+ // duplicate, cancelled and expired completions all land on
14
+ // unknown-action (the action is already settled). `value` is
15
+ // `{text, image?:{data: base64, mimeType}}`; `ok:false` carries `error`.
16
+ //
17
+ // Failure rules (see README): a tool call with no take() seen in the last 30 s fails fast ("Browser tools need the
18
+ // Picasso Mac app open."); an unanswered action fails after 60 s ("The Picasso preview didn't respond."); an aborted
19
+ // tool call drops its action and reports it cancelled.
20
+ //
21
+ // Mutating tools are gated by `tools/pre-execute` -> {kind:'ask'}, which dsh routes to the deployment's approval
22
+ // answerers (the Picasso relay forwards them to the Mac's approval card). Read-only tools delegate with next().
23
+ //
24
+ // Image projection goes through `@deepseek-ai/dsh-mcp-client`'s createMcpToolDefinition (the same adapter dsh's
25
+ // native Cua driver uses): a `{type:'image', data, mimeType}` block is admitted, stored as a durable attachment and
26
+ // referenced — never inlined — when the current model declares image input. The adapter is loaded with createRequire
27
+ // anchored at `config.dshBin` (the realpath of the launched dsh bin, passed by the relay's generated patch). When it
28
+ // cannot resolve, the same tools register text-only and browser_screenshot returns a text error.
29
+ import { createRequire } from 'node:module';
30
+ import { pathToFileURL } from 'node:url';
31
+
32
+ export const name = 'picasso-browser';
33
+ export const dshTarget = '0.2.2-rc.3';
34
+ // `inject` orders us after the tools service and unlocks `ctx.tools` property access.
35
+ export const inject = ['tools'];
36
+
37
+ export const SERVICE_KEY = 'picassoBrowser';
38
+ const REMOTE_METHOD_DESCRIPTOR = '@deepseek-ai/dsh-typert-protocol/remote-methods';
39
+
40
+ /** No `take()` seen within this window means the Mac app is not running its poller. */
41
+ export const NO_POLLER_MS = 30_000;
42
+ /** One queued action's answer budget before its tool call fails. */
43
+ export const ACTION_TIMEOUT_MS = 60_000;
44
+ export const TAKE_DEFAULT_MS = 25_000;
45
+
46
+ export const REMOTE_REFUSAL = 'Only pages running on this Mac open here.';
47
+ export const APP_CLOSED = 'Browser tools need the Picasso Mac app open.';
48
+ export const ACTION_TIMEOUT = "The Picasso preview didn't respond.";
49
+
50
+ /** The tools that change the page: each prompts via the approval card. */
51
+ export const ASK_TOOLS = new Set(['browser_navigate', 'browser_click', 'browser_type', 'browser_press_key']);
52
+ export const ALLOW_TOOLS = new Set(['browser_snapshot', 'browser_screenshot', 'browser_scroll', 'browser_console']);
53
+ export const TOOL_NAMES = [...ASK_TOOLS, ...ALLOW_TOOLS].sort();
54
+ const ALLOWED_KEYS = new Set(['Enter', 'Tab', 'Escape', 'Backspace', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight']);
55
+
56
+ const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '::1', '[::1]']);
57
+
58
+ export class BrowserError extends Error {
59
+ constructor(code, message, details = {}) {
60
+ super(message);
61
+ this.name = 'RemoteError';
62
+ this.code = `${SERVICE_KEY}/${code}`;
63
+ this.details = details;
64
+ this.isDSHRemoteError = true;
65
+ }
66
+ }
67
+
68
+ const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
69
+
70
+ /** The Mac's own copy for a refused page. The Preview's URL policy stays authoritative. */
71
+ export function refusedUrl(input) {
72
+ if (typeof input !== 'string') return undefined;
73
+ let url;
74
+ try {
75
+ url = new URL(input.trim());
76
+ } catch {
77
+ return undefined; // bare host:port, file paths and friends pass through to the Mac's PreviewURLPolicy.
78
+ }
79
+ if ((url.protocol === 'http:' || url.protocol === 'https:') && !LOOPBACK_HOSTS.has(url.hostname.toLowerCase())) return url;
80
+ return undefined;
81
+ }
82
+
83
+ /** Shared model-facing preamble: what this browser is and how refs work. */
84
+ const GUIDE =
85
+ ' This drives the user\u2019s visible Picasso Preview pane for this thread. Only pages running on this Mac' +
86
+ ' (localhost, 127.0.0.1, 0.0.0.0, ::1) or files inside the thread\u2019s folder load here. Call browser_snapshot' +
87
+ ' first and act on the refs it prints; refs go stale after navigation \u2014 take a new snapshot.';
88
+
89
+ export const TOOL_SPECS = [
90
+ {
91
+ name: 'browser_navigate',
92
+ description: `Open a page in this thread's Preview pane.${GUIDE}`,
93
+ parameters: {
94
+ type: 'object',
95
+ properties: { url: { type: 'string', description: 'Address to open: a loopback URL (http://localhost:3000) or a file inside the thread folder.' } },
96
+ required: ['url'],
97
+ additionalProperties: false,
98
+ },
99
+ },
100
+ {
101
+ name: 'browser_click',
102
+ description: `Click an element in the Preview, by snapshot ref.${GUIDE}`,
103
+ parameters: {
104
+ type: 'object',
105
+ properties: { ref: { type: 'string', description: 'Element ref from the latest browser_snapshot (e.g. "e12").' } },
106
+ required: ['ref'],
107
+ additionalProperties: false,
108
+ },
109
+ },
110
+ {
111
+ name: 'browser_type',
112
+ description: `Type text into an input, textarea or editable element in the Preview.${GUIDE}`,
113
+ parameters: {
114
+ type: 'object',
115
+ properties: {
116
+ ref: { type: 'string', description: 'Element ref from the latest browser_snapshot.' },
117
+ text: { type: 'string', description: 'Text to enter (replaces the current value).' },
118
+ submit: { type: 'boolean', description: 'Submit the enclosing form (or press Enter) after typing.' },
119
+ },
120
+ required: ['ref', 'text'],
121
+ additionalProperties: false,
122
+ },
123
+ },
124
+ {
125
+ name: 'browser_press_key',
126
+ description: `Press one key in the Preview: Enter, Tab, Escape, Backspace or an arrow key.${GUIDE}`,
127
+ parameters: {
128
+ type: 'object',
129
+ properties: { key: { type: 'string', enum: [...ALLOWED_KEYS], description: 'One of Enter, Tab, Escape, Backspace, ArrowUp, ArrowDown, ArrowLeft, ArrowRight.' } },
130
+ required: ['key'],
131
+ additionalProperties: false,
132
+ },
133
+ },
134
+ {
135
+ name: 'browser_snapshot',
136
+ description: `List the page's visible interactive elements as text lines with refs (e.g. "- button "Save" [ref=e12]").${GUIDE}`,
137
+ parameters: { type: 'object', properties: {}, additionalProperties: false },
138
+ },
139
+ {
140
+ name: 'browser_screenshot',
141
+ description: `Capture the Preview's visible viewport as an image.${GUIDE}`,
142
+ parameters: { type: 'object', properties: {}, additionalProperties: false },
143
+ },
144
+ {
145
+ name: 'browser_scroll',
146
+ description: `Scroll the page (or one element) up or down about a viewport.${GUIDE}`,
147
+ parameters: {
148
+ type: 'object',
149
+ properties: {
150
+ direction: { type: 'string', enum: ['up', 'down'], description: 'Scroll direction.' },
151
+ ref: { type: 'string', description: 'Optional element ref to scroll inside.' },
152
+ },
153
+ required: ['direction'],
154
+ additionalProperties: false,
155
+ },
156
+ },
157
+ {
158
+ name: 'browser_console',
159
+ description: `Read console messages, errors and network failures captured from the Preview page.${GUIDE}`,
160
+ parameters: {
161
+ type: 'object',
162
+ properties: {
163
+ sinceId: { type: 'integer', description: 'Only entries after this id (see the last line of a previous result).' },
164
+ errorsOnly: { type: 'boolean', description: 'Keep only error-level messages and failed requests.' },
165
+ },
166
+ additionalProperties: false,
167
+ },
168
+ },
169
+ ];
170
+
171
+ /** Reason the approval card shows for one gated call. */
172
+ export function askReason(exec) {
173
+ const args = isRecord(exec.arguments) ? exec.arguments : {};
174
+ switch (exec.name) {
175
+ case 'browser_navigate': return `Open ${typeof args.url === 'string' ? args.url : 'a page'} in the Preview`;
176
+ case 'browser_click': return `Click ${typeof args.ref === 'string' ? args.ref : 'an element'} in the Preview`;
177
+ case 'browser_type': return `Type into ${typeof args.ref === 'string' ? args.ref : 'a field'} in the Preview`;
178
+ case 'browser_press_key': return `Press ${typeof args.key === 'string' ? args.key : 'a key'} in the Preview`;
179
+ default: return `Run ${exec.name} in the Preview`;
180
+ }
181
+ }
182
+
183
+ /** The `tools/pre-execute` listener: ask for the mutating browser tools, delegate everything else. */
184
+ export function preExecute(exec, next) {
185
+ if (!ASK_TOOLS.has(exec.name)) return next();
186
+ const reason = askReason(exec);
187
+ return Promise.resolve({ kind: 'ask', reason, displayReason: { en: reason } });
188
+ }
189
+
190
+ /**
191
+ * The action queue the Mac drains through `picassoBrowser/*`. `now` is injectable for tests. Tool calls arrive via
192
+ * `issue()`; the poller drains via `take()`; results land via `complete()`. Wire params are simple identifiers only —
193
+ * the Typert gateway reads SRC method signatures off the function source, and a trailing `signal` is the transport
194
+ * cancellation slot, never a wire field.
195
+ */
196
+ export class BrowserActions {
197
+ constructor(options = {}) {
198
+ this.now = options.now ?? Date.now;
199
+ this.noPollerMs = options.noPollerMs ?? NO_POLLER_MS;
200
+ this.actionTimeoutMs = options.actionTimeoutMs ?? ACTION_TIMEOUT_MS;
201
+ this.queue = [];
202
+ this.inflight = new Map();
203
+ this.cancelledIds = [];
204
+ this.waiters = new Set();
205
+ this.lastPollAt = 0;
206
+ this.seq = 0;
207
+ }
208
+
209
+ // ── Remote surface ──────────────────────────────────────────────────────────────────────────────────────────
210
+
211
+ /** Long-poll for queued work; resolves early with whatever arrived, else empty after timeoutMs. */
212
+ async take(timeoutMs, signal) {
213
+ this.lastPollAt = this.now();
214
+ const ms = typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : TAKE_DEFAULT_MS;
215
+ const deadline = this.now() + ms;
216
+ const flush = () => {
217
+ const actions = this.queue.splice(0);
218
+ const cancelled = this.cancelledIds.splice(0);
219
+ for (const action of actions) this.inflight.set(action.actionId, action);
220
+ return { actions: actions.map(({ resolve: _r, reject: _j, timer: _t, onAbort: _a, signal: _s, result: _p, ...wire }) => wire), cancelled };
221
+ };
222
+ let out = flush();
223
+ if (out.actions.length > 0 || out.cancelled.length > 0) return out;
224
+ return await new Promise((resolve) => {
225
+ const settle = () => { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); this.waiters.delete(entry); resolve(flush()); };
226
+ const timer = setTimeout(settle, Math.max(0, deadline - this.now()));
227
+ const onAbort = () => settle();
228
+ signal?.addEventListener('abort', onAbort, { once: true });
229
+ const entry = { settle };
230
+ this.waiters.add(entry);
231
+ });
232
+ }
233
+
234
+ /**
235
+ * Deliver one action's outcome back to its tool call. AO-006.07: the completion is bound to the
236
+ * issuing session — `sessionId` (which the relay fills from ITS pending record, not from the
237
+ * caller's claim) must equal the session the action was issued for, else `session-mismatch`.
238
+ */
239
+ complete(actionId, ok, value, error, sessionId) {
240
+ const action = this.inflight.get(actionId);
241
+ if (action === undefined) throw new BrowserError('unknown-action', `No pending browser action "${String(actionId)}".`, { actionId });
242
+ if (typeof sessionId !== 'string' || sessionId === '') {
243
+ throw new BrowserError('session-required', `Completing browser action "${String(actionId)}" requires the issuing sessionId.`, { actionId });
244
+ }
245
+ if (sessionId !== action.sessionId) {
246
+ throw new BrowserError('session-mismatch', `Browser action "${String(actionId)}" belongs to a different session.`, { actionId });
247
+ }
248
+ clearTimeout(action.timer);
249
+ action.onAbort && action.signal?.removeEventListener('abort', action.onAbort);
250
+ this.inflight.delete(actionId);
251
+ if (ok === true) action.resolve(normalizeValue(value));
252
+ else action.reject(new Error(typeof error === 'string' && error ? error : 'The browser action failed.'));
253
+ return {};
254
+ }
255
+
256
+ // ── Tool side ───────────────────────────────────────────────────────────────────────────────────────────────
257
+
258
+ /**
259
+ * Queue one action for `sessionId` and wait for its outcome. Rejects fast when no poller is live, after the
260
+ * per-action timeout, or when the tool call's signal aborts (the action is then listed in the next `cancelled`).
261
+ */
262
+ issue(sessionId, callId, tool, args, signal) {
263
+ if (this.now() - this.lastPollAt > this.noPollerMs) return Promise.reject(new Error(APP_CLOSED));
264
+ const actionId = `ba-${++this.seq}`;
265
+ const action = { actionId, sessionId, callId, tool, args: isRecord(args) ? args : {}, issuedAt: this.now() };
266
+ const promise = new Promise((resolve, reject) => {
267
+ action.resolve = resolve;
268
+ action.reject = reject;
269
+ action.timer = setTimeout(() => this.expire(actionId, new Error(ACTION_TIMEOUT)), this.actionTimeoutMs);
270
+ action.timer.unref?.();
271
+ if (signal) {
272
+ action.signal = signal;
273
+ action.onAbort = () => this.expire(actionId, aborted(signal));
274
+ signal.addEventListener('abort', action.onAbort, { once: true });
275
+ }
276
+ });
277
+ action.result = promise;
278
+ this.queue.push(action);
279
+ for (const waiter of [...this.waiters]) waiter.settle();
280
+ return { actionId, promise };
281
+ }
282
+
283
+ /** Settle a queued or in-flight action as failed and report it cancelled to the next poller. */
284
+ expire(actionId, error) {
285
+ let action = this.inflight.get(actionId);
286
+ if (action !== undefined) this.inflight.delete(actionId);
287
+ else {
288
+ const index = this.queue.findIndex((entry) => entry.actionId === actionId);
289
+ if (index < 0) return;
290
+ action = this.queue.splice(index, 1)[0];
291
+ }
292
+ clearTimeout(action.timer);
293
+ action.onAbort && action.signal?.removeEventListener('abort', action.onAbort);
294
+ this.cancelledIds.push(actionId);
295
+ action.reject(error);
296
+ for (const waiter of [...this.waiters]) waiter.settle();
297
+ }
298
+ }
299
+
300
+ function aborted(signal) {
301
+ const reason = signal?.reason;
302
+ return reason instanceof Error ? reason : new Error('The tool call was cancelled.');
303
+ }
304
+
305
+ /** `{text, image?}` from the Mac, normalized to the canonical value a tool result carries. */
306
+ export function normalizeValue(value) {
307
+ if (!isRecord(value) || typeof value.text !== 'string') return { text: '' };
308
+ const image = isRecord(value.image) && typeof value.image.data === 'string' && typeof value.image.mimeType === 'string'
309
+ ? { data: value.image.data, mimeType: value.image.mimeType }
310
+ : undefined;
311
+ return { text: value.text, ...(image ? { image } : {}) };
312
+ }
313
+
314
+ /** Snapshot refs look like e1–e99999; anything else never reaches the page (and never a JS string). */
315
+ const REF_SHAPE = /^e[1-9][0-9]{0,4}$/;
316
+ export const REF_PROBLEM = 'ref must be a snapshot ref like "e12".';
317
+
318
+ function refProblem(ref, required) {
319
+ if (typeof ref !== 'string' || !REF_SHAPE.test(ref)) return required ? REF_PROBLEM : ref === undefined ? undefined : REF_PROBLEM;
320
+ return undefined;
321
+ }
322
+
323
+ /** Validate args the plugin itself owns before an action is queued; returns the failure message or undefined. */
324
+ export function argProblem(tool, args) {
325
+ if (tool === 'browser_navigate') {
326
+ const refused = refusedUrl(args.url);
327
+ if (refused) return `${REMOTE_REFUSAL} Use Open in browser for anything else.`;
328
+ if (typeof args.url !== 'string' || !args.url.trim()) return 'url must be a non-empty string.';
329
+ }
330
+ if (tool === 'browser_press_key' && !ALLOWED_KEYS.has(args.key)) {
331
+ return `key must be one of ${[...ALLOWED_KEYS].join(', ')}.`;
332
+ }
333
+ if (tool === 'browser_click' || tool === 'browser_type') return refProblem(args.ref, true);
334
+ if (tool === 'browser_scroll') {
335
+ if (args.direction !== 'up' && args.direction !== 'down') return 'direction must be "up" or "down".';
336
+ return refProblem(args.ref, false);
337
+ }
338
+ return undefined;
339
+ }
340
+
341
+ /**
342
+ * Run one tool call: validate, queue, await the Mac's outcome. Returns `{text, image?}` (normalized Mac value).
343
+ * `exec.agent.id` is the session id (dsh's Agent id is the SessionId) — the action's routing key to the Mac.
344
+ */
345
+ export async function runAction(actions, exec) {
346
+ const args = isRecord(exec.arguments) ? exec.arguments : {};
347
+ const problem = argProblem(exec.name, args);
348
+ if (problem) throw new Error(problem);
349
+ const sessionId = exec.agent?.id;
350
+ if (typeof sessionId !== 'string' || !sessionId) throw new Error('browser actions need an agent session');
351
+ const { promise } = actions.issue(sessionId, String(exec.callId ?? ''), exec.name, args, exec.signal);
352
+ return await promise;
353
+ }
354
+
355
+ /** The tool definitions registered on ctx.tools. `adapter` is createMcpToolDefinition, or undefined for text-only. */
356
+ export function buildTools(ctx, adapter, actions) {
357
+ return TOOL_SPECS.map((spec) => {
358
+ if (adapter !== undefined) {
359
+ return adapter(ctx, {
360
+ name: spec.name,
361
+ rawName: spec.name,
362
+ description: spec.description,
363
+ inputSchema: spec.parameters,
364
+ async call(_args, exec) {
365
+ const result = await runAction(actions, exec);
366
+ return {
367
+ content: [
368
+ { type: 'text', text: result.text },
369
+ ...(result.image ? [{ type: 'image', data: result.image.data, mimeType: result.image.mimeType }] : []),
370
+ ],
371
+ };
372
+ },
373
+ });
374
+ }
375
+ return {
376
+ name: spec.name,
377
+ description: spec.description,
378
+ parameters: spec.parameters,
379
+ output: {
380
+ schema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
381
+ render: (_args, value) => [{ type: 'text', text: typeof value?.text === 'string' ? value.text : '' }],
382
+ },
383
+ async execute(_args, exec) {
384
+ if (spec.name === 'browser_screenshot') throw new Error('Screenshots need this dsh build\u2019s image support; other browser tools still work.');
385
+ const result = await runAction(actions, exec);
386
+ return { text: result.image ? `${result.text}\n(image omitted: no image projection available)` : result.text };
387
+ },
388
+ };
389
+ });
390
+ }
391
+
392
+ /** Import one of dsh's bundled packages from a path-loaded plugin: anchor createRequire at the dsh bin's realpath. */
393
+ export async function dshModule(dshBin, specifier) {
394
+ const require = createRequire(dshBin);
395
+ return import(pathToFileURL(require.resolve(specifier)).href);
396
+ }
397
+
398
+ export async function apply(ctx, config) {
399
+ const actions = new BrowserActions();
400
+ const service = actions;
401
+ service.typertRemote = Object.freeze({ service, serviceKey: SERVICE_KEY, namespace: SERVICE_KEY });
402
+ ctx.provide(SERVICE_KEY, service);
403
+ let adapter;
404
+ try {
405
+ const module = await dshModule(config?.dshBin ?? '/opt/homebrew/bin/dsh', '@deepseek-ai/dsh-mcp-client');
406
+ adapter = module.createMcpToolDefinition;
407
+ if (typeof adapter !== 'function') throw new Error('no export');
408
+ } catch (error) {
409
+ console.warn(`${name}: image projection unavailable (${error instanceof Error ? error.message : String(error)}); registering text-only browser tools`);
410
+ }
411
+ for (const tool of buildTools(ctx, adapter, actions)) ctx.tools.register(tool);
412
+ ctx.on('tools/pre-execute', (exec, next) => preExecute(exec, next));
413
+ }
414
+
415
+ Object.defineProperty(BrowserActions.prototype, REMOTE_METHOD_DESCRIPTOR, {
416
+ configurable: true,
417
+ value: Object.freeze({
418
+ version: 1,
419
+ methods: Object.freeze([
420
+ Object.freeze({ method: 'take', invocation: Object.freeze({ kind: 'direct' }) }),
421
+ Object.freeze({ method: 'complete', invocation: Object.freeze({ kind: 'direct' }) }),
422
+ ]),
423
+ }),
424
+ });
@@ -0,0 +1,28 @@
1
+ {
2
+ "name": "@picasso/browser",
3
+ "version": "0.1.0",
4
+ "private": true,
5
+ "description": "dsh cordis plugin: browser_* model tools executed by the Picasso Mac app on the thread's loopback-only Preview pane, over the picassoBrowser/* Host Remote service the helper relay long-polls.",
6
+ "type": "module",
7
+ "main": "index.js",
8
+ "exports": {
9
+ ".": "./index.js",
10
+ "./cordis.patch.yml": "./cordis.patch.yml",
11
+ "./package.json": "./package.json"
12
+ },
13
+ "dshTarget": "0.2.2-rc.3",
14
+ "dsh": {
15
+ "bundle": {
16
+ "patch": "./cordis.patch.yml"
17
+ }
18
+ },
19
+ "scripts": {
20
+ "test": "node --import ../../test/setup/hermetic-preload.mjs --test test/*.test.mjs"
21
+ },
22
+ "files": [
23
+ "index.js",
24
+ "cordis.patch.yml",
25
+ "README.md"
26
+ ],
27
+ "license": "UNLICENSED"
28
+ }