shapewall 0.0.0-stage → 0.2.1

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 (302) hide show
  1. package/CHANGELOG.md +127 -0
  2. package/Dockerfile.agent +45 -0
  3. package/LICENSE +202 -0
  4. package/NOTICE +12 -0
  5. package/README.md +659 -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/AgentSettings-CEOkftKf.js +1 -0
  10. package/dist/client/assets/BoardChat-DyD_rQlA.js +30 -0
  11. package/dist/client/assets/BuzzDialog-DAdMz66r.js +1 -0
  12. package/dist/client/assets/ChecksPanel-Due6G_M8.js +1 -0
  13. package/dist/client/assets/History-DxCP1-IS.js +1 -0
  14. package/dist/client/assets/LocalSettings-BVVleHqg.js +1 -0
  15. package/dist/client/assets/Management-BkQimoMa.js +1 -0
  16. package/dist/client/assets/ShareDialog-D9mIRVJ4.js +2 -0
  17. package/dist/client/assets/app-update-dialog-BNJaXH1v.js +1 -0
  18. package/dist/client/assets/circle-x-B5smn8Mj.js +1 -0
  19. package/dist/client/assets/index-BHbxSLS4.js +65 -0
  20. package/dist/client/assets/index-DqWPr45k.css +2 -0
  21. package/dist/client/assets/refresh-cw-SqPU2sKl.js +1 -0
  22. package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
  23. package/dist/client/assets/square-hda22GRT.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/build-info.json +1 -0
  34. package/dist/client/favicon.svg +7 -0
  35. package/dist/client/icons/apple-touch-icon.png +0 -0
  36. package/dist/client/icons/icon-192.png +0 -0
  37. package/dist/client/icons/icon-512.png +0 -0
  38. package/dist/client/icons/maskable-512.png +0 -0
  39. package/dist/client/index.html +24 -0
  40. package/dist/client/manifest.webmanifest +15 -0
  41. package/dist/client/sw.js +53 -0
  42. package/dist/client/theme-boot.js +27 -0
  43. package/dist/console/assets/LocalAccountsApp-Dea93fL3.js +1 -0
  44. package/dist/console/assets/LocalConsole-D-TJ53EA.js +1 -0
  45. package/dist/console/assets/app-update-dialog-C5JVG7ck.js +1 -0
  46. package/dist/console/assets/console-DybJNLin.css +2 -0
  47. package/dist/console/assets/console-lpozP2ju.js +51 -0
  48. package/dist/console/build-info.json +1 -0
  49. package/dist/console/console.html +21 -0
  50. package/dist/console/favicon.svg +7 -0
  51. package/dist/console/icons/apple-touch-icon.png +0 -0
  52. package/dist/console/icons/icon-192.png +0 -0
  53. package/dist/console/icons/icon-512.png +0 -0
  54. package/dist/console/icons/maskable-512.png +0 -0
  55. package/dist/console/manifest.webmanifest +15 -0
  56. package/dist/console/theme-boot.js +27 -0
  57. package/docs/agent-hardening.md +342 -0
  58. package/docs/agent-recipes.md +187 -0
  59. package/docs/agent-workflow.md +320 -0
  60. package/docs/agents.md +858 -0
  61. package/docs/architecture.md +242 -0
  62. package/docs/buzz.md +140 -0
  63. package/docs/capture-warnings.md +57 -0
  64. package/docs/config.md +489 -0
  65. package/docs/deployment.md +290 -0
  66. package/docs/design-system.md +141 -0
  67. package/docs/github.md +107 -0
  68. package/docs/hosted.md +766 -0
  69. package/docs/images/board-overview.png +0 -0
  70. package/docs/images/journeys.png +0 -0
  71. package/docs/images/live-comment.png +0 -0
  72. package/docs/images/phone-comment.png +0 -0
  73. package/docs/images/phone-overview.png +0 -0
  74. package/docs/images/variant.png +0 -0
  75. package/docs/interaction-audits.md +40 -0
  76. package/docs/journeys.md +137 -0
  77. package/docs/local-accounts.md +80 -0
  78. package/docs/notifications.md +237 -0
  79. package/docs/page-checks.md +69 -0
  80. package/docs/performance.md +174 -0
  81. package/docs/starter-agent.md +325 -0
  82. package/docs/updates.md +87 -0
  83. package/examples/audits/interaction.audit.json +17 -0
  84. package/package.json +132 -4
  85. package/src/accounts/avatar.js +121 -0
  86. package/src/accounts/local.js +464 -0
  87. package/src/agent/acp/command.js +204 -0
  88. package/src/agent/acp/detect.js +75 -0
  89. package/src/agent/acp/sandbox.js +160 -0
  90. package/src/agent/backends/acp.js +1297 -0
  91. package/src/agent/backends/index.js +61 -0
  92. package/src/agent/backends/openai.js +308 -0
  93. package/src/agent/composer.js +221 -0
  94. package/src/agent/config.js +330 -0
  95. package/src/agent/context.js +191 -0
  96. package/src/agent/control.js +122 -0
  97. package/src/agent/errors.js +17 -0
  98. package/src/agent/feedback-loop.js +137 -0
  99. package/src/agent/manage.js +94 -0
  100. package/src/agent/next-steps.js +51 -0
  101. package/src/agent/owner-mcp.js +38 -0
  102. package/src/agent/plain-text.js +52 -0
  103. package/src/agent/ratings-core.js +213 -0
  104. package/src/agent/ratings.js +100 -0
  105. package/src/agent/reply-text.js +67 -0
  106. package/src/agent/routes.js +1047 -0
  107. package/src/agent/run.js +326 -0
  108. package/src/agent/settings-routes.js +637 -0
  109. package/src/agent/showable.js +23 -0
  110. package/src/agent/starter/approvals.js +181 -0
  111. package/src/agent/starter/build-image.js +90 -0
  112. package/src/agent/starter/cli.js +163 -0
  113. package/src/agent/starter/disk.js +53 -0
  114. package/src/agent/starter/doctor.js +180 -0
  115. package/src/agent/starter/egress-proxy.js +351 -0
  116. package/src/agent/starter/gate.js +90 -0
  117. package/src/agent/starter/loop.js +114 -0
  118. package/src/agent/starter/model-relay.js +289 -0
  119. package/src/agent/starter/pause.js +14 -0
  120. package/src/agent/starter/probe.js +272 -0
  121. package/src/agent/starter/prompt.js +41 -0
  122. package/src/agent/starter/push-guard.js +146 -0
  123. package/src/agent/starter/rpc.js +164 -0
  124. package/src/agent/starter/runtime.js +287 -0
  125. package/src/agent/starter/sandbox-main.js +121 -0
  126. package/src/agent/starter/settings.js +290 -0
  127. package/src/agent/starter/source.js +69 -0
  128. package/src/agent/starter/supervisor.js +755 -0
  129. package/src/agent/starter/sweep.js +46 -0
  130. package/src/agent/starter/tools.js +524 -0
  131. package/src/agent/starter/watch.js +84 -0
  132. package/src/agent/starter/worktree.js +409 -0
  133. package/src/agent/text-diff.js +210 -0
  134. package/src/agent/thread-history.js +223 -0
  135. package/src/agent/threads.js +399 -0
  136. package/src/agent/tools.js +200 -0
  137. package/src/agent/turn-changes.js +424 -0
  138. package/src/agent/undo-state.js +26 -0
  139. package/src/agent/user-settings.js +296 -0
  140. package/src/auth/record.js +375 -0
  141. package/src/broken-links.js +164 -0
  142. package/src/buzz/client.js +75 -0
  143. package/src/buzz/config.js +151 -0
  144. package/src/buzz/environment.js +13 -0
  145. package/src/buzz/gateway.js +192 -0
  146. package/src/buzz/routes.js +61 -0
  147. package/src/buzz/signer-child.js +205 -0
  148. package/src/buzz/store.js +89 -0
  149. package/src/buzz/transport.js +60 -0
  150. package/src/buzz/verify.js +140 -0
  151. package/src/capture/actions.js +159 -0
  152. package/src/capture/capture.js +776 -0
  153. package/src/capture/dom-names.js +189 -0
  154. package/src/capture/element-map.js +509 -0
  155. package/src/capture/live.js +827 -0
  156. package/src/capture/media-scheme.js +317 -0
  157. package/src/capture/network-summary.js +86 -0
  158. package/src/capture/pacing.js +34 -0
  159. package/src/capture/requests.js +167 -0
  160. package/src/capture/sanitize.js +752 -0
  161. package/src/checks/accessibility.js +134 -0
  162. package/src/checks/budgets.js +58 -0
  163. package/src/checks/cli.js +55 -0
  164. package/src/checks/comparison.js +113 -0
  165. package/src/checks/environments.js +32 -0
  166. package/src/checks/flow-config.js +82 -0
  167. package/src/checks/flow-origin.js +53 -0
  168. package/src/checks/flows.js +398 -0
  169. package/src/checks/lighthouse-auth.js +145 -0
  170. package/src/checks/lighthouse-findings.js +130 -0
  171. package/src/checks/lighthouse.js +395 -0
  172. package/src/checks/robots.js +85 -0
  173. package/src/checks/routes.js +52 -0
  174. package/src/checks/run-control.js +259 -0
  175. package/src/checks/runner.js +724 -0
  176. package/src/checks/schema.js +133 -0
  177. package/src/checks/seo-analysis.js +443 -0
  178. package/src/checks/seo-probe.js +190 -0
  179. package/src/checks/seo-snapshot.js +99 -0
  180. package/src/checks/store.js +214 -0
  181. package/src/checks/transport.js +47 -0
  182. package/src/cli/args.js +319 -0
  183. package/src/cli/capture.js +79 -0
  184. package/src/cli/commands.js +92 -0
  185. package/src/cli/comments.js +84 -0
  186. package/src/cli/help.js +243 -0
  187. package/src/cli/init.js +214 -0
  188. package/src/cli/misc.js +64 -0
  189. package/src/cli/notify.js +87 -0
  190. package/src/cli/open.js +22 -0
  191. package/src/cli/serve.js +274 -0
  192. package/src/cli/variant.js +82 -0
  193. package/src/cli/watch.js +70 -0
  194. package/src/cli.js +130 -0
  195. package/src/comment-fields.js +76 -0
  196. package/src/comments-cli.js +208 -0
  197. package/src/config-reload.js +100 -0
  198. package/src/config.js +1061 -0
  199. package/src/devices-cli.js +21 -0
  200. package/src/diff.js +95 -0
  201. package/src/discover.js +284 -0
  202. package/src/doctor.js +295 -0
  203. package/src/event-log.js +268 -0
  204. package/src/events-cli.js +102 -0
  205. package/src/events.js +113 -0
  206. package/src/export.js +119 -0
  207. package/src/feedback.js +246 -0
  208. package/src/github.js +551 -0
  209. package/src/hosted/LICENSE.md +105 -0
  210. package/src/hosted/access-cli.js +78 -0
  211. package/src/hosted/admin.js +682 -0
  212. package/src/hosted/agent-approvals.js +163 -0
  213. package/src/hosted/agent-policy.js +189 -0
  214. package/src/hosted/app.js +510 -0
  215. package/src/hosted/auth-routes.js +540 -0
  216. package/src/hosted/auth.js +536 -0
  217. package/src/hosted/backup.js +483 -0
  218. package/src/hosted/board-context.js +35 -0
  219. package/src/hosted/board-routes.js +486 -0
  220. package/src/hosted/board-view.js +94 -0
  221. package/src/hosted/clean-worker.js +24 -0
  222. package/src/hosted/cleaner.js +89 -0
  223. package/src/hosted/comments.js +355 -0
  224. package/src/hosted/console-routes.js +401 -0
  225. package/src/hosted/cookies.js +18 -0
  226. package/src/hosted/crypto.js +80 -0
  227. package/src/hosted/db.js +496 -0
  228. package/src/hosted/device-routes.js +175 -0
  229. package/src/hosted/device.js +233 -0
  230. package/src/hosted/events.js +63 -0
  231. package/src/hosted/guards.js +172 -0
  232. package/src/hosted/guest-view.js +65 -0
  233. package/src/hosted/http.js +39 -0
  234. package/src/hosted/import.js +300 -0
  235. package/src/hosted/mail.js +73 -0
  236. package/src/hosted/mcp-http.js +71 -0
  237. package/src/hosted/membership.js +114 -0
  238. package/src/hosted/operator.js +478 -0
  239. package/src/hosted/ops-cli.js +345 -0
  240. package/src/hosted/pages.js +146 -0
  241. package/src/hosted/permissions.js +113 -0
  242. package/src/hosted/presence.js +372 -0
  243. package/src/hosted/projects.js +124 -0
  244. package/src/hosted/public.js +109 -0
  245. package/src/hosted/push.js +622 -0
  246. package/src/hosted/quotas.js +115 -0
  247. package/src/hosted/ratelimit.js +96 -0
  248. package/src/hosted/rebind.js +316 -0
  249. package/src/hosted/retention.js +128 -0
  250. package/src/hosted/server.js +260 -0
  251. package/src/hosted/setup-link.js +64 -0
  252. package/src/hosted/setup.js +323 -0
  253. package/src/hosted/shares.js +444 -0
  254. package/src/hosted/tailscale.js +204 -0
  255. package/src/hosted/tenancy.js +301 -0
  256. package/src/hosted/token-api.js +455 -0
  257. package/src/hosted/token-events.js +60 -0
  258. package/src/hosted/tokens.js +57 -0
  259. package/src/hosted/turnstile.js +49 -0
  260. package/src/hosted/usercontent.js +154 -0
  261. package/src/hosted/zip.js +155 -0
  262. package/src/invocation.js +58 -0
  263. package/src/journey-paths.js +282 -0
  264. package/src/journeys.js +189 -0
  265. package/src/links.js +106 -0
  266. package/src/local-projects.js +182 -0
  267. package/src/lock.js +193 -0
  268. package/src/mcp.js +417 -0
  269. package/src/mentions.js +151 -0
  270. package/src/net.js +15 -0
  271. package/src/notify/config.js +275 -0
  272. package/src/notify/index.js +301 -0
  273. package/src/notify/lease.js +73 -0
  274. package/src/notify/messages.js +212 -0
  275. package/src/notify/run.js +174 -0
  276. package/src/pixeldiff.js +49 -0
  277. package/src/png.js +143 -0
  278. package/src/reactions.js +111 -0
  279. package/src/remote/cli.js +133 -0
  280. package/src/remote/credentials.js +62 -0
  281. package/src/remote/ids.js +12 -0
  282. package/src/remote/login.js +155 -0
  283. package/src/remote/remote-mcp.js +237 -0
  284. package/src/remote/remote-watch.js +291 -0
  285. package/src/remote/remote.js +313 -0
  286. package/src/remote/share-state.js +78 -0
  287. package/src/remote/share.js +369 -0
  288. package/src/remote/terminal.js +13 -0
  289. package/src/serve-state.js +64 -0
  290. package/src/server/app.js +823 -0
  291. package/src/server/devices.js +186 -0
  292. package/src/server/local-console.js +28 -0
  293. package/src/server/local-user.js +59 -0
  294. package/src/server/pairing-routes.js +159 -0
  295. package/src/server/share-routes.js +89 -0
  296. package/src/server/tailscale.js +97 -0
  297. package/src/sitemap.js +431 -0
  298. package/src/store.js +983 -0
  299. package/src/tokens.js +11 -0
  300. package/src/update/routes.js +245 -0
  301. package/src/watch.js +403 -0
  302. package/src/which.js +58 -0
