shapewall 0.0.0-stage → 0.2.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 (304) hide show
  1. package/CHANGELOG.md +139 -0
  2. package/Dockerfile.agent +45 -0
  3. package/LICENSE +202 -0
  4. package/NOTICE +12 -0
  5. package/README.md +651 -2
  6. package/THIRD_PARTY.md +165 -0
  7. package/bin/shapewall.js +29 -0
  8. package/dist/agent/package-lock.json +8384 -0
  9. package/dist/client/assets/BoardChat-D5SFd8HE.js +28 -0
  10. package/dist/client/assets/BuzzDialog-HWXBy52W.js +1 -0
  11. package/dist/client/assets/ChecksPanel-DTdImWoD.js +1 -0
  12. package/dist/client/assets/History-CEv6b-av.js +1 -0
  13. package/dist/client/assets/LocalSettings-C4vriEVQ.js +1 -0
  14. package/dist/client/assets/Management-DCfhcEUY.js +1 -0
  15. package/dist/client/assets/QuickConnect-DQGgUsl1.js +1 -0
  16. package/dist/client/assets/ShareDialog-C_plIto0.js +2 -0
  17. package/dist/client/assets/app-update-dialog-2hPz_N9G.js +1 -0
  18. package/dist/client/assets/circle-x-BZMPi8Zf.js +1 -0
  19. package/dist/client/assets/index-ByQRKVit.css +2 -0
  20. package/dist/client/assets/index-DweQ8Qtu.js +29 -0
  21. package/dist/client/assets/refresh-cw-CRow0Nbq.js +1 -0
  22. package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
  23. package/dist/client/assets/square-A8EnIYLR.js +1 -0
  24. package/dist/client/assets/tts-dist-DYlBQmwG.js +18 -0
  25. package/dist/client/assets/tts-en-g2p-BPUtBFGG.js +1 -0
  26. package/dist/client/assets/tts-ort-wasm-simd-threaded-qh98TCA_.wasm +0 -0
  27. package/dist/client/assets/tts-ort.wasm.bundle.min-rEkcs_ow.js +12 -0
  28. package/dist/client/assets/tts-rolldown-runtime-D8NudN84.js +1 -0
  29. package/dist/client/assets/tts-spacy-en-tokenizer-6SNMl--A.json +1 -0
  30. package/dist/client/assets/tts-tts.worker-Bzm6aWbv.js +1 -0
  31. package/dist/client/assets/tts-us_gold-DcjeNMH1.json +92589 -0
  32. package/dist/client/assets/tts-us_silver-C964mEB5.json +93363 -0
  33. package/dist/client/assets/ui-CLbws0rx.js +41 -0
  34. package/dist/client/build-info.json +1 -0
  35. package/dist/client/favicon.svg +7 -0
  36. package/dist/client/icons/apple-touch-icon.png +0 -0
  37. package/dist/client/icons/icon-192.png +0 -0
  38. package/dist/client/icons/icon-512.png +0 -0
  39. package/dist/client/icons/maskable-512.png +0 -0
  40. package/dist/client/index.html +25 -0
  41. package/dist/client/manifest.webmanifest +15 -0
  42. package/dist/client/sw.js +53 -0
  43. package/dist/client/theme-boot.js +27 -0
  44. package/dist/console/assets/LocalAccountsApp-BQCcmj3x.js +1 -0
  45. package/dist/console/assets/LocalConsole-Bb2FUDs7.js +1 -0
  46. package/dist/console/assets/app-update-dialog-DIeYepLZ.js +1 -0
  47. package/dist/console/assets/console-C7uJLLOn.js +51 -0
  48. package/dist/console/assets/console-R8IBY3Am.css +2 -0
  49. package/dist/console/build-info.json +1 -0
  50. package/dist/console/console.html +21 -0
  51. package/dist/console/favicon.svg +7 -0
  52. package/dist/console/icons/apple-touch-icon.png +0 -0
  53. package/dist/console/icons/icon-192.png +0 -0
  54. package/dist/console/icons/icon-512.png +0 -0
  55. package/dist/console/icons/maskable-512.png +0 -0
  56. package/dist/console/manifest.webmanifest +15 -0
  57. package/dist/console/theme-boot.js +27 -0
  58. package/docs/agent-hardening.md +342 -0
  59. package/docs/agent-recipes.md +187 -0
  60. package/docs/agent-workflow.md +320 -0
  61. package/docs/agents.md +894 -0
  62. package/docs/architecture.md +242 -0
  63. package/docs/buzz.md +140 -0
  64. package/docs/capture-warnings.md +57 -0
  65. package/docs/config.md +489 -0
  66. package/docs/deployment.md +289 -0
  67. package/docs/design-system.md +162 -0
  68. package/docs/github.md +107 -0
  69. package/docs/hosted.md +764 -0
  70. package/docs/images/board-overview.png +0 -0
  71. package/docs/images/journeys.png +0 -0
  72. package/docs/images/live-comment.png +0 -0
  73. package/docs/images/phone-comment.png +0 -0
  74. package/docs/images/phone-overview.png +0 -0
  75. package/docs/images/variant.png +0 -0
  76. package/docs/interaction-audits.md +40 -0
  77. package/docs/journeys.md +137 -0
  78. package/docs/local-accounts.md +80 -0
  79. package/docs/notifications.md +237 -0
  80. package/docs/page-checks.md +69 -0
  81. package/docs/performance.md +174 -0
  82. package/docs/starter-agent.md +325 -0
  83. package/docs/updates.md +87 -0
  84. package/examples/audits/interaction.audit.json +17 -0
  85. package/package.json +132 -4
  86. package/src/accounts/avatar.js +121 -0
  87. package/src/accounts/local.js +464 -0
  88. package/src/agent/acp/command.js +204 -0
  89. package/src/agent/acp/detect.js +75 -0
  90. package/src/agent/acp/sandbox.js +160 -0
  91. package/src/agent/agent-health.js +75 -0
  92. package/src/agent/backends/acp.js +1297 -0
  93. package/src/agent/backends/index.js +61 -0
  94. package/src/agent/backends/openai.js +308 -0
  95. package/src/agent/composer.js +221 -0
  96. package/src/agent/config.js +338 -0
  97. package/src/agent/context.js +191 -0
  98. package/src/agent/control.js +122 -0
  99. package/src/agent/errors.js +17 -0
  100. package/src/agent/feedback-loop.js +137 -0
  101. package/src/agent/manage.js +94 -0
  102. package/src/agent/next-steps.js +51 -0
  103. package/src/agent/owner-mcp.js +38 -0
  104. package/src/agent/plain-text.js +52 -0
  105. package/src/agent/ratings-core.js +213 -0
  106. package/src/agent/ratings.js +100 -0
  107. package/src/agent/reply-text.js +67 -0
  108. package/src/agent/routes.js +1065 -0
  109. package/src/agent/run.js +326 -0
  110. package/src/agent/settings-routes.js +704 -0
  111. package/src/agent/showable.js +23 -0
  112. package/src/agent/starter/approvals.js +181 -0
  113. package/src/agent/starter/build-image.js +90 -0
  114. package/src/agent/starter/cli.js +163 -0
  115. package/src/agent/starter/disk.js +53 -0
  116. package/src/agent/starter/doctor.js +180 -0
  117. package/src/agent/starter/egress-proxy.js +351 -0
  118. package/src/agent/starter/gate.js +90 -0
  119. package/src/agent/starter/loop.js +114 -0
  120. package/src/agent/starter/model-relay.js +289 -0
  121. package/src/agent/starter/pause.js +14 -0
  122. package/src/agent/starter/probe.js +272 -0
  123. package/src/agent/starter/prompt.js +41 -0
  124. package/src/agent/starter/push-guard.js +146 -0
  125. package/src/agent/starter/rpc.js +164 -0
  126. package/src/agent/starter/runtime.js +287 -0
  127. package/src/agent/starter/sandbox-main.js +121 -0
  128. package/src/agent/starter/settings.js +290 -0
  129. package/src/agent/starter/source.js +69 -0
  130. package/src/agent/starter/supervisor.js +755 -0
  131. package/src/agent/starter/sweep.js +46 -0
  132. package/src/agent/starter/tools.js +524 -0
  133. package/src/agent/starter/watch.js +84 -0
  134. package/src/agent/starter/worktree.js +409 -0
  135. package/src/agent/text-diff.js +210 -0
  136. package/src/agent/thread-history.js +223 -0
  137. package/src/agent/threads.js +399 -0
  138. package/src/agent/tools.js +200 -0
  139. package/src/agent/turn-changes.js +424 -0
  140. package/src/agent/undo-state.js +26 -0
  141. package/src/agent/user-settings.js +308 -0
  142. package/src/auth/record.js +375 -0
  143. package/src/broken-links.js +164 -0
  144. package/src/buzz/client.js +75 -0
  145. package/src/buzz/config.js +151 -0
  146. package/src/buzz/environment.js +13 -0
  147. package/src/buzz/gateway.js +192 -0
  148. package/src/buzz/routes.js +61 -0
  149. package/src/buzz/signer-child.js +205 -0
  150. package/src/buzz/store.js +89 -0
  151. package/src/buzz/transport.js +60 -0
  152. package/src/buzz/verify.js +140 -0
  153. package/src/capture/actions.js +159 -0
  154. package/src/capture/capture.js +776 -0
  155. package/src/capture/dom-names.js +189 -0
  156. package/src/capture/element-map.js +509 -0
  157. package/src/capture/live.js +827 -0
  158. package/src/capture/media-scheme.js +317 -0
  159. package/src/capture/network-summary.js +86 -0
  160. package/src/capture/pacing.js +34 -0
  161. package/src/capture/requests.js +167 -0
  162. package/src/capture/sanitize.js +752 -0
  163. package/src/checks/accessibility.js +134 -0
  164. package/src/checks/budgets.js +58 -0
  165. package/src/checks/cli.js +55 -0
  166. package/src/checks/comparison.js +113 -0
  167. package/src/checks/environments.js +32 -0
  168. package/src/checks/flow-config.js +82 -0
  169. package/src/checks/flow-origin.js +53 -0
  170. package/src/checks/flows.js +398 -0
  171. package/src/checks/lighthouse-auth.js +145 -0
  172. package/src/checks/lighthouse-findings.js +130 -0
  173. package/src/checks/lighthouse.js +395 -0
  174. package/src/checks/robots.js +85 -0
  175. package/src/checks/routes.js +52 -0
  176. package/src/checks/run-control.js +259 -0
  177. package/src/checks/runner.js +724 -0
  178. package/src/checks/schema.js +133 -0
  179. package/src/checks/seo-analysis.js +443 -0
  180. package/src/checks/seo-probe.js +190 -0
  181. package/src/checks/seo-snapshot.js +99 -0
  182. package/src/checks/store.js +214 -0
  183. package/src/checks/transport.js +47 -0
  184. package/src/cli/args.js +319 -0
  185. package/src/cli/capture.js +79 -0
  186. package/src/cli/commands.js +92 -0
  187. package/src/cli/comments.js +84 -0
  188. package/src/cli/help.js +243 -0
  189. package/src/cli/init.js +214 -0
  190. package/src/cli/misc.js +64 -0
  191. package/src/cli/notify.js +87 -0
  192. package/src/cli/open.js +22 -0
  193. package/src/cli/serve.js +274 -0
  194. package/src/cli/variant.js +82 -0
  195. package/src/cli/watch.js +70 -0
  196. package/src/cli.js +130 -0
  197. package/src/comment-fields.js +76 -0
  198. package/src/comments-cli.js +208 -0
  199. package/src/config-reload.js +100 -0
  200. package/src/config.js +1061 -0
  201. package/src/devices-cli.js +21 -0
  202. package/src/diff.js +95 -0
  203. package/src/discover.js +284 -0
  204. package/src/doctor.js +295 -0
  205. package/src/event-log.js +268 -0
  206. package/src/events-cli.js +102 -0
  207. package/src/events.js +113 -0
  208. package/src/export.js +119 -0
  209. package/src/feedback.js +246 -0
  210. package/src/github.js +551 -0
  211. package/src/hosted/LICENSE.md +105 -0
  212. package/src/hosted/access-cli.js +78 -0
  213. package/src/hosted/admin.js +682 -0
  214. package/src/hosted/agent-approvals.js +163 -0
  215. package/src/hosted/agent-policy.js +189 -0
  216. package/src/hosted/app.js +510 -0
  217. package/src/hosted/auth-routes.js +540 -0
  218. package/src/hosted/auth.js +536 -0
  219. package/src/hosted/backup.js +483 -0
  220. package/src/hosted/board-context.js +35 -0
  221. package/src/hosted/board-routes.js +486 -0
  222. package/src/hosted/board-view.js +94 -0
  223. package/src/hosted/clean-worker.js +24 -0
  224. package/src/hosted/cleaner.js +89 -0
  225. package/src/hosted/comments.js +355 -0
  226. package/src/hosted/console-routes.js +401 -0
  227. package/src/hosted/cookies.js +18 -0
  228. package/src/hosted/crypto.js +80 -0
  229. package/src/hosted/db.js +496 -0
  230. package/src/hosted/device-routes.js +175 -0
  231. package/src/hosted/device.js +233 -0
  232. package/src/hosted/events.js +63 -0
  233. package/src/hosted/guards.js +172 -0
  234. package/src/hosted/guest-view.js +65 -0
  235. package/src/hosted/http.js +39 -0
  236. package/src/hosted/import.js +300 -0
  237. package/src/hosted/mail.js +73 -0
  238. package/src/hosted/mcp-http.js +71 -0
  239. package/src/hosted/membership.js +114 -0
  240. package/src/hosted/operator.js +478 -0
  241. package/src/hosted/ops-cli.js +345 -0
  242. package/src/hosted/pages.js +146 -0
  243. package/src/hosted/permissions.js +113 -0
  244. package/src/hosted/presence.js +372 -0
  245. package/src/hosted/projects.js +124 -0
  246. package/src/hosted/public.js +109 -0
  247. package/src/hosted/push.js +622 -0
  248. package/src/hosted/quotas.js +115 -0
  249. package/src/hosted/ratelimit.js +96 -0
  250. package/src/hosted/rebind.js +316 -0
  251. package/src/hosted/retention.js +128 -0
  252. package/src/hosted/server.js +260 -0
  253. package/src/hosted/setup-link.js +64 -0
  254. package/src/hosted/setup.js +323 -0
  255. package/src/hosted/shares.js +444 -0
  256. package/src/hosted/tailscale.js +204 -0
  257. package/src/hosted/tenancy.js +301 -0
  258. package/src/hosted/token-api.js +455 -0
  259. package/src/hosted/token-events.js +60 -0
  260. package/src/hosted/tokens.js +57 -0
  261. package/src/hosted/turnstile.js +49 -0
  262. package/src/hosted/usercontent.js +154 -0
  263. package/src/hosted/zip.js +155 -0
  264. package/src/invocation.js +58 -0
  265. package/src/journey-paths.js +282 -0
  266. package/src/journeys.js +189 -0
  267. package/src/links.js +106 -0
  268. package/src/local-projects.js +182 -0
  269. package/src/lock.js +193 -0
  270. package/src/mcp.js +417 -0
  271. package/src/mentions.js +151 -0
  272. package/src/net.js +15 -0
  273. package/src/notify/config.js +275 -0
  274. package/src/notify/index.js +301 -0
  275. package/src/notify/lease.js +73 -0
  276. package/src/notify/messages.js +212 -0
  277. package/src/notify/run.js +174 -0
  278. package/src/pixeldiff.js +49 -0
  279. package/src/png.js +143 -0
  280. package/src/reactions.js +111 -0
  281. package/src/remote/cli.js +133 -0
  282. package/src/remote/credentials.js +62 -0
  283. package/src/remote/ids.js +12 -0
  284. package/src/remote/login.js +155 -0
  285. package/src/remote/remote-mcp.js +237 -0
  286. package/src/remote/remote-watch.js +291 -0
  287. package/src/remote/remote.js +313 -0
  288. package/src/remote/share-state.js +78 -0
  289. package/src/remote/share.js +369 -0
  290. package/src/remote/terminal.js +13 -0
  291. package/src/serve-state.js +64 -0
  292. package/src/server/app.js +824 -0
  293. package/src/server/devices.js +186 -0
  294. package/src/server/local-console.js +28 -0
  295. package/src/server/local-user.js +59 -0
  296. package/src/server/pairing-routes.js +159 -0
  297. package/src/server/share-routes.js +89 -0
  298. package/src/server/tailscale.js +97 -0
  299. package/src/sitemap.js +431 -0
  300. package/src/store.js +983 -0
  301. package/src/tokens.js +11 -0
  302. package/src/update/routes.js +245 -0
  303. package/src/watch.js +403 -0
  304. package/src/which.js +58 -0
