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,61 @@
1
+ // Chat backends: what the chat panel talks to.
2
+ //
3
+ // A backend is an object:
4
+ //
5
+ // {
6
+ // id: 'openai-compatible',
7
+ // // 'shapewall': Shapewall offers its read-only board tools and runs them
8
+ // // (src/agent/tools.js). 'own': the agent has its own tools and reports
9
+ // // them as `tool` events (an ACP agent, later).
10
+ // tools: 'shapewall' | 'own' | 'none',
11
+ // vision: true, // takes image parts
12
+ // async *stream({ system, messages, tools, signal, thread }) { ... yield events ... },
13
+ // runMsMax?: 1200000, // how long one answer may take (default 5 minutes)
14
+ // answerPermission?(thread, id, optionId), // the person's answer to a permission card
15
+ // close?(), // stop what the backend started (server shutdown)
16
+ // }
17
+ //
18
+ // `thread` is "<board>/<thread>": a backend with a process per thread (ACP)
19
+ // keeps it across turns.
20
+ //
21
+ // `messages` are neutral: { role: 'user' | 'assistant' | 'tool', content: [{ type: 'text', text } |
22
+ // { type: 'image', mediaType, data }], toolCalls?: [{ id, name, args }], toolCallId? }. `system` is
23
+ // Shapewall's own prompt; board and comment text never goes there (src/agent/context.js).
24
+ //
25
+ // Events a backend yields:
26
+ // { type: 'text', text } answer text, streamed
27
+ // { type: 'reasoning', text } model thinking, shown collapsed
28
+ // { type: 'status', text } a short status line
29
+ // { type: 'tool_call', id, name, args } the model asks for a Shapewall tool (tools: 'shapewall')
30
+ // { type: 'tool', id, name, label?, state, detail? } the agent ran its own tool (tools: 'own'); state running | done | error
31
+ // { type: 'plan', entries: [{ content, status }] } the agent's plan (tools: 'own')
32
+ // { type: 'permission', id, title, kind, detail, options, state, chosen, expiresAt }
33
+ // the agent asks before it acts; state pending, then
34
+ // approved | denied | expired | cancelled
35
+ // { type: 'done', finishReason } the turn ended
36
+ // Errors are thrown as AgentError (code, message), with any secret removed.
37
+ //
38
+ // The sandboxed starter agent plugs in here as another backend.
39
+
40
+ import { createAcpBackend } from './acp.js'
41
+ import { createOpenAIBackend } from './openai.js'
42
+
43
+ export { AgentError } from '../errors.js'
44
+
45
+ const FACTORIES = {
46
+ 'openai-compatible': createOpenAIBackend,
47
+ acp: createAcpBackend,
48
+ }
49
+
50
+ // The backend for these settings (src/agent/config.js agentSettings), or
51
+ // null when chat is not connected. `root` (the project) and `protect` (the
52
+ // Shapewall store) are for ACP: what an agent may read and write.
53
+ export function createBackend(
54
+ settings,
55
+ { env = process.env, fetchImpl = globalThis.fetch, root, protect, sensitivePaths, limits, log, mcpServersFor, processPool } = {},
56
+ ) {
57
+ if (!settings.configured) return null
58
+ const factory = FACTORIES[settings.backend]
59
+ if (!factory) return null
60
+ return factory(settings, { env, fetchImpl, root, protect, sensitivePaths, limits, log, mcpServersFor, processPool })
61
+ }
@@ -0,0 +1,308 @@
1
+ // The OpenAI-compatible chat completions backend: POST {baseUrl}/chat/completions
2
+ // with stream: true, read the server-sent events back. Works with OpenAI,
3
+ // DeepSeek, xAI, OpenRouter, Ollama, LM Studio, vLLM and anything else that
4
+ // speaks the same API. The key (optional, for local servers) is read from the
5
+ // environment per request and removed from any error text.
6
+
7
+ import { agentKey } from '../config.js'
8
+ import { NO_IMAGES_NOTE } from '../context.js'
9
+ import { AgentError } from '../errors.js'
10
+
11
+ const CONNECT_TIMEOUT_MS = 60000
12
+ // The composer's model picker: the endpoint's list, kept 10 minutes.
13
+ const MODELS_CACHE_MS = 10 * 60 * 1000
14
+ const MODELS_TIMEOUT_MS = 5000
15
+ export const MODELS_MAX = 100
16
+ const ERROR_BODY_MAX = 4000
17
+
18
+ // Neutral messages (backends/index.js) to the chat completions shape.
19
+ export function toOpenAIMessages(system, messages, { vision }) {
20
+ const out = [{ role: 'system', content: system }]
21
+ for (const message of messages) {
22
+ if (message.role === 'tool') {
23
+ out.push({ role: 'tool', tool_call_id: message.toolCallId, content: textOf(message.content) })
24
+ continue
25
+ }
26
+ if (message.role === 'assistant') {
27
+ const entry = { role: 'assistant', content: textOf(message.content) || (message.toolCalls?.length ? null : '') }
28
+ if (message.toolCalls?.length) {
29
+ entry.tool_calls = message.toolCalls.map((call) => ({
30
+ id: call.id,
31
+ type: 'function',
32
+ function: { name: call.name, arguments: JSON.stringify(call.args ?? {}) },
33
+ }))
34
+ }
35
+ out.push(entry)
36
+ continue
37
+ }
38
+ const parts = []
39
+ for (const part of message.content) {
40
+ if (part.type === 'text') parts.push({ type: 'text', text: part.text })
41
+ else if (part.type === 'image' && vision)
42
+ parts.push({ type: 'image_url', image_url: { url: `data:${part.mediaType};base64,${part.data}` } })
43
+ else if (part.type === 'image') parts.push({ type: 'text', text: '[An image was attached, but this model does not take images.]' })
44
+ }
45
+ // Text-only messages as a plain string: some servers take nothing else.
46
+ out.push({ role: 'user', content: parts.every((part) => part.type === 'text') ? parts.map((part) => part.text).join('\n\n') : parts })
47
+ }
48
+ return out
49
+ }
50
+
51
+ function textOf(content) {
52
+ return (content || [])
53
+ .filter((part) => part.type === 'text')
54
+ .map((part) => part.text)
55
+ .join('\n\n')
56
+ }
57
+
58
+ function toOpenAITools(tools) {
59
+ return tools.map((tool) => ({
60
+ type: 'function',
61
+ function: { name: tool.name, description: tool.description, parameters: tool.parameters },
62
+ }))
63
+ }
64
+
65
+ // Keeps a secret out of anything shown or logged.
66
+ export function redact(text, secret) {
67
+ let value = String(text ?? '')
68
+ if (secret) value = value.split(secret).join('[redacted]')
69
+ return value.replace(/\b(sk|gsk|xai|key)-[A-Za-z0-9_-]{8,}/g, '[redacted]')
70
+ }
71
+
72
+ // Reads a server-sent event stream: yields each `data:` payload.
73
+ async function* sseData(body, signal) {
74
+ const decoder = new TextDecoder()
75
+ let buffer = ''
76
+ for await (const chunk of body) {
77
+ if (signal?.aborted) return
78
+ buffer += decoder.decode(chunk, { stream: true })
79
+ let index
80
+ while ((index = buffer.search(/\r?\n\r?\n/)) >= 0) {
81
+ const block = buffer.slice(0, index)
82
+ buffer = buffer.slice(index).replace(/^\r?\n\r?\n/, '')
83
+ const data = block
84
+ .split(/\r?\n/)
85
+ .filter((line) => line.startsWith('data:'))
86
+ .map((line) => line.slice(5).replace(/^ /, ''))
87
+ .join('\n')
88
+ if (data) yield data
89
+ }
90
+ }
91
+ const rest = buffer.trim()
92
+ if (rest.startsWith('data:')) yield rest.slice(5).trim()
93
+ }
94
+
95
+ export function upstreamError(status, bodyText, key) {
96
+ let message = ''
97
+ try {
98
+ const json = JSON.parse(bodyText)
99
+ message = json?.error?.message || json?.message || (typeof json?.error === 'string' ? json.error : '')
100
+ } catch {
101
+ message = bodyText
102
+ }
103
+ message = redact(String(message || '').slice(0, 300), key).trim()
104
+ const suffix = message ? `: ${message}` : ''
105
+ if (status === 401 || status === 403) return new AgentError('agent_auth', `The model endpoint refused the API key (${status})${suffix}`)
106
+ if (status === 404) return new AgentError('agent_not_found', `The model endpoint or model was not found (404)${suffix}`)
107
+ if (status === 429) return new AgentError('agent_rate_limited', `The model endpoint is rate limiting or out of credit (429)${suffix}`)
108
+ return new AgentError('agent_upstream', `The model endpoint answered ${status}${suffix}`)
109
+ }
110
+
111
+ // Servers and models without function calling answer 400 to `tools`.
112
+ const TOOLS_UNSUPPORTED = /tool|function/i
113
+ const USAGE_UNSUPPORTED = /stream_options|include_usage/i
114
+ // Models without vision answer 400 to image parts ("Multimodal data
115
+ // provided, but model does not support multimodal requests", "image_url is
116
+ // not supported", ...).
117
+ const IMAGES_UNSUPPORTED = /image|vision|multimodal|multi-modal/i
118
+
119
+ const hasImages = (messages) => messages.some((message) => (message.content || []).some((part) => part.type === 'image'))
120
+
121
+ // Token counts as the endpoint reports them (the starter agent's budget).
122
+ function usageEvent(usage) {
123
+ const prompt = Number(usage?.prompt_tokens) || 0
124
+ const completion = Number(usage?.completion_tokens) || 0
125
+ const total = Number(usage?.total_tokens) || prompt + completion
126
+ return { type: 'usage', prompt, completion, total }
127
+ }
128
+
129
+ export function createOpenAIBackend(settings, { env = process.env, fetchImpl = globalThis.fetch } = {}) {
130
+ // Learned per server process and model: once a model refuses tools, ask without them.
131
+ const toolsRefused = new Set()
132
+ // settings.usage asks for token counts (stream_options.include_usage);
133
+ // a server that refuses it is asked again without.
134
+ let usageRefused = false
135
+ // Once the endpoint refuses images, this model gets none (the chat says so).
136
+ const imagesRefused = new Set()
137
+ // The endpoint's own model list (GET {baseUrl}/models), for the composer's
138
+ // picker: cached, bounded, and empty when the endpoint has none.
139
+ let models = null
140
+ return {
141
+ id: 'openai-compatible',
142
+ tools: settings.tools ? 'shapewall' : 'none',
143
+ vision: settings.vision,
144
+ async listModels() {
145
+ if (models && Date.now() - models.at < MODELS_CACHE_MS) return models.ids
146
+ const key = agentKey(settings, env)
147
+ const controller = new AbortController()
148
+ const timer = setTimeout(() => controller.abort(), MODELS_TIMEOUT_MS)
149
+ let ids = []
150
+ try {
151
+ const response = await fetchImpl(`${settings.baseUrl}/models`, {
152
+ method: 'GET',
153
+ headers: { Accept: 'application/json', ...(key ? { Authorization: `Bearer ${key}` } : {}) },
154
+ signal: controller.signal,
155
+ redirect: 'error',
156
+ })
157
+ if (response.ok) {
158
+ const json = await response.json().catch(() => null)
159
+ ids = [...new Set((Array.isArray(json?.data) ? json.data : []).map((item) => String(item?.id ?? '')))]
160
+ // eslint-disable-next-line no-control-regex
161
+ .filter((id) => id && id.length <= 200 && !/[\u0000-\u001f\u007f]/.test(id))
162
+ .sort((a, b) => a.localeCompare(b))
163
+ .slice(0, MODELS_MAX)
164
+ }
165
+ } catch {
166
+ ids = []
167
+ } finally {
168
+ clearTimeout(timer)
169
+ }
170
+ models = { at: Date.now(), ids }
171
+ return ids
172
+ },
173
+ // `model`: this chat's choice from the endpoint's own list (the
174
+ // composer's picker, routes.js); the configured model otherwise.
175
+ async *stream({ system, messages, tools = [], signal, model: chosen = null }) {
176
+ const model = chosen || settings.model
177
+ const key = agentKey(settings, env)
178
+ const vision = settings.vision && !imagesRefused.has(model)
179
+ const withImages = vision && hasImages(messages)
180
+ if (imagesRefused.has(model) && hasImages(messages.slice(-1))) yield { type: 'notice', text: NO_IMAGES_NOTE }
181
+ const useTools = tools.length > 0 && !toolsRefused.has(model)
182
+ const body = {
183
+ model,
184
+ stream: true,
185
+ messages: toOpenAIMessages(system, messages, { vision }),
186
+ }
187
+ if (useTools) body.tools = toOpenAITools(tools)
188
+ const useUsage = Boolean(settings.usage) && !usageRefused
189
+ if (useUsage) body.stream_options = { include_usage: true }
190
+ if (settings.maxTokens) body.max_tokens = settings.maxTokens
191
+ if (settings.temperature !== null && settings.temperature !== undefined) body.temperature = settings.temperature
192
+ const headers = { 'Content-Type': 'application/json', Accept: 'text/event-stream' }
193
+ if (key) headers.Authorization = `Bearer ${key}`
194
+
195
+ const connect = new AbortController()
196
+ // settings.connectTimeoutMs 0: no limit here (the starter agent's host
197
+ // relay keeps the time and says what happened).
198
+ const connectMs = settings.connectTimeoutMs ?? CONNECT_TIMEOUT_MS
199
+ const timer = connectMs ? setTimeout(() => connect.abort(), connectMs) : null
200
+ const onAbort = () => connect.abort()
201
+ signal?.addEventListener('abort', onAbort, { once: true })
202
+ let response
203
+ try {
204
+ response = await fetchImpl(`${settings.baseUrl}/chat/completions`, {
205
+ method: 'POST',
206
+ headers,
207
+ body: JSON.stringify(body),
208
+ signal: connect.signal,
209
+ redirect: 'error',
210
+ })
211
+ } catch (error) {
212
+ clearTimeout(timer)
213
+ signal?.removeEventListener('abort', onAbort)
214
+ if (signal?.aborted) return
215
+ if (error?.relayed) throw new AgentError('agent_unreachable', redact(error.message, key))
216
+ const reason = connect.signal.aborted ? 'timed out' : redact(error.cause?.code || error.message, key)
217
+ throw new AgentError('agent_unreachable', `Could not reach the model endpoint (${reason}).`)
218
+ }
219
+ clearTimeout(timer)
220
+ try {
221
+ if (!response.ok) {
222
+ const text = (await response.text().catch(() => '')).slice(0, ERROR_BODY_MAX)
223
+ if (useTools && response.status === 400 && TOOLS_UNSUPPORTED.test(text)) {
224
+ toolsRefused.add(model)
225
+ yield { type: 'status', text: 'This model does not use tools; asking without them' }
226
+ yield* this.stream({ system, messages, tools: [], signal, model: chosen })
227
+ return
228
+ }
229
+ if (withImages && response.status === 400 && IMAGES_UNSUPPORTED.test(text)) {
230
+ // Once more without the images, instead of the raw 400.
231
+ imagesRefused.add(model)
232
+ if (!hasImages(messages.slice(-1))) yield { type: 'notice', text: NO_IMAGES_NOTE }
233
+ yield* this.stream({ system, messages, tools, signal, model: chosen })
234
+ return
235
+ }
236
+ if (useUsage && response.status === 400 && USAGE_UNSUPPORTED.test(text)) {
237
+ usageRefused = true
238
+ yield* this.stream({ system, messages, tools, signal, model: chosen })
239
+ return
240
+ }
241
+ throw upstreamError(response.status, text, key)
242
+ }
243
+ const type = String(response.headers.get('content-type') || '')
244
+ if (!type.includes('text/event-stream')) {
245
+ // A server that ignored stream: true answers with one JSON body.
246
+ const json = await response.json().catch(() => null)
247
+ const choice = json?.choices?.[0]
248
+ if (!choice) throw new AgentError('agent_upstream', 'The model endpoint did not answer in the chat completions format.')
249
+ if (json.usage) yield usageEvent(json.usage)
250
+ if (choice.message?.content) yield { type: 'text', text: String(choice.message.content) }
251
+ for (const call of choice.message?.tool_calls || []) yield toolCall(call.id, call.function?.name, call.function?.arguments)
252
+ yield { type: 'done', finishReason: choice.finish_reason || 'stop' }
253
+ return
254
+ }
255
+ const calls = new Map()
256
+ let finishReason = null
257
+ for await (const data of sseData(response.body, signal)) {
258
+ if (data === '[DONE]') break
259
+ let chunk
260
+ try {
261
+ chunk = JSON.parse(data)
262
+ } catch {
263
+ continue
264
+ }
265
+ if (chunk.error) throw upstreamError(500, JSON.stringify(chunk), key)
266
+ if (chunk.usage) yield usageEvent(chunk.usage)
267
+ const choice = chunk.choices?.[0]
268
+ if (!choice) continue
269
+ const delta = choice.delta || {}
270
+ const reasoning = delta.reasoning_content ?? delta.reasoning
271
+ if (typeof reasoning === 'string' && reasoning) yield { type: 'reasoning', text: reasoning }
272
+ if (typeof delta.content === 'string' && delta.content) yield { type: 'text', text: delta.content }
273
+ for (const part of delta.tool_calls || []) {
274
+ const index = part.index ?? calls.size
275
+ const call = calls.get(index) || { id: '', name: '', args: '' }
276
+ if (part.id) call.id = part.id
277
+ if (part.function?.name) call.name += part.function.name
278
+ if (part.function?.arguments) call.args += part.function.arguments
279
+ calls.set(index, call)
280
+ }
281
+ if (choice.finish_reason) finishReason = choice.finish_reason
282
+ }
283
+ if (signal?.aborted) return
284
+ for (const [index, call] of [...calls.entries()].sort((a, b) => a[0] - b[0])) {
285
+ yield toolCall(call.id || `call_${index}`, call.name, call.args)
286
+ }
287
+ yield { type: 'done', finishReason: finishReason || 'stop' }
288
+ } catch (error) {
289
+ if (signal?.aborted) return
290
+ if (error instanceof AgentError) throw error
291
+ if (error?.relayed) throw new AgentError('agent_upstream', redact(error.message, key))
292
+ throw new AgentError('agent_upstream', `The model stream broke off (${redact(error.message, key)}).`)
293
+ } finally {
294
+ signal?.removeEventListener('abort', onAbort)
295
+ }
296
+ },
297
+ }
298
+ }
299
+
300
+ function toolCall(id, name, rawArgs) {
301
+ let args = {}
302
+ try {
303
+ args = rawArgs ? JSON.parse(rawArgs) : {}
304
+ } catch {
305
+ args = { _invalid: String(rawArgs).slice(0, 200) }
306
+ }
307
+ return { type: 'tool_call', id: String(id || ''), name: String(name || ''), args }
308
+ }
@@ -0,0 +1,221 @@
1
+ // What the chat composer adds to a message besides text and images:
2
+ //
3
+ // - mentions: board things picked with "@" in the composer (a page, a
4
+ // comment, a journey, a commented element, a person). The board sends ids
5
+ // only; the server checks each one against this board, stores a label, and
6
+ // gives the model the item's details as quoted data (context.js).
7
+ // - files: small text files (a log, Markdown, JSON, CSV), sent as text and
8
+ // stored with the message. Their content is untrusted data too.
9
+
10
+ import { listComments } from '../store.js'
11
+ import { listJourneys } from '../journeys.js'
12
+ import { MENTION_HANDLE_RE, commentMentions, handleFor } from '../mentions.js'
13
+ import { quoteData } from './context.js'
14
+ import { AgentError } from './errors.js'
15
+ import { commentForModel } from './tools.js'
16
+
17
+ export const MENTIONS_MAX = 8
18
+ export const FILES_MAX = 3
19
+ export const FILE_CHARS_MAX = 100 * 1000
20
+ const LABEL_MAX = 80
21
+ const NAME_MAX = 120
22
+ // Text files by extension: the type the board declares must be one of these.
23
+ export const TEXT_FILE_TYPES = {
24
+ txt: 'text/plain',
25
+ log: 'text/plain',
26
+ md: 'text/markdown',
27
+ markdown: 'text/markdown',
28
+ json: 'application/json',
29
+ csv: 'text/csv',
30
+ }
31
+ const MENTION_KINDS = ['page', 'comment', 'journey', 'element', 'person']
32
+ const PERSON_COMMENTS_MAX = 10
33
+ const BODY_MAX = 600
34
+
35
+ const cut = (value, max) => {
36
+ const text = String(value ?? '')
37
+ .replace(/\s+/g, ' ')
38
+ .trim()
39
+ return text.length > max ? `${text.slice(0, max - 1)}…` : text
40
+ }
41
+ const commentById = (config, board) => {
42
+ let cache = null
43
+ return (id) => {
44
+ cache ||= new Map(listComments(config, board.id).map((comment) => [comment.id, comment]))
45
+ return cache.get(id) || null
46
+ }
47
+ }
48
+
49
+ // Checks the mentions of a message: [{ kind, id }] -> [{ kind, id, label }],
50
+ // every one on this board, no repeats. An unknown one is refused, so the
51
+ // person never sends a message that silently lost its context.
52
+ export function validateMentions(config, board, raw) {
53
+ if (raw === undefined || raw === null) return []
54
+ if (!Array.isArray(raw) || raw.length > MENTIONS_MAX)
55
+ throw new AgentError('bad_mention', `Mention at most ${MENTIONS_MAX} things in a message.`, 400)
56
+ const comment = commentById(config, board)
57
+ let journeys = null
58
+ const seen = new Set()
59
+ const out = []
60
+ for (const item of raw) {
61
+ const kind = item?.kind
62
+ if (!MENTION_KINDS.includes(kind)) throw new AgentError('bad_mention', 'A mention is a page, comment, journey, element or person.', 400)
63
+ let entry = null
64
+ if (kind === 'page') {
65
+ const page = board.pages.find((value) => value.id === item.id)
66
+ if (page) entry = { kind, id: page.id, label: cut(page.title || page.id, LABEL_MAX) }
67
+ } else if (kind === 'comment' || kind === 'element') {
68
+ const id = Number(item.id)
69
+ const found = Number.isSafeInteger(id) && id > 0 ? comment(id) : null
70
+ if (found && (kind === 'comment' || found.anchor)) {
71
+ const text = kind === 'element' ? found.anchor?.text || found.anchor?.selector || 'element' : found.body
72
+ entry = { kind, id: found.id, label: cut(`#${found.id} ${text}`, LABEL_MAX) }
73
+ }
74
+ } else if (kind === 'journey') {
75
+ journeys ||= listJourneys(config, board)
76
+ const journey = journeys.find((value) => value.id === item.id)
77
+ if (journey) entry = { kind, id: journey.id, label: cut(journey.name || journey.id, LABEL_MAX) }
78
+ } else if (kind === 'person') {
79
+ const handle = String(item.id || '').toLowerCase()
80
+ if (MENTION_HANDLE_RE.test(handle)) entry = { kind, id: handle, label: `@${handle}` }
81
+ }
82
+ if (!entry) throw new AgentError('bad_mention', `That ${kind} is not on this board any more. Remove it and send again.`, 400)
83
+ const key = `${entry.kind}:${entry.id}`
84
+ if (seen.has(key)) continue
85
+ seen.add(key)
86
+ out.push(entry)
87
+ }
88
+ return out
89
+ }
90
+
91
+ const cleanName = (value, fallback) =>
92
+ String(value || '')
93
+ // eslint-disable-next-line no-control-regex
94
+ .replace(/[\u0000-\u001f\u007f<>/\\]/g, '')
95
+ .trim()
96
+ .slice(0, NAME_MAX) || fallback
97
+
98
+ // Checks the text files of a message: [{ name, mediaType, text }]. The
99
+ // extension decides the type; binary content (a NUL byte) is refused.
100
+ export function validateFiles(raw) {
101
+ if (raw === undefined || raw === null) return []
102
+ if (!Array.isArray(raw) || raw.length > FILES_MAX)
103
+ throw new AgentError('too_many_files', `Attach at most ${FILES_MAX} text files to a message.`, 400)
104
+ return raw.map((item, index) => {
105
+ const name = cleanName(item?.name, `file-${index + 1}.txt`)
106
+ const ext = /\.([a-z]{2,8})$/i.exec(name)?.[1]?.toLowerCase()
107
+ const mediaType = TEXT_FILE_TYPES[ext]
108
+ if (!mediaType || (item?.mediaType && item.mediaType !== mediaType && item.mediaType !== 'text/plain'))
109
+ throw new AgentError('bad_file', 'Attach text files: .txt, .log, .md, .json or .csv.', 400)
110
+ if (typeof item?.text !== 'string') throw new AgentError('bad_file', 'A text file has no text.', 400)
111
+ const text = item.text.replace(/\r\n/g, '\n')
112
+ if (text.includes('\u0000')) throw new AgentError('bad_file', `${name} is not a text file.`, 400)
113
+ if (text.length > FILE_CHARS_MAX) throw new AgentError('file_too_big', `A text file is at most ${FILE_CHARS_MAX / 1000} KB.`, 413)
114
+ return { name, mediaType, bytes: Buffer.byteLength(text), text }
115
+ })
116
+ }
117
+
118
+ // The quoted data for one mention: what the model needs to know about it.
119
+ export function mentionContext(config, board, mention, find = commentById(config, board)) {
120
+ const attrs = { board: board.id, kind: mention.kind }
121
+ if (mention.kind === 'page') {
122
+ const page = board.pages.find((value) => value.id === mention.id)
123
+ if (!page) return null
124
+ return quoteData('mention', { ...attrs, page: page.id }, { page: { id: page.id, title: page.title, path: page.path, note: page.note } })
125
+ }
126
+ if (mention.kind === 'comment' || mention.kind === 'element') {
127
+ const comment = find(mention.id)
128
+ if (!comment) return null
129
+ if (mention.kind === 'comment') return quoteData('mention', { ...attrs, comment: comment.id }, commentForModel(config, board, comment))
130
+ const page = board.pages.find((value) => value.id === comment.pageId)
131
+ return quoteData(
132
+ 'mention',
133
+ { ...attrs, comment: comment.id, page: comment.pageId },
134
+ {
135
+ element: { selector: comment.anchor?.selector || null, text: comment.anchor?.text || null },
136
+ page: page ? { id: page.id, title: page.title, path: page.path } : { id: comment.pageId },
137
+ viewport: comment.viewport,
138
+ comment: { id: comment.id, body: cut(comment.body, BODY_MAX), status: comment.status },
139
+ },
140
+ )
141
+ }
142
+ if (mention.kind === 'journey') {
143
+ const journey = listJourneys(config, board).find((value) => value.id === mention.id)
144
+ if (!journey) return null
145
+ const titles = new Map(board.pages.map((page) => [page.id, page.title]))
146
+ return quoteData(
147
+ 'mention',
148
+ { ...attrs, journey: journey.id },
149
+ {
150
+ journey: {
151
+ id: journey.id,
152
+ name: journey.name,
153
+ description: journey.description || undefined,
154
+ pages: (journey.pages || []).map((id) => ({ id, title: titles.get(id) || id })),
155
+ },
156
+ },
157
+ )
158
+ }
159
+ if (mention.kind === 'person') {
160
+ const handle = mention.id
161
+ const theirs = listComments(config, board.id).filter(
162
+ (comment) =>
163
+ comment.status === 'open' &&
164
+ (handleFor(comment.author) === handle ||
165
+ String(comment.authorHandle || '').toLowerCase() === handle ||
166
+ commentMentions(comment).includes(handle)),
167
+ )
168
+ return quoteData(
169
+ 'mention',
170
+ { ...attrs, person: handle },
171
+ {
172
+ person: `@${handle}`,
173
+ openComments: theirs
174
+ .slice(0, PERSON_COMMENTS_MAX)
175
+ .map((comment) => ({ id: comment.id, page: comment.pageId, author: comment.author || null, body: cut(comment.body, 300) })),
176
+ more: Math.max(0, theirs.length - PERSON_COMMENTS_MAX) || undefined,
177
+ },
178
+ )
179
+ }
180
+ return null
181
+ }
182
+
183
+ // A text file, as quoted data.
184
+ export function fileContext(board, file) {
185
+ return quoteData('file', { board: board.id, name: file.name }, { name: file.name, type: file.mediaType, text: file.text })
186
+ }
187
+
188
+ // The text parts for a stored message's mentions and files (run.js
189
+ // modelMessages). `full`: the details (the last few person messages, like
190
+ // images); older messages get one line each, so a long thread stays small.
191
+ export function composerParts(config, board, message, { full = true } = {}) {
192
+ const parts = []
193
+ const mentions = Array.isArray(message.mentions) ? message.mentions : []
194
+ const files = Array.isArray(message.files) ? message.files : []
195
+ if (!mentions.length && !files.length) return parts
196
+ const find = commentById(config, board)
197
+ for (const mention of mentions) {
198
+ const text = full ? mentionContext(config, board, mention, find) : null
199
+ // The label can be comment text: quoted like everything from the board.
200
+ parts.push({
201
+ type: 'text',
202
+ text:
203
+ text ||
204
+ quoteData(
205
+ 'mention',
206
+ { board: board.id, kind: mention.kind },
207
+ { id: mention.id, label: cut(mention.label || mention.id, LABEL_MAX) },
208
+ ),
209
+ })
210
+ }
211
+ for (const file of files) {
212
+ parts.push({
213
+ type: 'text',
214
+ text:
215
+ full && typeof file.text === 'string'
216
+ ? fileContext(board, file)
217
+ : quoteData('file', { board: board.id, earlier: 'true' }, { name: file.name, note: 'attached earlier' }),
218
+ })
219
+ }
220
+ return parts
221
+ }