@@ -0,0 +1,351 @@
1
+ // The starter agent's egress proxy: the only way out of the agent container.
2
+ //
3
+ // The agent container sits on an internal network with no route out and no
4
+ // outside DNS. This proxy runs in a second container on that network and on
5
+ // an ordinary one, and passes on exactly the host:port pairs it was given
6
+ // (the package registry, plus any the person added; the model is called
7
+ // from the host, not through here):
8
+ //
9
+ // - CONNECT host:port (https, and anything else tunnelled) only to an
10
+ // allowed pair;
11
+ // - plain http (absolute-form "GET http://host:port/path") only to an
12
+ // allowed pair, for local servers that speak http;
13
+ // - everything else answers 403, and each refusal is logged.
14
+ //
15
+ // Names are resolved here, then checked again by address: a name on the
16
+ // default list (the npm registry) that resolves to a private, loopback or
17
+ // link-local address is refused, so a rebinding DNS answer cannot turn it
18
+ // into a way onto the host's network. Pairs the person chose (--allow-host)
19
+ // may be private: a mirror on the LAN is the point of them.
20
+ //
21
+ // Configuration comes from the environment (no secret in it):
22
+ // SHAPEWALL_EGRESS_ALLOW "host:port,host:port!private,..." (!private: may resolve to a private address)
23
+ // SHAPEWALL_EGRESS_PORT default 3128
24
+ // Log lines are JSON on stdout: { ready }, { allow, host, port }, { deny, host, port, reason }.
25
+
26
+ import dns from 'node:dns/promises'
27
+ import http from 'node:http'
28
+ import net from 'node:net'
29
+ import { fileURLToPath } from 'node:url'
30
+
31
+ export const PROXY_PORT = 3128
32
+ const HOST_RE = /^[a-z0-9]([a-z0-9.-]{0,251}[a-z0-9])?$/
33
+ const CONNECT_TIMEOUT_MS = 15000
34
+ const IDLE_TIMEOUT_MS = 10 * 60 * 1000
35
+
36
+ // "host:port" or "host:port!private" -> { host, port, private }. Throws for anything else.
37
+ export function parseAllowEntry(value) {
38
+ const raw = String(value || '')
39
+ .trim()
40
+ .toLowerCase()
41
+ const priv = raw.endsWith('!private')
42
+ const body = priv ? raw.slice(0, -8) : raw
43
+ const match = /^(\[[0-9a-f:.]+\]|[^:[\]]+):(\d{1,5})$/.exec(body)
44
+ if (!match) throw new Error(`egress allow entry "${value}" is not host:port`)
45
+ const host = match[1].replace(/^\[|\]$/g, '')
46
+ const port = Number(match[2])
47
+ if (!(port > 0 && port < 65536)) throw new Error(`egress allow entry "${value}" has a bad port`)
48
+ if (!net.isIP(host) && !HOST_RE.test(host)) throw new Error(`egress allow entry "${value}" has a bad host`)
49
+ return { host, port, private: priv }
50
+ }
51
+
52
+ export function parseAllowList(value) {
53
+ return String(value || '')
54
+ .split(',')
55
+ .map((item) => item.trim())
56
+ .filter(Boolean)
57
+ .map(parseAllowEntry)
58
+ }
59
+
60
+ export function formatAllowEntry(entry) {
61
+ const host = net.isIP(entry.host) === 6 ? `[${entry.host}]` : entry.host
62
+ return `${host}:${entry.port}${entry.private ? '!private' : ''}`
63
+ }
64
+
65
+ // An IPv6 address as eight 16-bit numbers (with an embedded IPv4 tail), or null.
66
+ function ipv6Words(value) {
67
+ let text = value.replace(/%.*$/, '')
68
+ const tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(text)
69
+ if (tail) {
70
+ const bytes = tail[1].split('.').map(Number)
71
+ text = `${text.slice(0, -tail[1].length)}${((bytes[0] << 8) | bytes[1]).toString(16)}:${((bytes[2] << 8) | bytes[3]).toString(16)}`
72
+ }
73
+ const halves = text.split('::')
74
+ if (halves.length > 2) return null
75
+ const head = halves[0] ? halves[0].split(':') : []
76
+ const rest = halves.length === 2 && halves[1] ? halves[1].split(':') : []
77
+ const fill = halves.length === 2 ? 8 - head.length - rest.length : 0
78
+ const parts = [...head, ...Array(Math.max(0, fill)).fill('0'), ...rest]
79
+ if (parts.length !== 8 || !parts.every((part) => /^[0-9a-f]{1,4}$/.test(part))) return null
80
+ return parts.map((part) => parseInt(part, 16))
81
+ }
82
+
83
+ // The server name a TLS ClientHello asks for. Bytes may come in pieces:
84
+ // -> { need: true } (wait for more), { error }, or { sni, ech }.
85
+ export function readClientHello(buffer) {
86
+ // Handshake bytes from consecutive TLS handshake records.
87
+ let offset = 0
88
+ const chunks = []
89
+ let handshake = Buffer.alloc(0)
90
+ for (;;) {
91
+ if (buffer.length < offset + 5) return { need: true }
92
+ if (buffer[offset] !== 0x16) return { error: 'not TLS' }
93
+ if (buffer[offset + 1] !== 3) return { error: 'not TLS' }
94
+ const length = buffer.readUInt16BE(offset + 3)
95
+ if (length === 0 || length > 16384) return { error: 'bad TLS record' }
96
+ if (buffer.length < offset + 5 + length) return { need: true }
97
+ chunks.push(buffer.subarray(offset + 5, offset + 5 + length))
98
+ offset += 5 + length
99
+ handshake = Buffer.concat(chunks)
100
+ if (handshake.length >= 4) {
101
+ if (handshake[0] !== 1) return { error: 'not a ClientHello' }
102
+ const total = handshake.readUIntBE(1, 3)
103
+ if (total > 65536) return { error: 'ClientHello too big' }
104
+ if (handshake.length >= 4 + total) {
105
+ handshake = handshake.subarray(4, 4 + total)
106
+ break
107
+ }
108
+ }
109
+ }
110
+ try {
111
+ let at = 2 + 32 // version, random
112
+ at += 1 + handshake[at] // session id
113
+ at += 2 + handshake.readUInt16BE(at) // cipher suites
114
+ at += 1 + handshake[at] // compression methods
115
+ if (at === handshake.length) return { sni: null, ech: false }
116
+ const end = at + 2 + handshake.readUInt16BE(at)
117
+ if (end > handshake.length) return { error: 'bad ClientHello' }
118
+ at += 2
119
+ let sni = null
120
+ let ech = false
121
+ while (at + 4 <= end) {
122
+ const type = handshake.readUInt16BE(at)
123
+ const length = handshake.readUInt16BE(at + 2)
124
+ const data = handshake.subarray(at + 4, at + 4 + length)
125
+ if (data.length !== length) return { error: 'bad ClientHello' }
126
+ if (type === 0xfe0d) ech = true
127
+ if (type === 0) {
128
+ if (sni !== null) return { error: 'two server_name extensions' }
129
+ const listEnd = 2 + data.readUInt16BE(0)
130
+ let inner = 2
131
+ const names = []
132
+ while (inner + 3 <= listEnd) {
133
+ const nameType = data[inner]
134
+ const nameLength = data.readUInt16BE(inner + 1)
135
+ if (nameType === 0) names.push(data.subarray(inner + 3, inner + 3 + nameLength).toString('latin1'))
136
+ inner += 3 + nameLength
137
+ }
138
+ if (names.length !== 1) return { error: 'not exactly one server name' }
139
+ sni = names[0].toLowerCase()
140
+ }
141
+ at += 4 + length
142
+ }
143
+ return { sni, ech }
144
+ } catch {
145
+ return { error: 'bad ClientHello' }
146
+ }
147
+ }
148
+
149
+ const HELLO_MAX = 70000
150
+ const HELLO_TIMEOUT_MS = 10000
151
+
152
+ // Private, loopback, link-local, unique-local, CGNAT, multicast and unspecified addresses.
153
+ export function privateAddress(address) {
154
+ const value = String(address || '').toLowerCase()
155
+ if (net.isIP(value) === 4) {
156
+ const [a, b] = value.split('.').map(Number)
157
+ return (
158
+ a === 0 ||
159
+ a === 10 ||
160
+ a === 127 ||
161
+ (a === 100 && b >= 64 && b <= 127) ||
162
+ (a === 169 && b === 254) ||
163
+ (a === 172 && b >= 16 && b <= 31) ||
164
+ (a === 192 && b === 168) ||
165
+ a >= 224
166
+ )
167
+ }
168
+ if (net.isIP(value) === 6) {
169
+ const words = ipv6Words(value)
170
+ if (!words) return true
171
+ if (words.every((word) => word === 0)) return true // ::
172
+ if (words.slice(0, 7).every((word) => word === 0) && words[7] === 1) return true // ::1
173
+ const v4 = (high, low) => `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`
174
+ // IPv4-mapped (::ffff:a.b.c.d, also written ::ffff:7f00:1) and IPv4-compatible (::a.b.c.d).
175
+ if (words.slice(0, 5).every((word) => word === 0) && (words[5] === 0xffff || words[5] === 0))
176
+ return privateAddress(v4(words[6], words[7]))
177
+ // NAT64 (64:ff9b::/96 and the local-use 64:ff9b:1::/48): the IPv4 address is inside.
178
+ if (words[0] === 0x64 && words[1] === 0xff9b) return words[2] === 1 || privateAddress(v4(words[6], words[7]))
179
+ // 6to4 (2002::/16) carries an IPv4 address too; Teredo (2001:0::/32) is a tunnel: refuse.
180
+ if (words[0] === 0x2002) return privateAddress(v4(words[1], words[2]))
181
+ if (words[0] === 0x2001 && words[1] === 0) return true
182
+ const first = words[0]
183
+ return (
184
+ (first & 0xfe00) === 0xfc00 ||
185
+ (first & 0xffc0) === 0xfe80 ||
186
+ (first & 0xffc0) === 0xfec0 ||
187
+ (first & 0xff00) === 0xff00 ||
188
+ first === 0x0100
189
+ )
190
+ }
191
+ return true
192
+ }
193
+
194
+ // createEgressProxy({ allow, log, lookup }) -> http.Server (not listening yet).
195
+ // The timeouts are options for the tests only.
196
+ export function createEgressProxy({
197
+ allow,
198
+ log = (entry) => process.stdout.write(`${JSON.stringify(entry)}\n`),
199
+ lookup = dns.lookup,
200
+ connectTimeoutMs = CONNECT_TIMEOUT_MS,
201
+ idleTimeoutMs = IDLE_TIMEOUT_MS,
202
+ }) {
203
+ const entries = allow.map((entry) => ({ ...entry, host: entry.host.toLowerCase() }))
204
+ const find = (host, port) => entries.find((entry) => entry.host === String(host).toLowerCase() && entry.port === Number(port))
205
+
206
+ // The address to connect to, or a reason to refuse.
207
+ async function resolve(host, port) {
208
+ const entry = find(host, port)
209
+ if (!entry) return { reason: 'not on the allow list' }
210
+ let address = entry.host
211
+ if (!net.isIP(address)) {
212
+ try {
213
+ address = (await lookup(entry.host, { verbatim: true })).address
214
+ } catch (error) {
215
+ return { reason: `cannot resolve (${error.code || error.message})` }
216
+ }
217
+ }
218
+ if (!entry.private && privateAddress(address)) return { reason: `resolves to a private address (${address})` }
219
+ return { address, entry }
220
+ }
221
+
222
+ const deny = (host, port, reason) => log({ deny: true, host: String(host).slice(0, 255), port: Number(port) || null, reason })
223
+
224
+ const server = http.createServer(async (req, res) => {
225
+ // Plain http, absolute-form only.
226
+ let url
227
+ try {
228
+ url = new URL(req.url)
229
+ } catch {
230
+ url = null
231
+ }
232
+ if (!url || url.protocol !== 'http:') {
233
+ deny(req.headers.host || '', 0, 'not a proxy request')
234
+ res.writeHead(403, { 'Content-Type': 'text/plain' }).end('Shapewall egress proxy: only allowed hosts\n')
235
+ return
236
+ }
237
+ const port = Number(url.port || 80)
238
+ const target = await resolve(url.hostname, port)
239
+ if (!target.address) {
240
+ deny(url.hostname, port, target.reason)
241
+ res.writeHead(403, { 'Content-Type': 'text/plain' }).end(`Shapewall egress proxy: ${url.hostname}:${port} is ${target.reason}\n`)
242
+ return
243
+ }
244
+ log({ allow: true, host: url.hostname, port, method: req.method })
245
+ const headers = { ...req.headers, host: url.host }
246
+ for (const name of ['proxy-connection', 'proxy-authorization', 'connection', 'keep-alive']) delete headers[name]
247
+ const upstream = http.request(
248
+ { host: target.address, port, method: req.method, path: `${url.pathname}${url.search}`, headers, timeout: idleTimeoutMs },
249
+ (answer) => {
250
+ answer.on('error', () => res.destroy())
251
+ res.writeHead(answer.statusCode || 502, answer.headers)
252
+ answer.pipe(res)
253
+ },
254
+ )
255
+ // The timeout option only emits 'timeout'; ending the request is ours to do.
256
+ upstream.on('timeout', () => upstream.destroy(Object.assign(new Error('upstream timed out'), { code: 'ETIMEDOUT' })))
257
+ upstream.on('error', () => {
258
+ // Mid-body a 502 cannot be sent any more: cut the response instead.
259
+ if (res.headersSent) return res.destroy()
260
+ res.writeHead(502, { 'Content-Type': 'text/plain' }).end()
261
+ })
262
+ // The client went away before the answer was sent: stop the upstream request too.
263
+ res.on('close', () => {
264
+ if (!res.writableFinished) upstream.destroy()
265
+ })
266
+ req.pipe(upstream)
267
+ })
268
+
269
+ server.on('connect', async (req, client, head) => {
270
+ client.on('error', () => {})
271
+ const match = /^(\[[0-9a-fA-F:.]+\]|[^:[\]]+):(\d{1,5})$/.exec(String(req.url || ''))
272
+ const host = match ? match[1].replace(/^\[|\]$/g, '') : String(req.url || '')
273
+ const port = match ? Number(match[2]) : 0
274
+ const target = match ? await resolve(host, port) : { reason: 'not host:port' }
275
+ if (!target.address) {
276
+ deny(host, port, target.reason)
277
+ client.end('HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain\r\n\r\nShapewall egress proxy: only allowed hosts\n')
278
+ return
279
+ }
280
+ const upstream = net.connect({ host: target.address, port, timeout: connectTimeoutMs })
281
+ let established = false
282
+ upstream.once('connect', () => {
283
+ established = true
284
+ upstream.setTimeout(idleTimeoutMs)
285
+ client.write('HTTP/1.1 200 Connection Established\r\n\r\n')
286
+ // Only TLS, and only to the name that was allowed: many hosts share an
287
+ // address (a CDN), so the address alone would let any of them through.
288
+ let buffered = head?.length ? Buffer.from(head) : Buffer.alloc(0)
289
+ const refuse = (reason) => {
290
+ deny(host, port, reason)
291
+ clearTimeout(timer)
292
+ client.destroy()
293
+ upstream.destroy()
294
+ }
295
+ const timer = setTimeout(() => refuse('no TLS ClientHello'), HELLO_TIMEOUT_MS)
296
+ const check = () => {
297
+ const hello = readClientHello(buffered)
298
+ if (hello.need) {
299
+ if (buffered.length > HELLO_MAX) refuse('ClientHello too big')
300
+ return
301
+ }
302
+ client.off('data', onData)
303
+ if (hello.error) return refuse(`${hello.error} (CONNECT carries TLS only)`)
304
+ if (hello.ech) return refuse('encrypted ClientHello (ECH)')
305
+ const expected = target.entry.host
306
+ if (hello.sni === null ? !net.isIP(expected) : hello.sni !== expected) {
307
+ return refuse(`TLS server name ${hello.sni === null ? 'missing' : `"${hello.sni.slice(0, 100)}"`} is not ${expected}`)
308
+ }
309
+ clearTimeout(timer)
310
+ log({ allow: true, host, port, method: 'CONNECT' })
311
+ upstream.write(buffered)
312
+ upstream.pipe(client)
313
+ client.pipe(upstream)
314
+ }
315
+ const onData = (chunk) => {
316
+ buffered = Buffer.concat([buffered, chunk])
317
+ check()
318
+ }
319
+ client.on('data', onData)
320
+ if (buffered.length) check()
321
+ })
322
+ // A timeout only emits 'timeout': end it as an error so the client hears of it.
323
+ upstream.on('timeout', () => upstream.destroy(Object.assign(new Error('upstream timed out'), { code: 'ETIMEDOUT' })))
324
+ upstream.on('error', (error) => {
325
+ if (client.destroyed) return
326
+ // Once the tunnel is up the client speaks TLS: no HTTP answer fits, just close.
327
+ if (established) client.destroy()
328
+ else client.end(`HTTP/1.1 502 Bad Gateway\r\n\r\n${error.code || 'upstream error'}\n`)
329
+ })
330
+ // However the upstream side closes, the client side is closed too.
331
+ upstream.on('close', () => {
332
+ if (!client.destroyed && !client.writableEnded) client.end()
333
+ })
334
+ client.on('close', () => upstream.destroy())
335
+ })
336
+ server.on('clientError', (error, socket) => socket.destroy())
337
+ return server
338
+ }
339
+
340
+ // Started as a program (in the proxy container).
341
+ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
342
+ const allow = parseAllowList(process.env.SHAPEWALL_EGRESS_ALLOW)
343
+ const port = Number(process.env.SHAPEWALL_EGRESS_PORT || PROXY_PORT)
344
+ const server = createEgressProxy({ allow })
345
+ server.listen(port, '0.0.0.0', () => {
346
+ process.stdout.write(`${JSON.stringify({ ready: true, port, allow: allow.map(formatAllowEntry) })}\n`)
347
+ })
348
+ const stop = () => server.close(() => process.exit(0))
349
+ process.on('SIGTERM', stop)
350
+ process.on('SIGINT', stop)
351
+ }
@@ -0,0 +1,90 @@
1
+ // The trigger gate: which comments the starter agent may take.
2
+ //
3
+ // Anyone who can comment can write text the agent will act on, so a comment
4
+ // is dispatched only when a trusted member stands behind it:
5
+ //
6
+ // - a share link guest's comment (authorGuest) is never dispatched, whoever
7
+ // tags it later;
8
+ // - a comment written by an agent (a hosted token, or the local "agent" /
9
+ // "shapewall" names) is not either, so agents do not feed each other;
10
+ // - a trusted member's own comment is dispatched;
11
+ // - anyone else's comment waits until a trusted member replies with @agent.
12
+ //
13
+ // Who is a member: on a hosted board, the account handle the server attests
14
+ // (authorHandle, reply.handle); display names are never enough there. On a
15
+ // local board, the author name as typed: a local board has no accounts, so
16
+ // this is only as strong as who can reach the board (docs/starter-agent.md).
17
+
18
+ import { extractMentions } from '../../mentions.js'
19
+ import { trustName } from './settings.js'
20
+
21
+ export const AGENT_HANDLE = 'agent'
22
+ const AGENT_NAMES = new Set(['agent', 'shapewall', 'shapewall agent', 'starter agent'])
23
+
24
+ // The identity behind a comment or reply: { name, attested }.
25
+ function identity(item, { hosted }) {
26
+ if (hosted) return { name: item.authorHandle || item.handle ? trustName(item.authorHandle || item.handle) : null, attested: true }
27
+ return { name: trustName(item.author), attested: false }
28
+ }
29
+
30
+ const byAgent = (item, { hosted }) => Boolean(item.authorAgent || item.agent) || (!hosted && AGENT_NAMES.has(trustName(item.author)))
31
+
32
+ // gateComment(comment, { trusted: Set, hosted }) ->
33
+ // { dispatch: true, by, via: 'author' | 'tag', attested }
34
+ // { dispatch: false, reason, final } final: never, whatever happens later
35
+ export function gateComment(comment, { trusted, hosted = false, handle = AGENT_HANDLE }) {
36
+ if (!comment || comment.status !== 'open') return { dispatch: false, reason: 'the comment is not open', final: false }
37
+ if (comment.authorGuest)
38
+ return { dispatch: false, reason: 'a share link guest wrote it (guest comments are never dispatched)', final: true }
39
+ if (byAgent(comment, { hosted })) return { dispatch: false, reason: 'an agent wrote it', final: true }
40
+ if (hosted)
41
+ return comment.dispatchable === true
42
+ ? { dispatch: true, by: 'server policy', via: 'author', attested: true }
43
+ : { dispatch: false, reason: 'the server has not dispatched this comment', final: false }
44
+ if (!trusted?.size)
45
+ return { dispatch: false, reason: 'no member may dispatch work on this board (starterAgent.trusted is empty)', final: false }
46
+ const author = identity(comment, { hosted })
47
+ if (author.name && trusted.has(author.name)) return { dispatch: true, by: author.name, via: 'author', attested: author.attested }
48
+ // A tag vouches for the text as it was then: after an edit of the comment,
49
+ // only a newer tag counts (a tag without a time does not count then).
50
+ const edited = typeof comment.editedAt === 'string' ? Date.parse(comment.editedAt) : null
51
+ let stale = false
52
+ for (const reply of comment.replies || []) {
53
+ if (reply.guest || byAgent(reply, { hosted })) continue
54
+ const who = identity(reply, { hosted })
55
+ if (!who.name || !trusted.has(who.name)) continue
56
+ if (!extractMentions(reply.body).includes(handle)) continue
57
+ const at = typeof reply.createdAt === 'string' ? Date.parse(reply.createdAt) : NaN
58
+ if (edited !== null && !(at > edited)) {
59
+ stale = true
60
+ continue
61
+ }
62
+ return { dispatch: true, by: who.name, via: 'tag', attested: who.attested }
63
+ }
64
+ return {
65
+ dispatch: false,
66
+ reason: stale
67
+ ? `the comment was edited after the @${handle} tag; a trusted member must tag it again`
68
+ : `waiting for a trusted member to reply with @${handle}`,
69
+ final: false,
70
+ }
71
+ }
72
+
73
+ // What of a comment the model may see: the comment and the replies of
74
+ // people who are not guests. Guest replies are dropped, not quoted.
75
+ export function commentForTask(item) {
76
+ return {
77
+ id: item.id,
78
+ body: item.body,
79
+ author: item.author,
80
+ status: item.status,
81
+ page: item.page || null,
82
+ variant: item.variant || null,
83
+ viewport: item.viewport || null,
84
+ element: item.element || null,
85
+ position: item.position || null,
86
+ replies: (item.replies || [])
87
+ .filter((reply) => !reply.guest)
88
+ .map((reply) => ({ author: reply.author, body: reply.body, createdAt: reply.createdAt })),
89
+ }
90
+ }
@@ -0,0 +1,114 @@
1
+ // The starter agent's turn loop, inside the container: ask the model, run
2
+ // the tools it calls, repeat until it answers without a tool call or a
3
+ // budget runs out.
4
+ //
5
+ // Budgets per comment, checked before every model call:
6
+ // - turns: model calls;
7
+ // - tokens: as the endpoint reports them (stream_options.include_usage),
8
+ // or estimated at 4 characters a token when it does not; each answer's
9
+ // max_tokens is capped at what is left;
10
+ // - wall time: a deadline, also enforced from the host (it stops the
11
+ // container), so a model or a command that hangs cannot outlast it.
12
+
13
+ export const TOOL_CALLS_PER_TURN_MAX = 8
14
+ const DEFAULT_ANSWER_TOKENS = 4096
15
+ const TEXT_MAX = 20000
16
+
17
+ const ARG_SHOWN_MAX = 160
18
+
19
+ // A tool call's arguments for the run log: names and short values (long
20
+ // text such as a file's content is cut, with its length).
21
+ export function argsSummary(args) {
22
+ if (!args || typeof args !== 'object' || Array.isArray(args)) return null
23
+ const out = {}
24
+ for (const [key, value] of Object.entries(args).slice(0, 12)) {
25
+ if (typeof value === 'string')
26
+ out[key] = value.length > ARG_SHOWN_MAX ? `${value.slice(0, ARG_SHOWN_MAX)}... (${value.length} characters)` : value
27
+ else if (['number', 'boolean'].includes(typeof value) || value === null) out[key] = value
28
+ else out[key] = '[...]'
29
+ }
30
+ return out
31
+ }
32
+
33
+ const estimate = (value) => Math.ceil((typeof value === 'string' ? value.length : JSON.stringify(value).length) / 4)
34
+
35
+ // runLoop({ backend, settings, system, task, tools, budget, deadline, emit, signal })
36
+ // -> { stop: 'answered' | 'turns' | 'tokens' | 'time' | 'stopped' | 'error', text, usage, error? }
37
+ export async function runLoop({
38
+ backend,
39
+ settings,
40
+ system,
41
+ task,
42
+ tools,
43
+ budget,
44
+ deadline,
45
+ emit = () => {},
46
+ signal = null,
47
+ now = () => Date.now(),
48
+ }) {
49
+ const messages = [{ role: 'user', content: [{ type: 'text', text: task }] }]
50
+ const usage = { turns: 0, tokens: 0, estimated: false }
51
+ let text = ''
52
+ const over = () => {
53
+ if (signal?.aborted) return 'stopped'
54
+ if (now() >= deadline) return 'time'
55
+ if (usage.turns >= budget.turns) return 'turns'
56
+ if (usage.tokens >= budget.tokens) return 'tokens'
57
+ return null
58
+ }
59
+ for (;;) {
60
+ const stop = over()
61
+ if (stop) return { stop, text: text.trim(), usage }
62
+ usage.turns += 1
63
+ emit({ type: 'turn', turn: usage.turns })
64
+ // What is left of the token budget caps this answer.
65
+ settings.maxTokens = Math.max(1, Math.min(settings.answerTokens || DEFAULT_ANSWER_TOKENS, budget.tokens - usage.tokens))
66
+ let turnText = ''
67
+ let reported = null
68
+ const calls = []
69
+ try {
70
+ for await (const event of backend.stream({ system, messages, tools: tools.specs, signal })) {
71
+ if (signal?.aborted) break
72
+ if (event.type === 'text') {
73
+ turnText += event.text
74
+ emit({ type: 'text', text: event.text })
75
+ } else if (event.type === 'usage') {
76
+ reported = (reported || 0) + event.total
77
+ } else if (event.type === 'tool_call') {
78
+ calls.push(event)
79
+ }
80
+ }
81
+ } catch (error) {
82
+ if (signal?.aborted) return { stop: 'stopped', text: text.trim(), usage }
83
+ return {
84
+ stop: 'error',
85
+ text: text.trim(),
86
+ usage,
87
+ error: { code: error.code || 'agent_error', message: String(error.message).slice(0, 300) },
88
+ }
89
+ }
90
+ if (reported === null) {
91
+ usage.estimated = true
92
+ usage.tokens += estimate(system) + estimate(messages) + estimate(turnText) + estimate(calls)
93
+ } else usage.tokens += reported
94
+ emit({ type: 'usage', tokens: usage.tokens, estimated: usage.estimated })
95
+ if (signal?.aborted) return { stop: 'stopped', text: text.trim(), usage }
96
+ if (turnText) text = `${text}${text ? '\n\n' : ''}${turnText}`.slice(-TEXT_MAX)
97
+ if (!calls.length) return { stop: 'answered', text: text.trim(), usage }
98
+ const taken = calls.slice(0, TOOL_CALLS_PER_TURN_MAX).map((call, index) => ({ ...call, id: call.id || `call_${usage.turns}_${index}` }))
99
+ messages.push({ role: 'assistant', content: [{ type: 'text', text: turnText }], toolCalls: taken })
100
+ for (const call of taken) {
101
+ const id = call.id
102
+ emit({ type: 'tool', id, name: call.name, state: 'running', args: argsSummary(call.args) })
103
+ const result = await tools.run(call)
104
+ emit({ type: 'tool', id, name: call.name, label: result.label, state: result.ok ? 'done' : 'error', detail: result.detail })
105
+ messages.push({ role: 'tool', toolCallId: id, content: [{ type: 'text', text: result.text }] })
106
+ }
107
+ if (calls.length > taken.length) {
108
+ messages.push({
109
+ role: 'user',
110
+ content: [{ type: 'text', text: `[Shapewall] Only the first ${TOOL_CALLS_PER_TURN_MAX} tool calls of a turn run.` }],
111
+ })
112
+ }
113
+ }
114
+ }