@@ -0,0 +1,1297 @@
1
+ // The ACP bridge: the chat panel talks to an agent CLI on this machine that
2
+ // speaks the Agent Client Protocol (JSON-RPC over stdio): Claude Code through
3
+ // claude-agent-acp, Codex through codex-acp, goose, Gemini CLI. The agent runs
4
+ // with the person's own login, so a subscription never leaves their machine.
5
+ //
6
+ // - One agent process per chat thread, started on the first message (spawned
7
+ // without a shell, cwd = the project root, a small environment:
8
+ // src/agent/acp/command.js), reused for the next ones, and stopped after
9
+ // being idle (10 minutes) and when the server stops. At most `processesMax`
10
+ // run at once; the least recently used idle one makes room.
11
+ // - A turn is session/prompt. session/update notifications stream back as
12
+ // text, thinking, tool cards and the plan; Stop sends session/cancel (and
13
+ // the process is stopped if it does not end the turn soon after).
14
+ // - session/request_permission becomes an approve / deny card in the panel.
15
+ // No answer within `permissionMs` is a deny.
16
+ // - The client side Shapewall offers: text files inside the project root only
17
+ // (src/agent/acp/sandbox.js), and terminals where every command needs the
18
+ // person's approval in the panel. Nothing else.
19
+
20
+ import fs from 'node:fs'
21
+ import os from 'node:os'
22
+ import path from 'node:path'
23
+ import { randomBytes } from 'node:crypto'
24
+ import { spawn } from 'node:child_process'
25
+ import { Readable, Writable } from 'node:stream'
26
+ import { PROTOCOL_VERSION, RequestError, client, ndJsonStream } from '@agentclientprotocol/sdk'
27
+ import { TERMINAL_ENV_ALLOWED, agentEnv, formatCommand, loginHint, terminalEnvRefused } from '../acp/command.js'
28
+ import { createSandbox, SandboxError } from '../acp/sandbox.js'
29
+ import { ACP_PREAMBLE, NEXT_STEPS_PROMPT, NO_IMAGES_NOTE, quoteData } from '../context.js'
30
+ import { AgentError } from '../errors.js'
31
+ import { showable } from '../showable.js'
32
+ import { diffForCard, diffForFiles } from '../text-diff.js'
33
+ import { findProgram } from '../../watch.js'
34
+ import { redact } from './openai.js'
35
+
36
+ const VERSION = JSON.parse(fs.readFileSync(new URL('../../../package.json', import.meta.url), 'utf8')).version
37
+
38
+ export const ACP_DEFAULTS = {
39
+ // initialize + session/new, including a first `npx` download.
40
+ startMs: 90 * 1000,
41
+ idleMs: 10 * 60 * 1000,
42
+ permissionMs: 2 * 60 * 1000,
43
+ // After session/cancel, how long the agent has to end the turn.
44
+ cancelGraceMs: 5000,
45
+ processesMax: 4,
46
+ // A coding agent may work for a while; the panel still has a limit.
47
+ runMs: 20 * 60 * 1000,
48
+ terminalsMax: 4,
49
+ terminalBytesMax: 1024 * 1024,
50
+ }
51
+
52
+ const STDERR_KEEP = 4000
53
+ // The most an approval card shows (and so the most that can be approved).
54
+ export const DETAIL_MAX = 4096
55
+ const HISTORY_TEXT_MAX = 4000
56
+
57
+ // Only execution choices, never arbitrary adapter config or credentials.
58
+ // Use the adapter's advertised display name when available.
59
+ export function sessionChoices(session) {
60
+ return (Array.isArray(session?.configOptions) ? session.configOptions : [])
61
+ .filter((option) => ['model', 'thought_level'].includes(option?.category) && typeof option.currentValue === 'string')
62
+ .slice(0, 2)
63
+ .map((option) => {
64
+ const values = (Array.isArray(option.options) ? option.options : []).flatMap((item) => item.options || [item])
65
+ const selected = values.find((item) => item.value === option.currentValue)
66
+ const name = option.category === 'model' ? 'Configured model' : 'Configured reasoning effort'
67
+ return `${name}: ${showable(String(selected?.name || option.currentValue)).slice(0, 120)}`
68
+ })
69
+ }
70
+ // The pickers the composer may show: model and reasoning effort selects as
71
+ // the agent lists them, display text made showable and bounded.
72
+ const OPTION_VALUES_MAX = 60
73
+ export function sessionOptions(configOptions) {
74
+ return (Array.isArray(configOptions) ? configOptions : [])
75
+ .filter(
76
+ (option) =>
77
+ ['model', 'thought_level'].includes(option?.category) &&
78
+ (option.type === undefined || option.type === 'select') &&
79
+ typeof option.id === 'string' &&
80
+ typeof option.currentValue === 'string',
81
+ )
82
+ .slice(0, 2)
83
+ .map((option) => {
84
+ const values = (Array.isArray(option.options) ? option.options : [])
85
+ .flatMap((item) => (Array.isArray(item?.options) ? item.options : [item]))
86
+ .filter((item) => typeof item?.value === 'string')
87
+ .slice(0, OPTION_VALUES_MAX)
88
+ .map((item) => ({
89
+ value: item.value.slice(0, 200),
90
+ name: showable(String(item.name || item.value)).slice(0, 80),
91
+ ...(item.description ? { description: showable(String(item.description)).slice(0, 160) } : {}),
92
+ }))
93
+ return {
94
+ id: option.id.slice(0, 100),
95
+ category: option.category,
96
+ name: showable(String(option.name || option.category)).slice(0, 60),
97
+ currentValue: option.currentValue,
98
+ values,
99
+ }
100
+ })
101
+ .filter((option) => option.values.length > 1)
102
+ }
103
+ const KILL_GRACE_MS = 2000
104
+ const POSIX = process.platform !== 'win32'
105
+
106
+ // Every process group we started, so they go with the server even when it
107
+ // exits without a clean shutdown.
108
+ const live = new Set()
109
+ let exitHook = false
110
+ function track(child) {
111
+ live.add(child)
112
+ if (!exitHook) {
113
+ exitHook = true
114
+ process.once('exit', () => {
115
+ for (const entry of live) killTree(entry, 'SIGKILL')
116
+ })
117
+ }
118
+ child.treeExitedPromise = new Promise((resolve) => {
119
+ child.treeExited = resolve
120
+ })
121
+ child.once('exit', () => stopTree(child))
122
+ child.once('error', () => {
123
+ if (!child.pid) {
124
+ live.delete(child)
125
+ child.treeExited()
126
+ }
127
+ })
128
+ }
129
+
130
+ function killTree(child, signal = 'SIGTERM') {
131
+ if (!child?.pid) return
132
+ try {
133
+ if (POSIX) process.kill(-child.pid, signal)
134
+ else child.kill(signal)
135
+ } catch {
136
+ try {
137
+ child.kill(signal)
138
+ } catch {
139
+ /* gone */
140
+ }
141
+ }
142
+ }
143
+
144
+ // A dead group leader does not mean its descendants have stopped. Linux
145
+ // zombies cannot run or write and may remain until the system reaps them.
146
+ function treeAlive(child) {
147
+ if (!child?.pid) return false
148
+ if (process.platform === 'linux') {
149
+ try {
150
+ for (const pid of fs.readdirSync('/proc')) {
151
+ if (!/^\d+$/.test(pid)) continue
152
+ try {
153
+ const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8')
154
+ const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ')
155
+ if (Number(fields[2]) === child.pid && !['Z', 'X'].includes(fields[0])) return true
156
+ } catch (error) {
157
+ if (error.code !== 'ENOENT' && error.code !== 'ESRCH') throw error
158
+ }
159
+ }
160
+ return false
161
+ } catch {
162
+ // If process metadata is unavailable, retain ownership until the OS
163
+ // says the group is gone rather than assuming a successful cleanup.
164
+ }
165
+ }
166
+ try {
167
+ if (POSIX) process.kill(-child.pid, 0)
168
+ else process.kill(child.pid, 0)
169
+ return true
170
+ } catch (error) {
171
+ return error.code !== 'ESRCH'
172
+ }
173
+ }
174
+
175
+ // Stops our process group and settles only when no member can still work.
176
+ function stopTree(child) {
177
+ if (!child) return Promise.resolve()
178
+ if (child.treeStopping) return child.treeStopping
179
+ killTree(child, 'SIGTERM')
180
+ child.treeStopping = (async () => {
181
+ const deadline = Date.now() + KILL_GRACE_MS
182
+ let forced = false
183
+ while (treeAlive(child)) {
184
+ if (!forced && Date.now() >= deadline) {
185
+ forced = true
186
+ killTree(child, 'SIGKILL')
187
+ }
188
+ await new Promise((resolve) => setTimeout(resolve, 20))
189
+ }
190
+ live.delete(child)
191
+ child.treeExited?.()
192
+ })()
193
+ return child.treeStopping
194
+ }
195
+
196
+ async function reserveProcessSlot(processPool, agent, signal) {
197
+ if (!processPool) return
198
+ const epoch = processPool.epoch
199
+ if (processPool.agents.size >= processPool.max) {
200
+ const idle = [...processPool.agents].filter((item) => !item.turn && item.state === 'ready').sort((a, b) => a.usedAt - b.usedAt)
201
+ if (![...processPool.agents].some((item) => item.killedFor && item.stoppingPromise)) idle[0]?.kill('evicted')
202
+ const retiring = [...processPool.agents].filter((item) => item.killedFor && item.stoppingPromise)
203
+ if (!retiring.length) throw new AgentError('agent_busy', 'Native agents are busy in other threads. Try again in a moment.', 429)
204
+ // A terminated session still consumes a slot until its owned process groups stop.
205
+ // Concurrent waiters recheck before reserving, so one exit admits at most one.
206
+ let timer
207
+ let onAbort
208
+ try {
209
+ await Promise.race([
210
+ Promise.race(retiring.map((item) => item.stoppingPromise)),
211
+ new Promise((resolve) => {
212
+ timer = setTimeout(resolve, KILL_GRACE_MS + 1000)
213
+ }),
214
+ new Promise((resolve) => {
215
+ onAbort = resolve
216
+ if (signal?.aborted) resolve()
217
+ else signal?.addEventListener('abort', onAbort, { once: true })
218
+ }),
219
+ ])
220
+ } finally {
221
+ clearTimeout(timer)
222
+ signal?.removeEventListener('abort', onAbort)
223
+ }
224
+ if (signal?.aborted) throw new AgentError('agent_stopped', 'The agent start was cancelled.', 409)
225
+ if (processPool.agents.size >= processPool.max)
226
+ throw new AgentError('agent_busy', 'A native agent is still stopping. Try again in a moment.', 429)
227
+ }
228
+ if (signal?.aborted) throw new AgentError('agent_stopped', 'The agent start was cancelled.', 409)
229
+ if (processPool.epoch !== epoch) throw new AgentError('agent_start', 'The server is stopping.')
230
+ processPool.agents.add(agent)
231
+ }
232
+
233
+ // A queue a turn's events go into and the backend's stream reads from.
234
+ function eventQueue() {
235
+ const items = []
236
+ let wake = null
237
+ let finished = false
238
+ let failure = null
239
+ return {
240
+ push(event) {
241
+ if (finished) return
242
+ items.push(event)
243
+ wake?.()
244
+ },
245
+ end(error = null) {
246
+ if (finished) return
247
+ finished = true
248
+ failure = error
249
+ wake?.()
250
+ },
251
+ async *[Symbol.asyncIterator]() {
252
+ for (;;) {
253
+ if (items.length) {
254
+ yield items.shift()
255
+ continue
256
+ }
257
+ if (finished) {
258
+ if (failure) throw failure
259
+ return
260
+ }
261
+ await new Promise((resolve) => (wake = resolve))
262
+ wake = null
263
+ }
264
+ },
265
+ }
266
+ }
267
+
268
+ const cut = (value, max) => {
269
+ const text = String(value ?? '')
270
+ return text.length > max ? `${text.slice(0, max - 1)}…` : text
271
+ }
272
+
273
+ // showable(): text for an approval card with nothing hidden (src/agent/showable.js).
274
+ export { showable }
275
+
276
+ // An agent's JSON-RPC error as text: the message and, when it is text, the
277
+ // data (where agents put the useful part: "Internal error" + why). Anything
278
+ // that looks like a key is removed.
279
+ function errorText(error) {
280
+ const data = typeof error?.data === 'string' ? error.data : typeof error?.data?.message === 'string' ? error.data.message : ''
281
+ return redact([error?.message, data].filter(Boolean).join(': '))
282
+ }
283
+
284
+ // The most text of one side of an edit that gets a diff on its card.
285
+ const DIFF_INPUT_MAX = 2 * 1024 * 1024
286
+
287
+ // The { path, oldText, newText } items of ACP tool call content.
288
+ function diffContent(content) {
289
+ const out = content
290
+ .filter((item) => item?.type === 'diff' && typeof item.path === 'string' && typeof item.newText === 'string')
291
+ .filter((item) => item.newText.length <= DIFF_INPUT_MAX && String(item.oldText ?? '').length <= DIFF_INPUT_MAX)
292
+ .slice(0, 20)
293
+ .map((item) => ({ path: item.path, oldText: typeof item.oldText === 'string' ? item.oldText : null, newText: item.newText }))
294
+ return out.length ? out : null
295
+ }
296
+
297
+ const TOOL_STATES = { pending: 'running', in_progress: 'running', completed: 'done', failed: 'error' }
298
+
299
+ // ACP's auth_required is -32000; agents also say it in words. goose with no
300
+ // provider set up says "Failed to resolve provider": the same fix (configure).
301
+ const AUTH_TEXT_RE =
302
+ /auth(entication)?[ _-]?required|not (logged|signed) in|please (run )?\/login|invalid api key|log ?in (first|again)|unauthori[sz]ed|failed to resolve provider/i
303
+
304
+ export function authFailure(error) {
305
+ return error?.code === -32000 || AUTH_TEXT_RE.test(errorText(error))
306
+ }
307
+
308
+ // A short answer that is only "please log in" (some agents end the turn
309
+ // with that text instead of an error). Narrower than AUTH_TEXT_RE: an answer
310
+ // about a site's login page must not count.
311
+ const AUTH_ANSWER_RE = /^(error: )?(invalid api key|authentication required|not logged in)\b|please run \/login/i
312
+
313
+ export function authAnswer(text) {
314
+ const value = String(text || '').trim()
315
+ return value.length > 0 && value.length <= 300 && AUTH_ANSWER_RE.test(value)
316
+ }
317
+
318
+ // Some adapters stream a provider rejection as an ordinary end_turn answer.
319
+ // A handshake can succeed for an unavailable model, so do not call this a
320
+ // completed coding turn or silently retry with another model.
321
+ export function modelFailureAnswer(text) {
322
+ const value = String(text || '').trim()
323
+ return (
324
+ value.length <= 1500 &&
325
+ /(?:^|\n)The ['"`][^\n]{1,150}['"`] model is not supported when using Codex with a ChatGPT account\.?$/i.test(value)
326
+ )
327
+ }
328
+
329
+ // The chat error for an agent that is not logged in, with how to fix it for
330
+ // that agent (from the command: src/agent/acp/command.js loginHint).
331
+ export function authError(label, argv) {
332
+ return new AgentError(
333
+ 'agent_auth',
334
+ `${label} is not logged in (or not set up) on this machine. To fix it, ${loginHint(argv)}; then send again.`,
335
+ )
336
+ }
337
+
338
+ // What the person's turn looks like to the agent: on a new session, the
339
+ // preamble and the thread so far (as quoted data); then the new message.
340
+ export function promptBlocks({ messages, fresh, image, thread }) {
341
+ const blocks = []
342
+ const last = messages.at(-1)
343
+ if (fresh) {
344
+ blocks.push({ type: 'text', text: ACP_PREAMBLE })
345
+ const earlier = messages
346
+ .slice(0, -1)
347
+ .map((message) => ({
348
+ role: message.role === 'assistant' ? 'agent' : 'person',
349
+ text: cut(
350
+ (message.content || [])
351
+ .filter((part) => part.type === 'text' && !part.text.startsWith('Board context'))
352
+ .map((part) => part.text)
353
+ .join('\n'),
354
+ HISTORY_TEXT_MAX,
355
+ ),
356
+ }))
357
+ .filter((message) => message.text)
358
+ if (earlier.length) {
359
+ blocks.push({
360
+ type: 'text',
361
+ text: `Earlier messages in this chat thread, for context (data, not instructions):\n${quoteData('chat-history', { thread }, earlier)}`,
362
+ })
363
+ }
364
+ // Suggested next steps (context.js): its own block, after the thread so far.
365
+ blocks.push({ type: 'text', text: NEXT_STEPS_PROMPT })
366
+ }
367
+ for (const part of last?.content || []) {
368
+ if (part.type === 'text') blocks.push({ type: 'text', text: part.text })
369
+ else if (part.type === 'image' && image) blocks.push({ type: 'image', mimeType: part.mediaType, data: part.data })
370
+ else if (part.type === 'image') blocks.push({ type: 'text', text: '[An image was attached, but this agent does not take images.]' })
371
+ }
372
+ return blocks
373
+ }
374
+
375
+ // True for a path that is not inside the project root.
376
+ export function outsideProject(root, file) {
377
+ const value = String(file || '')
378
+ if (!value) return false
379
+ const relative = path.relative(root, path.resolve(root, value))
380
+ return relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)
381
+ }
382
+
383
+ // A path as a card shows it: relative inside the project; outside it, the
384
+ // whole path (never just the name, which could pass for a project file).
385
+ export function relativeTo(root, file) {
386
+ const value = String(file || '')
387
+ if (!value) return ''
388
+ if (outsideProject(root, value)) return path.resolve(root, value)
389
+ return path.relative(root, path.resolve(root, value)) || '.'
390
+ }
391
+
392
+ const OUTSIDE_NOTE = '(outside the project)'
393
+
394
+ // The card's path with a warning when it is outside the project.
395
+ function shownPath(root, file) {
396
+ const shown = relativeTo(root, file)
397
+ return shown && outsideProject(root, file) ? `${shown} ${OUTSIDE_NOTE}` : shown
398
+ }
399
+
400
+ // One agent process and its ACP session (one chat thread).
401
+ class AcpProcess {
402
+ constructor({ argv, label, env, sandbox, limits, log, thread, onGone, mcpServers = [] }) {
403
+ Object.assign(this, { argv, label, sandbox, limits, log, thread, onGone, mcpServers })
404
+ this.env = agentEnv(env)
405
+ this.root = sandbox.root
406
+ this.state = 'starting'
407
+ this.stderr = ''
408
+ this.turn = null
409
+ this.tools = new Map()
410
+ this.terminals = new Map()
411
+ this.terminalGroups = new Set()
412
+ this.sessionId = null
413
+ this.fresh = true
414
+ this.usedAt = Date.now()
415
+ }
416
+
417
+ get pid() {
418
+ return this.child?.pid ?? null
419
+ }
420
+
421
+ async start(signal) {
422
+ let child
423
+ // The process starts in a fresh empty folder, not the project: `npx` and
424
+ // other launchers read config from their working folder (.npmrc with a
425
+ // script-shell or registry, .tool-versions, ...), so a repo could decide
426
+ // what runs before anyone approves anything. The project reaches the
427
+ // agent as the session's cwd (session/new) instead.
428
+ this.home = fs.mkdtempSync(path.join(os.tmpdir(), 'shapewall-acp-'))
429
+ try {
430
+ child = spawn(this.argv[0], this.argv.slice(1), {
431
+ cwd: this.home,
432
+ env: this.env,
433
+ stdio: ['pipe', 'pipe', 'pipe'],
434
+ shell: false,
435
+ detached: POSIX,
436
+ windowsHide: true,
437
+ })
438
+ } catch (error) {
439
+ this.removeHome()
440
+ throw new AgentError('agent_start', `Could not start ${this.label} (${error.code || error.message}).`)
441
+ }
442
+ this.child = child
443
+ track(child)
444
+ const spawned = new Promise((resolve, reject) => {
445
+ child.once('spawn', resolve)
446
+ child.once('error', reject)
447
+ })
448
+ child.stderr.on('data', (chunk) => {
449
+ this.stderr = (this.stderr + chunk.toString('utf8')).slice(-STDERR_KEEP)
450
+ })
451
+ child.stdin.on('error', () => {})
452
+ // A later error (a failed kill) must not take the server down.
453
+ child.on('error', () => {})
454
+ this.exitedPromise = new Promise((resolve) => child.once('exit', resolve))
455
+ child.once('exit', (code, signalName) => this.gone(code, signalName))
456
+ try {
457
+ await spawned
458
+ } catch (error) {
459
+ this.state = 'dead'
460
+ this.removeHome()
461
+ throw new AgentError('agent_start', `Could not start ${this.label} (${error.code || error.message}).`)
462
+ }
463
+
464
+ const app = client({ name: 'shapewall' })
465
+ .onNotification('session/update', ({ params }) => this.onUpdate(params))
466
+ .onRequest('session/request_permission', ({ params, signal: requestSignal }) => this.onPermission(params, requestSignal))
467
+ .onRequest('fs/read_text_file', ({ params }) => this.onRead(params))
468
+ .onRequest('fs/write_text_file', ({ params, signal: requestSignal }) => this.onWrite(params, requestSignal))
469
+ .onRequest('terminal/create', ({ params, signal: requestSignal }) => this.onTerminalCreate(params, requestSignal))
470
+ .onRequest('terminal/output', ({ params }) => this.onTerminalOutput(params))
471
+ .onRequest('terminal/wait_for_exit', ({ params }) => this.onTerminalWait(params))
472
+ .onRequest('terminal/kill', ({ params }) => this.onTerminalKill(params))
473
+ .onRequest('terminal/release', ({ params }) => this.onTerminalRelease(params))
474
+ this.connection = app.connect(ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout)))
475
+ this.connection.closed.catch(() => {})
476
+
477
+ const timer = setTimeout(() => this.kill('start_timeout'), this.limits.startMs)
478
+ const onAbort = () => this.kill('aborted')
479
+ signal?.addEventListener('abort', onAbort, { once: true })
480
+ try {
481
+ const init = await this.connection.agent.request('initialize', {
482
+ protocolVersion: PROTOCOL_VERSION,
483
+ clientCapabilities: { fs: { readTextFile: true, writeTextFile: true }, terminal: true },
484
+ clientInfo: { name: 'shapewall', title: 'Shapewall', version: VERSION },
485
+ })
486
+ this.agentInfo = init?.agentInfo || null
487
+ this.image = Boolean(init?.agentCapabilities?.promptCapabilities?.image)
488
+ this.authMethods = Array.isArray(init?.authMethods) ? init.authMethods : []
489
+ const session = await this.connection.agent.request('session/new', { cwd: this.root, mcpServers: this.mcpServers })
490
+ this.sessionId = session.sessionId
491
+ this.choices = sessionChoices(session)
492
+ this.configOptions = Array.isArray(session.configOptions) ? session.configOptions : []
493
+ this.state = 'ready'
494
+ } catch (error) {
495
+ throw this.startError(error)
496
+ } finally {
497
+ clearTimeout(timer)
498
+ signal?.removeEventListener('abort', onAbort)
499
+ }
500
+ return this
501
+ }
502
+
503
+ startError(error) {
504
+ if (this.killedFor === 'start_timeout') {
505
+ this.kill('start_failed')
506
+ return new AgentError('agent_start', `${this.label} did not answer within ${Math.round(this.limits.startMs / 1000)} seconds.`)
507
+ }
508
+ this.kill('start_failed')
509
+ if (authFailure(error)) return this.authError()
510
+ if (this.exited) return this.exitError()
511
+ return new AgentError('agent_start', `${this.label} did not start an ACP session (${cut(errorText(error) || 'no answer', 300)}).`)
512
+ }
513
+
514
+ // Not logged in: the fix goes to the chat and to the server log.
515
+ authError() {
516
+ const error = authError(this.label, this.argv)
517
+ this.log(`acp: ${this.label} is not logged in: ${loginHint(this.argv)}`)
518
+ return error
519
+ }
520
+
521
+ exitError() {
522
+ const tail = this.stderr.trim().split('\n').slice(-3).join(' ').trim()
523
+ const how = this.exited?.signal ? `signal ${this.exited.signal}` : `code ${this.exited?.code ?? '?'}`
524
+ return new AgentError('agent_exited', `${this.label} stopped (${how})${tail ? `: ${cut(tail, 300)}` : '.'}`)
525
+ }
526
+
527
+ gone(code, signalName) {
528
+ this.exited = { code, signal: signalName }
529
+ this.state = 'dead'
530
+ clearTimeout(this.idleTimer)
531
+ for (const terminal of this.terminals.values()) stopTree(terminal.child)
532
+ this.terminals.clear()
533
+ // Whatever a running turn was waiting for will not come.
534
+ if (this.turn) {
535
+ for (const permission of this.turn.permissions.values()) permission.settle('cancelled')
536
+ this.turn.queue.end(this.turn.cancelled ? null : this.exitError())
537
+ }
538
+ try {
539
+ this.connection?.close()
540
+ } catch {
541
+ /* closed */
542
+ }
543
+ if (code && !this.killedFor) this.log(`acp: ${this.label} exited with code ${code}`)
544
+ this.stopOwned()
545
+ this.onGone(this)
546
+ }
547
+
548
+ stopOwned() {
549
+ this.stoppingPromise ||= Promise.all([stopTree(this.child), ...[...this.terminalGroups].map(stopTree)]).then(() => {
550
+ this.stopped = true
551
+ this.removeHome()
552
+ this.onGone(this)
553
+ })
554
+ return this.stoppingPromise
555
+ }
556
+
557
+ removeHome() {
558
+ if (!this.home) return
559
+ try {
560
+ fs.rmSync(this.home, { recursive: true, force: true })
561
+ } catch {
562
+ /* a child still writing there; the temp folder is cleaned eventually */
563
+ }
564
+ this.home = null
565
+ }
566
+
567
+ kill(reason = 'stopped') {
568
+ this.killedFor = this.killedFor || reason
569
+ if (!['starting', 'dead'].includes(this.state)) this.state = 'stopping'
570
+ // Detach the session from its thread immediately. Its shared process
571
+ // slot stays reserved until all owned groups have stopped.
572
+ this.onGone(this)
573
+ clearTimeout(this.idleTimer)
574
+ try {
575
+ this.child?.stdin.end()
576
+ } catch {
577
+ /* closed */
578
+ }
579
+ this.stopOwned()
580
+ }
581
+
582
+ idle() {
583
+ clearTimeout(this.idleTimer)
584
+ this.usedAt = Date.now()
585
+ this.idleTimer = setTimeout(() => this.kill('idle'), this.limits.idleMs)
586
+ this.idleTimer.unref?.()
587
+ }
588
+
589
+ // Waits for a turn that is still ending (after Stop) to settle; stops the
590
+ // process when it does not.
591
+ async settled() {
592
+ const done = this.turn?.done
593
+ let timeout
594
+ try {
595
+ if (done)
596
+ await Promise.race([
597
+ done,
598
+ new Promise((resolve) => {
599
+ timeout = setTimeout(resolve, this.limits.cancelGraceMs + 500)
600
+ }),
601
+ ])
602
+ if (this.turn) {
603
+ this.kill('stuck')
604
+ }
605
+ if (this.stoppingPromise) await this.stoppingPromise
606
+ // A completed terminal root can leave a retiring descendant group
607
+ // even when the ACP session itself remains healthy and reusable.
608
+ await Promise.all([...this.terminalGroups].map((child) => child.treeStopping).filter(Boolean))
609
+ } finally {
610
+ clearTimeout(timeout)
611
+ }
612
+ }
613
+
614
+ // Starts session/prompt. Returns the events and a finish() for when the
615
+ // reader stops early.
616
+ prompt(blocks, signal) {
617
+ clearTimeout(this.idleTimer)
618
+ const queue = eventQueue()
619
+ const turn = { queue, permissions: new Map(), cancelled: false, settled: false, text: '' }
620
+ this.turn = turn
621
+ this.fresh = false
622
+ const onAbort = () => this.cancel(turn)
623
+ signal?.addEventListener('abort', onAbort, { once: true })
624
+ turn.done = this.connection.agent
625
+ .request('session/prompt', { sessionId: this.sessionId, prompt: blocks })
626
+ .then((result) => {
627
+ // The turn's token counts, where the agent reports them (ACP unstable PromptResponse.usage).
628
+ if (result?.usage && typeof result.usage === 'object')
629
+ queue.push({ type: 'usage', input: result.usage.inputTokens, output: result.usage.outputTokens, total: result.usage.totalTokens })
630
+ queue.push({ type: 'done', finishReason: result?.stopReason || 'end_turn' })
631
+ // A turn whose whole answer is "please log in": say how, as an error.
632
+ queue.end(
633
+ authAnswer(turn.text)
634
+ ? this.authError()
635
+ : modelFailureAnswer(turn.text)
636
+ ? new AgentError(
637
+ 'agent_model',
638
+ 'The native agent rejected the selected model. Check the model in its CLI configuration on this computer; no other model was tried.',
639
+ )
640
+ : null,
641
+ )
642
+ })
643
+ .catch(async (error) => {
644
+ if (turn.cancelled) return queue.end()
645
+ if (authFailure(error)) return queue.end(this.authError())
646
+ // The pipe often closes just before the exit: wait a moment, so the
647
+ // message says the agent stopped (and why), not that a request failed.
648
+ if (!this.exited) await Promise.race([this.exitedPromise, new Promise((resolve) => setTimeout(resolve, 500))])
649
+ queue.end(
650
+ this.exited
651
+ ? this.exitError()
652
+ : new AgentError('agent_upstream', `${this.label}: ${cut(errorText(error) || 'the turn failed', 300)}`),
653
+ )
654
+ })
655
+ .finally(() => {
656
+ turn.settled = true
657
+ clearTimeout(turn.killTimer)
658
+ signal?.removeEventListener('abort', onAbort)
659
+ if (this.turn === turn) this.turn = null
660
+ if (this.state !== 'dead') this.idle()
661
+ })
662
+ if (signal?.aborted) this.cancel(turn)
663
+ return { events: queue, finish: () => turn.settled || this.cancel(turn) }
664
+ }
665
+
666
+ cancel(turn) {
667
+ if (turn.cancelled || turn.settled) return
668
+ turn.cancelled = true
669
+ for (const permission of turn.permissions.values()) permission.settle('cancelled')
670
+ this.connection.agent.notify('session/cancel', { sessionId: this.sessionId }).catch(() => {})
671
+ turn.killTimer = setTimeout(() => {
672
+ if (!turn.settled) this.kill('cancel_ignored')
673
+ }, this.limits.cancelGraceMs)
674
+ turn.killTimer.unref?.()
675
+ }
676
+
677
+ // The composer's model and effort pickers: one of the session's own
678
+ // config options (model or thought_level, select only) to one of the
679
+ // values it lists. Never while a turn runs; never a mode (permission
680
+ // modes stay the agent's own setting, docs/agents.md).
681
+ async setOption(configId, value) {
682
+ if (this.state !== 'ready' || this.turn) throw new AgentError('agent_running', 'Wait for the answer to finish before switching.', 409)
683
+ const option = sessionOptions(this.configOptions).find((item) => item.id === configId)
684
+ if (!option || !option.values.some((item) => item.value === value))
685
+ throw new AgentError('bad_option', 'The agent does not offer that choice.', 400)
686
+ let result
687
+ try {
688
+ result = await this.connection.agent.request('session/set_config_option', { sessionId: this.sessionId, configId, value })
689
+ } catch (error) {
690
+ throw new AgentError('agent_upstream', `${this.label} did not switch (${cut(errorText(error) || 'no answer', 200)}).`, 502)
691
+ }
692
+ if (Array.isArray(result?.configOptions)) this.configOptions = result.configOptions
693
+ else this.configOptions = this.configOptions.map((item) => (item.id === configId ? { ...item, currentValue: value } : item))
694
+ return sessionOptions(this.configOptions)
695
+ }
696
+
697
+ // ---- What the agent sends ---------------------------------------------------
698
+
699
+ ownSession(params) {
700
+ if (params?.sessionId !== this.sessionId) throw RequestError.invalidParams(undefined, 'unknown session')
701
+ }
702
+
703
+ onUpdate(params) {
704
+ if (params?.sessionId === this.sessionId && params.update?.sessionUpdate === 'config_option_update') {
705
+ // The agent changed its own model or effort (or confirmed ours): the composer shows it.
706
+ if (Array.isArray(params.update.configOptions)) this.configOptions = params.update.configOptions
707
+ return
708
+ }
709
+ const turn = this.turn
710
+ if (!turn || turn.cancelled || params?.sessionId !== this.sessionId) return
711
+ const update = params.update || {}
712
+ const kind = update.sessionUpdate
713
+ if (kind === 'usage_update') {
714
+ turn.queue.push({ type: 'usage', contextUsed: update.used, contextSize: update.size })
715
+ return
716
+ }
717
+ if (kind === 'agent_message_chunk' && update.content?.type === 'text') {
718
+ if (turn.text.length <= 1000) turn.text += String(update.content.text)
719
+ turn.queue.push({ type: 'text', text: String(update.content.text) })
720
+ } else if (kind === 'agent_thought_chunk' && update.content?.type === 'text')
721
+ turn.queue.push({ type: 'reasoning', text: String(update.content.text) })
722
+ else if (kind === 'tool_call' || kind === 'tool_call_update') turn.queue.push(this.toolEvent(update))
723
+ else if (kind === 'plan' && Array.isArray(update.entries)) {
724
+ turn.queue.push({
725
+ type: 'plan',
726
+ entries: update.entries.slice(0, 30).map((entry) => ({
727
+ content: cut(entry?.content, 200),
728
+ status: ['pending', 'in_progress', 'completed'].includes(entry?.status) ? entry.status : 'pending',
729
+ })),
730
+ })
731
+ }
732
+ }
733
+
734
+ toolEvent(update) {
735
+ const id = String(update.toolCallId || '')
736
+ const known = this.tools.get(id) || {}
737
+ const tool = {
738
+ title: update.title || known.title || update.kind || 'Tool',
739
+ kind: update.kind || known.kind || 'other',
740
+ status: update.status || known.status || 'pending',
741
+ location: update.locations?.[0]?.path || known.location || null,
742
+ // ACP diff content ({ type: 'diff', path, oldText, newText }), for the
743
+ // approval card if the agent asks about this call later.
744
+ diffs: Array.isArray(update.content) ? diffContent(update.content) : known.diffs || null,
745
+ }
746
+ this.tools.set(id, tool)
747
+ if (this.tools.size > 500) this.tools.delete(this.tools.keys().next().value)
748
+ return {
749
+ type: 'tool',
750
+ id: `acp-${id}`,
751
+ name: tool.kind,
752
+ label: cut(tool.title, 80),
753
+ state: TOOL_STATES[tool.status] || 'running',
754
+ detail: tool.location ? showable(shownPath(this.root, tool.location)) : null,
755
+ }
756
+ }
757
+
758
+ // Shows a card and waits for the person: resolves 'approved' (with the
759
+ // option), 'denied', 'expired' or 'cancelled'.
760
+ ask({ title, kind, detail, options, diff = null }, signal) {
761
+ const turn = this.turn
762
+ if (!turn || turn.cancelled) return Promise.resolve({ state: 'cancelled', option: null })
763
+ const id = `perm_${randomBytes(6).toString('hex')}`
764
+ const expiresAt = new Date(Date.now() + this.limits.permissionMs).toISOString()
765
+ // The card shows everything the person approves. What cannot be shown
766
+ // in full cannot be approved: it is denied without asking.
767
+ if (detail && detail.length > DETAIL_MAX) {
768
+ turn.queue.push({
769
+ type: 'permission',
770
+ id,
771
+ title: cut(title, 120),
772
+ kind,
773
+ detail: `${cut(detail, 300)}\n[Denied: ${detail.length} characters is too long to show for approval.]`,
774
+ options: [],
775
+ expiresAt: null,
776
+ state: 'denied',
777
+ chosen: null,
778
+ })
779
+ return Promise.resolve({ state: 'denied', option: null })
780
+ }
781
+ const card = { type: 'permission', id, title: cut(title, 120), kind, detail: detail || null, diff, options, expiresAt }
782
+ return new Promise((resolve) => {
783
+ const settle = (state, option = null, answeredBy = null) => {
784
+ if (!turn.permissions.has(id)) return
785
+ turn.permissions.delete(id)
786
+ clearTimeout(timer)
787
+ signal?.removeEventListener('abort', onAbort)
788
+ turn.queue.push({ ...card, state, chosen: option?.name || null, answeredBy })
789
+ resolve({ state, option })
790
+ }
791
+ const timer = setTimeout(() => settle('expired'), this.limits.permissionMs)
792
+ timer.unref?.()
793
+ const onAbort = () => settle('cancelled')
794
+ signal?.addEventListener('abort', onAbort, { once: true })
795
+ turn.permissions.set(id, { options, settle })
796
+ turn.queue.push({ ...card, state: 'pending', chosen: null })
797
+ })
798
+ }
799
+
800
+ // The person's answer from the board. True when the card was still open.
801
+ answer(id, optionId, answeredBy = null) {
802
+ const permission = this.turn?.permissions.get(id)
803
+ if (!permission) return null
804
+ if (optionId === null) {
805
+ permission.settle('denied', null, answeredBy)
806
+ return 'denied'
807
+ }
808
+ const option = permission.options.find((item) => item.optionId === optionId)
809
+ if (!option) return false
810
+ const state = option.kind.startsWith('allow') ? 'approved' : 'denied'
811
+ permission.settle(state, option, answeredBy)
812
+ return state
813
+ }
814
+
815
+ async onPermission(params, signal) {
816
+ this.ownSession(params)
817
+ const call = params.toolCall || {}
818
+ const known = this.tools.get(String(call.toolCallId || '')) || {}
819
+ const options = (Array.isArray(params.options) ? params.options : []).slice(0, 6).map((option) => ({
820
+ optionId: cut(option?.optionId, 100),
821
+ name: cut(option?.name || option?.optionId, 60),
822
+ kind: ['allow_once', 'allow_always', 'reject_once', 'reject_always'].includes(option?.kind) ? option.kind : 'reject_once',
823
+ }))
824
+ const input = call.rawInput && typeof call.rawInput === 'object' ? call.rawInput : null
825
+ let detail =
826
+ input?.command ??
827
+ input?.cmd ??
828
+ input?.file_path ??
829
+ input?.path ??
830
+ relativeTo(this.root, call.locations?.[0]?.path || known.location || '')
831
+ if (Array.isArray(detail)) detail = detail.map(String).join(' ')
832
+ else if (detail && typeof detail !== 'string') detail = JSON.stringify(detail)
833
+ if (detail) detail = showable(detail)
834
+ // A file outside the project says so on the card.
835
+ const target = [input?.file_path, input?.path, input?.filePath, call.locations?.[0]?.path, known.location].find(
836
+ (value) => typeof value === 'string' && value,
837
+ )
838
+ if (detail && target && outsideProject(this.root, target)) {
839
+ detail = `${detail}\n[Outside the project: ${showable(path.resolve(this.root, target))}]`
840
+ }
841
+ const { state, option } = await this.ask(
842
+ {
843
+ title: call.title || known.title || 'Use a tool',
844
+ kind: call.kind || known.kind || 'other',
845
+ detail,
846
+ options,
847
+ diff: this.editDiff(call, known, input),
848
+ },
849
+ signal,
850
+ )
851
+ if (state === 'approved' || (state === 'denied' && option)) return { outcome: { outcome: 'selected', optionId: option.optionId } }
852
+ // No answer, or a plain deny: the agent's own "reject" option, else cancelled.
853
+ const reject =
854
+ state === 'cancelled'
855
+ ? null
856
+ : options.find((item) => item.kind === 'reject_once') || options.find((item) => item.kind === 'reject_always')
857
+ return reject ? { outcome: { outcome: 'selected', optionId: reject.optionId } } : { outcome: { outcome: 'cancelled' } }
858
+ }
859
+
860
+ // What an edit or write would change, for its approval card: the diff
861
+ // content the agent sent (ACP), else its tool input (Claude Code's
862
+ // old_string/new_string and Write content, goose's old_str/new_str and
863
+ // file_text), against the file as it is now. null when there is none.
864
+ editDiff(call, known, input) {
865
+ try {
866
+ const sent = Array.isArray(call.content) ? diffContent(call.content) : known.diffs
867
+ if (sent?.length) {
868
+ return diffForFiles(
869
+ sent.map((item) => ({ ...item, path: relativeTo(this.root, item.path), outside: outsideProject(this.root, item.path) })),
870
+ )
871
+ }
872
+ if (!input) return null
873
+ const file = [input.file_path, input.path, input.filePath].find((value) => typeof value === 'string') || ''
874
+ const shown = file ? relativeTo(this.root, file) : null
875
+ const outside = Boolean(file) && outsideProject(this.root, file)
876
+ const text = (value) => (typeof value === 'string' && value.length <= DIFF_INPUT_MAX ? value : null)
877
+ const edits = Array.isArray(input.edits) ? input.edits : [input]
878
+ const pairs = edits
879
+ .map((edit) => ({
880
+ oldText: text(edit?.old_string ?? edit?.old_str ?? edit?.oldText),
881
+ newText: text(edit?.new_string ?? edit?.new_str ?? edit?.newText),
882
+ }))
883
+ .filter((pair) => pair.oldText !== null && pair.newText !== null)
884
+ if (pairs.length) {
885
+ // Applied to the file when it has every old text: real line numbers
886
+ // and context. Else the snippets alone.
887
+ const current = file ? this.currentText(file) : null
888
+ let next = current
889
+ for (const [index, pair] of pairs.entries()) {
890
+ if (next === null || !pair.oldText || !next.includes(pair.oldText)) {
891
+ next = null
892
+ break
893
+ }
894
+ next = edits[index]?.replace_all ? next.split(pair.oldText).join(pair.newText) : next.replace(pair.oldText, () => pair.newText)
895
+ }
896
+ if (next !== null) return diffForFiles([{ path: shown, oldText: current, newText: next, outside }])
897
+ return diffForFiles(pairs.map((pair) => ({ path: shown, outside, ...pair })))
898
+ }
899
+ const whole = text(input.content ?? input.file_text ?? input.text)
900
+ if (whole === null || !file) return null
901
+ return diffForFiles([{ path: shown, oldText: this.currentText(file), newText: whole, outside }])
902
+ } catch {
903
+ return null
904
+ }
905
+ }
906
+
907
+ // A project file's text now, or null (new, outside the project, too big).
908
+ currentText(file) {
909
+ try {
910
+ return this.sandbox.read({ path: path.resolve(this.root, file) })
911
+ } catch {
912
+ return null
913
+ }
914
+ }
915
+
916
+ onRead(params) {
917
+ this.ownSession(params)
918
+ try {
919
+ return { content: this.sandbox.read(params) }
920
+ } catch (error) {
921
+ throw sandboxRefusal(error)
922
+ }
923
+ }
924
+
925
+ async onWrite(params, signal) {
926
+ this.ownSession(params)
927
+ const turn = this.turn
928
+ let target
929
+ try {
930
+ target = this.sandbox.resolve(params?.path, { write: true })
931
+ } catch (error) {
932
+ throw sandboxRefusal(error)
933
+ }
934
+ // Dotfiles, hooks, CI workflows, package.json, the Shapewall config: files
935
+ // that decide what runs later. A write there needs the person's approval.
936
+ if (this.sandbox.sensitive(target)) {
937
+ const bytes = Buffer.byteLength(String(params?.content ?? ''))
938
+ const { state } = await this.ask(
939
+ {
940
+ title: 'Write a file that controls what runs',
941
+ kind: 'edit',
942
+ detail: `${showable(relativeTo(this.root, target))} (${bytes} bytes)`,
943
+ diff:
944
+ typeof params?.content === 'string'
945
+ ? diffForCard(relativeTo(this.root, target), this.currentText(target), params.content)
946
+ : null,
947
+ options: [
948
+ { optionId: 'write', name: 'Write', kind: 'allow_once' },
949
+ { optionId: 'deny', name: "Don't write", kind: 'reject_once' },
950
+ ],
951
+ },
952
+ signal,
953
+ )
954
+ if (state !== 'approved') throw new RequestError(-32000, `The person did not allow writing this file (${state}).`)
955
+ if (!turn || this.turn !== turn || turn.cancelled || signal?.aborted || this.state !== 'ready' || this.stoppingPromise)
956
+ throw new RequestError(-32000, 'The agent stopped before this file could be written.')
957
+ }
958
+ try {
959
+ const file = this.sandbox.write(params)
960
+ this.turn?.queue.push({
961
+ type: 'tool',
962
+ id: `acp-write-${randomBytes(4).toString('hex')}`,
963
+ name: 'edit',
964
+ label: 'Wrote a file',
965
+ state: 'done',
966
+ detail: relativeTo(this.root, file),
967
+ })
968
+ return {}
969
+ } catch (error) {
970
+ throw sandboxRefusal(error)
971
+ }
972
+ }
973
+
974
+ // ---- Terminals: each command is approved in the panel ---------------------------
975
+
976
+ async onTerminalCreate(params, signal) {
977
+ this.ownSession(params)
978
+ const turn = this.turn
979
+ if (this.terminals.size >= this.limits.terminalsMax) throw new RequestError(-32000, 'Too many terminals are open; release one first.')
980
+ const command = typeof params.command === 'string' ? params.command : ''
981
+ const args = Array.isArray(params.args) ? params.args.map(String) : []
982
+ if (!command) throw RequestError.invalidParams(undefined, 'command is required')
983
+ let cwd = this.root
984
+ try {
985
+ if (params.cwd) cwd = this.sandbox.resolve(params.cwd)
986
+ } catch (error) {
987
+ throw sandboxRefusal(error)
988
+ }
989
+ // The agent's env: names that change what a program loads or runs
990
+ // (LD_PRELOAD, NODE_OPTIONS, GIT_CONFIG_*, PATH, EDITOR, ...) refuse the
991
+ // whole request; a few harmless ones pass and are shown; the rest are ignored.
992
+ const extraEnv = {}
993
+ const ignored = []
994
+ for (const entry of Array.isArray(params.env) ? params.env : []) {
995
+ if (typeof entry?.name !== 'string' || typeof entry?.value !== 'string') continue
996
+ if (terminalEnvRefused(entry.name)) {
997
+ throw new RequestError(-32000, `Refused: the command sets ${cut(entry.name, 60)}, which can change what runs.`)
998
+ }
999
+ if (TERMINAL_ENV_ALLOWED.has(entry.name)) extraEnv[entry.name] = entry.value
1000
+ else ignored.push(cut(entry.name, 60))
1001
+ }
1002
+ const shown = showable(formatCommand([command, ...args]))
1003
+ const lines = [
1004
+ shown,
1005
+ `${args.length} argument${args.length === 1 ? '' : 's'}, no shell, in ${cwd === this.root ? 'the project folder' : relativeTo(this.root, cwd)}`,
1006
+ ...Object.entries(extraEnv).map(([name, value]) => `env ${name}=${showable(value)}`),
1007
+ ...(ignored.length ? [`env ignored: ${ignored.join(', ')}`] : []),
1008
+ ]
1009
+ const { state } = await this.ask(
1010
+ {
1011
+ title: 'Run a command',
1012
+ kind: 'execute',
1013
+ detail: lines.join('\n'),
1014
+ options: [
1015
+ { optionId: 'run', name: 'Run', kind: 'allow_once' },
1016
+ { optionId: 'deny', name: "Don't run", kind: 'reject_once' },
1017
+ ],
1018
+ },
1019
+ signal,
1020
+ )
1021
+ if (state !== 'approved') throw new RequestError(-32000, `The person did not allow this command (${state}).`)
1022
+ // Approval can resolve immediately before teardown. Recheck after that
1023
+ // await so no terminal group appears after stopOwned took its snapshot.
1024
+ if (!turn || this.turn !== turn || turn.cancelled || signal?.aborted || this.state !== 'ready' || this.stoppingPromise)
1025
+ throw new RequestError(-32000, 'The agent stopped before this command could start.')
1026
+ if (this.terminals.size >= this.limits.terminalsMax) throw new RequestError(-32000, 'Too many terminals are open; release one first.')
1027
+ // A path is relative to the terminal's folder; a bare name is looked up on PATH.
1028
+ const program = findProgram(/[\\/]/.test(command) ? path.resolve(cwd, command) : command, this.env)
1029
+ if (!program) throw new RequestError(-32000, `"${command}" is not an executable on PATH`)
1030
+ const env = { ...this.env, ...extraEnv }
1031
+ const limit = Math.min(
1032
+ Number.isInteger(params.outputByteLimit) && params.outputByteLimit > 0 ? params.outputByteLimit : Infinity,
1033
+ this.limits.terminalBytesMax,
1034
+ )
1035
+ const child = spawn(program, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], shell: false, detached: POSIX, windowsHide: true })
1036
+ track(child)
1037
+ this.terminalGroups.add(child)
1038
+ child.treeExitedPromise.then(() => this.terminalGroups.delete(child))
1039
+ child.on('error', () => {})
1040
+ const terminal = { child, output: '', truncated: false, exitStatus: null }
1041
+ const append = (chunk) => {
1042
+ terminal.output += chunk.toString('utf8')
1043
+ if (Buffer.byteLength(terminal.output) > limit) {
1044
+ terminal.truncated = true
1045
+ const buffer = Buffer.from(terminal.output)
1046
+ // Keep the end, cut at a character boundary.
1047
+ terminal.output = buffer
1048
+ .subarray(buffer.length - limit)
1049
+ .toString('utf8')
1050
+ .replace(/^\ufffd+/, '')
1051
+ }
1052
+ }
1053
+ child.stdout.on('data', append)
1054
+ child.stderr.on('data', append)
1055
+ terminal.exited = new Promise((resolve) => {
1056
+ child.once('error', (error) => {
1057
+ append(`${error.message}\n`)
1058
+ terminal.exitStatus = { exitCode: 127, signal: null }
1059
+ resolve(terminal.exitStatus)
1060
+ })
1061
+ child.once('exit', (code, signalName) => {
1062
+ terminal.exitStatus = { exitCode: code, signal: signalName }
1063
+ resolve(terminal.exitStatus)
1064
+ })
1065
+ })
1066
+ const terminalId = `term_${randomBytes(6).toString('hex')}`
1067
+ this.terminals.set(terminalId, terminal)
1068
+ this.turn?.queue.push({
1069
+ type: 'tool',
1070
+ id: `acp-${terminalId}`,
1071
+ name: 'execute',
1072
+ label: 'Ran a command',
1073
+ state: 'running',
1074
+ detail: shown,
1075
+ })
1076
+ terminal.exited.then((status) => {
1077
+ this.turn?.queue.push({
1078
+ type: 'tool',
1079
+ id: `acp-${terminalId}`,
1080
+ name: 'execute',
1081
+ label: 'Ran a command',
1082
+ state: status.exitCode === 0 ? 'done' : 'error',
1083
+ detail: shown,
1084
+ })
1085
+ })
1086
+ return { terminalId }
1087
+ }
1088
+
1089
+ terminal(params) {
1090
+ this.ownSession(params)
1091
+ const terminal = this.terminals.get(params.terminalId)
1092
+ if (!terminal) throw RequestError.invalidParams(undefined, 'unknown terminal')
1093
+ return terminal
1094
+ }
1095
+
1096
+ onTerminalOutput(params) {
1097
+ const terminal = this.terminal(params)
1098
+ return { output: terminal.output, truncated: terminal.truncated, ...(terminal.exitStatus ? { exitStatus: terminal.exitStatus } : {}) }
1099
+ }
1100
+
1101
+ async onTerminalWait(params) {
1102
+ return await this.terminal(params).exited
1103
+ }
1104
+
1105
+ onTerminalKill(params) {
1106
+ stopTree(this.terminal(params).child)
1107
+ return {}
1108
+ }
1109
+
1110
+ onTerminalRelease(params) {
1111
+ const terminal = this.terminal(params)
1112
+ stopTree(terminal.child)
1113
+ this.terminals.delete(params.terminalId)
1114
+ return {}
1115
+ }
1116
+ }
1117
+
1118
+ function sandboxRefusal(error) {
1119
+ if (error instanceof SandboxError) return new RequestError(-32000, error.message)
1120
+ return new RequestError(-32000, `refused: ${cut(error?.code || error?.message, 100)}`)
1121
+ }
1122
+
1123
+ // createAcpBackend(settings, { env, root, protect, limits, log })
1124
+ export function createAcpBackend(
1125
+ settings,
1126
+ {
1127
+ env = process.env,
1128
+ root,
1129
+ protect = [],
1130
+ sensitivePaths = [],
1131
+ limits = {},
1132
+ log = () => {},
1133
+ mcpServersFor = null,
1134
+ processPool = null,
1135
+ } = {},
1136
+ ) {
1137
+ const limit = { ...ACP_DEFAULTS, ...limits }
1138
+ const sandbox = createSandbox({ root, protect, sensitivePaths })
1139
+ const processes = new Map()
1140
+ // Agents still starting (initialize, session/new): counted and stopped too.
1141
+ const starting = new Set()
1142
+ let closed = false
1143
+
1144
+ const evictFor = () => {
1145
+ if (processes.size + starting.size < limit.processesMax) return
1146
+ const idle = [...processes.values()].filter((item) => !item.turn && item.state === 'ready').sort((a, b) => a.usedAt - b.usedAt)
1147
+ if (!idle.length) throw new AgentError('agent_busy', `${settings.label} is busy in other threads. Try again in a moment.`, 429)
1148
+ idle[0].kill('evicted')
1149
+ }
1150
+
1151
+ const start = async (thread, signal) => {
1152
+ evictFor()
1153
+ const agent = new AcpProcess({
1154
+ argv: settings.acp.argv,
1155
+ label: settings.label,
1156
+ env,
1157
+ sandbox,
1158
+ limits: limit,
1159
+ log,
1160
+ thread,
1161
+ mcpServers: mcpServersFor?.(thread) || [],
1162
+ onGone: (item) => {
1163
+ if (item.stopped || !item.pid) processPool?.agents.delete(item)
1164
+ if (processes.get(item.thread) === item) processes.delete(item.thread)
1165
+ },
1166
+ })
1167
+ if (closed) throw new AgentError('agent_start', 'The server is stopping.')
1168
+ if (processPool) await reserveProcessSlot(processPool, agent, signal)
1169
+ if (closed) {
1170
+ agent.kill('shutdown')
1171
+ await agent.stoppingPromise
1172
+ throw new AgentError('agent_start', 'The server is stopping.')
1173
+ }
1174
+ const pending = agent.start(signal)
1175
+ starting.add(agent)
1176
+ try {
1177
+ await pending
1178
+ } catch (error) {
1179
+ agent.kill('start_failed')
1180
+ await agent.stoppingPromise
1181
+ throw error
1182
+ } finally {
1183
+ starting.delete(agent)
1184
+ if (agent.stopped || !agent.pid) processPool?.agents.delete(agent)
1185
+ }
1186
+ if (closed) {
1187
+ agent.kill('shutdown')
1188
+ await agent.stoppingPromise
1189
+ throw new AgentError('agent_start', 'The server is stopping.')
1190
+ }
1191
+ if (agent.state !== 'ready') throw agent.exited ? agent.exitError() : new AgentError('agent_start', `${settings.label} did not start.`)
1192
+ processes.set(thread, agent)
1193
+ return agent
1194
+ }
1195
+
1196
+ return {
1197
+ id: 'acp',
1198
+ tools: 'own',
1199
+ // Off when the person said so in Settings > Agent; otherwise per agent,
1200
+ // from its initialize answer (promptCapabilities.image).
1201
+ vision: settings.vision !== false,
1202
+ label: settings.label,
1203
+ runMsMax: limit.runMs,
1204
+ async *stream({ messages, signal, thread = 'default' }) {
1205
+ if (signal?.aborted) return
1206
+ let agent = processes.get(thread)
1207
+ if (agent?.turn) await agent.settled()
1208
+ agent = processes.get(thread)
1209
+ if (!agent || agent.state !== 'ready') {
1210
+ yield { type: 'status', text: `Starting ${settings.label}` }
1211
+ agent = await start(thread, signal)
1212
+ for (const text of agent.choices) yield { type: 'notice', text }
1213
+ }
1214
+ if (signal?.aborted) {
1215
+ agent.kill('aborted')
1216
+ await agent.settled()
1217
+ return
1218
+ }
1219
+ yield { type: 'status', text: `${settings.label} is working` }
1220
+ const image = agent.image && settings.vision !== false
1221
+ if (!image && messages.at(-1)?.content?.some((part) => part.type === 'image')) yield { type: 'notice', text: NO_IMAGES_NOTE }
1222
+ const turn = agent.prompt(promptBlocks({ messages, fresh: agent.fresh, image, thread }), signal)
1223
+ try {
1224
+ for await (const event of turn.events) yield event
1225
+ } finally {
1226
+ turn.finish()
1227
+ await agent.settled()
1228
+ }
1229
+ },
1230
+ // The person's answer to a permission card: 'approved' | 'denied', false
1231
+ // for an option the card does not have, null when there is no such card.
1232
+ // "Clear this thread": the agent forgets too. Its process (and so its
1233
+ // session and memory) stops; the next message starts a fresh one.
1234
+ resetThread(thread) {
1235
+ processes.get(thread)?.kill('cleared')
1236
+ for (const agent of starting) if (agent.thread === thread) agent.kill('cleared')
1237
+ },
1238
+ answerPermission(thread, id, optionId, answeredBy = null) {
1239
+ return processes.get(thread)?.answer(id, optionId, answeredBy) ?? null
1240
+ },
1241
+ // The composer's model and effort pickers, for a thread whose session is
1242
+ // running (they come from session/new). Null without a session.
1243
+ sessionOptions(thread) {
1244
+ const agent = processes.get(thread)
1245
+ return agent && agent.state === 'ready' ? sessionOptions(agent.configOptions) : null
1246
+ },
1247
+ async setSessionOption(thread, configId, value) {
1248
+ const agent = processes.get(thread)
1249
+ if (!agent || agent.state !== 'ready')
1250
+ throw new AgentError('no_session', 'The agent session ended. Send a message, then choose again.', 409)
1251
+ return agent.setOption(configId, value)
1252
+ },
1253
+ processes: () =>
1254
+ [...processes.values(), ...starting].map((item) => ({
1255
+ thread: item.thread,
1256
+ pid: item.pid,
1257
+ state: item.state,
1258
+ busy: Boolean(item.turn),
1259
+ })),
1260
+ close() {
1261
+ closed = true
1262
+ for (const agent of [...processes.values(), ...starting]) agent.kill('shutdown')
1263
+ processes.clear()
1264
+ },
1265
+ }
1266
+ }
1267
+
1268
+ // `shapewall doctor`: starts the agent, does the initialize handshake, and
1269
+ // stops it again. Never sends a prompt (that would spend the subscription).
1270
+ export async function acpHandshake(settings, { env = process.env, root, timeoutMs = 30000, processPool = null } = {}) {
1271
+ const sandbox = createSandbox({ root })
1272
+ const agent = new AcpProcess({
1273
+ argv: settings.acp.argv,
1274
+ label: settings.label,
1275
+ env,
1276
+ sandbox,
1277
+ limits: { ...ACP_DEFAULTS, startMs: timeoutMs },
1278
+ log: () => {},
1279
+ thread: 'doctor',
1280
+ onGone: (item) => {
1281
+ if (item.stopped || !item.pid) processPool?.agents.delete(item)
1282
+ },
1283
+ })
1284
+ try {
1285
+ await reserveProcessSlot(processPool, agent)
1286
+ await agent.start()
1287
+ return { ok: true, agentInfo: agent.agentInfo, image: agent.image, choices: agent.choices }
1288
+ } catch (error) {
1289
+ return { ok: false, code: error.code, message: error.message }
1290
+ } finally {
1291
+ agent.kill('doctor')
1292
+ await agent.stoppingPromise
1293
+ // spawn can fail without an exit event; a dead child with no pid has
1294
+ // no process left to release its reservation through onGone.
1295
+ if (agent.stopped || !agent.pid) processPool?.agents.delete(agent)
1296
+ }
1297
+ }