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.
- package/CHANGELOG.md +139 -0
- package/Dockerfile.agent +45 -0
- package/LICENSE +202 -0
- package/NOTICE +12 -0
- package/README.md +651 -2
- package/THIRD_PARTY.md +165 -0
- package/bin/shapewall.js +29 -0
- package/dist/agent/package-lock.json +8384 -0
- package/dist/client/assets/BoardChat-D5SFd8HE.js +28 -0
- package/dist/client/assets/BuzzDialog-HWXBy52W.js +1 -0
- package/dist/client/assets/ChecksPanel-DTdImWoD.js +1 -0
- package/dist/client/assets/History-CEv6b-av.js +1 -0
- package/dist/client/assets/LocalSettings-C4vriEVQ.js +1 -0
- package/dist/client/assets/Management-DCfhcEUY.js +1 -0
- package/dist/client/assets/QuickConnect-DQGgUsl1.js +1 -0
- package/dist/client/assets/ShareDialog-C_plIto0.js +2 -0
- package/dist/client/assets/app-update-dialog-2hPz_N9G.js +1 -0
- package/dist/client/assets/circle-x-BZMPi8Zf.js +1 -0
- package/dist/client/assets/index-ByQRKVit.css +2 -0
- package/dist/client/assets/index-DweQ8Qtu.js +29 -0
- package/dist/client/assets/refresh-cw-CRow0Nbq.js +1 -0
- package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
- package/dist/client/assets/square-A8EnIYLR.js +1 -0
- package/dist/client/assets/tts-dist-DYlBQmwG.js +18 -0
- package/dist/client/assets/tts-en-g2p-BPUtBFGG.js +1 -0
- package/dist/client/assets/tts-ort-wasm-simd-threaded-qh98TCA_.wasm +0 -0
- package/dist/client/assets/tts-ort.wasm.bundle.min-rEkcs_ow.js +12 -0
- package/dist/client/assets/tts-rolldown-runtime-D8NudN84.js +1 -0
- package/dist/client/assets/tts-spacy-en-tokenizer-6SNMl--A.json +1 -0
- package/dist/client/assets/tts-tts.worker-Bzm6aWbv.js +1 -0
- package/dist/client/assets/tts-us_gold-DcjeNMH1.json +92589 -0
- package/dist/client/assets/tts-us_silver-C964mEB5.json +93363 -0
- package/dist/client/assets/ui-CLbws0rx.js +41 -0
- package/dist/client/build-info.json +1 -0
- package/dist/client/favicon.svg +7 -0
- package/dist/client/icons/apple-touch-icon.png +0 -0
- package/dist/client/icons/icon-192.png +0 -0
- package/dist/client/icons/icon-512.png +0 -0
- package/dist/client/icons/maskable-512.png +0 -0
- package/dist/client/index.html +25 -0
- package/dist/client/manifest.webmanifest +15 -0
- package/dist/client/sw.js +53 -0
- package/dist/client/theme-boot.js +27 -0
- package/dist/console/assets/LocalAccountsApp-BQCcmj3x.js +1 -0
- package/dist/console/assets/LocalConsole-Bb2FUDs7.js +1 -0
- package/dist/console/assets/app-update-dialog-DIeYepLZ.js +1 -0
- package/dist/console/assets/console-C7uJLLOn.js +51 -0
- package/dist/console/assets/console-R8IBY3Am.css +2 -0
- package/dist/console/build-info.json +1 -0
- package/dist/console/console.html +21 -0
- package/dist/console/favicon.svg +7 -0
- package/dist/console/icons/apple-touch-icon.png +0 -0
- package/dist/console/icons/icon-192.png +0 -0
- package/dist/console/icons/icon-512.png +0 -0
- package/dist/console/icons/maskable-512.png +0 -0
- package/dist/console/manifest.webmanifest +15 -0
- package/dist/console/theme-boot.js +27 -0
- package/docs/agent-hardening.md +342 -0
- package/docs/agent-recipes.md +187 -0
- package/docs/agent-workflow.md +320 -0
- package/docs/agents.md +894 -0
- package/docs/architecture.md +242 -0
- package/docs/buzz.md +140 -0
- package/docs/capture-warnings.md +57 -0
- package/docs/config.md +489 -0
- package/docs/deployment.md +289 -0
- package/docs/design-system.md +162 -0
- package/docs/github.md +107 -0
- package/docs/hosted.md +764 -0
- package/docs/images/board-overview.png +0 -0
- package/docs/images/journeys.png +0 -0
- package/docs/images/live-comment.png +0 -0
- package/docs/images/phone-comment.png +0 -0
- package/docs/images/phone-overview.png +0 -0
- package/docs/images/variant.png +0 -0
- package/docs/interaction-audits.md +40 -0
- package/docs/journeys.md +137 -0
- package/docs/local-accounts.md +80 -0
- package/docs/notifications.md +237 -0
- package/docs/page-checks.md +69 -0
- package/docs/performance.md +174 -0
- package/docs/starter-agent.md +325 -0
- package/docs/updates.md +87 -0
- package/examples/audits/interaction.audit.json +17 -0
- package/package.json +132 -4
- package/src/accounts/avatar.js +121 -0
- package/src/accounts/local.js +464 -0
- package/src/agent/acp/command.js +204 -0
- package/src/agent/acp/detect.js +75 -0
- package/src/agent/acp/sandbox.js +160 -0
- package/src/agent/agent-health.js +75 -0
- package/src/agent/backends/acp.js +1297 -0
- package/src/agent/backends/index.js +61 -0
- package/src/agent/backends/openai.js +308 -0
- package/src/agent/composer.js +221 -0
- package/src/agent/config.js +338 -0
- package/src/agent/context.js +191 -0
- package/src/agent/control.js +122 -0
- package/src/agent/errors.js +17 -0
- package/src/agent/feedback-loop.js +137 -0
- package/src/agent/manage.js +94 -0
- package/src/agent/next-steps.js +51 -0
- package/src/agent/owner-mcp.js +38 -0
- package/src/agent/plain-text.js +52 -0
- package/src/agent/ratings-core.js +213 -0
- package/src/agent/ratings.js +100 -0
- package/src/agent/reply-text.js +67 -0
- package/src/agent/routes.js +1065 -0
- package/src/agent/run.js +326 -0
- package/src/agent/settings-routes.js +704 -0
- package/src/agent/showable.js +23 -0
- package/src/agent/starter/approvals.js +181 -0
- package/src/agent/starter/build-image.js +90 -0
- package/src/agent/starter/cli.js +163 -0
- package/src/agent/starter/disk.js +53 -0
- package/src/agent/starter/doctor.js +180 -0
- package/src/agent/starter/egress-proxy.js +351 -0
- package/src/agent/starter/gate.js +90 -0
- package/src/agent/starter/loop.js +114 -0
- package/src/agent/starter/model-relay.js +289 -0
- package/src/agent/starter/pause.js +14 -0
- package/src/agent/starter/probe.js +272 -0
- package/src/agent/starter/prompt.js +41 -0
- package/src/agent/starter/push-guard.js +146 -0
- package/src/agent/starter/rpc.js +164 -0
- package/src/agent/starter/runtime.js +287 -0
- package/src/agent/starter/sandbox-main.js +121 -0
- package/src/agent/starter/settings.js +290 -0
- package/src/agent/starter/source.js +69 -0
- package/src/agent/starter/supervisor.js +755 -0
- package/src/agent/starter/sweep.js +46 -0
- package/src/agent/starter/tools.js +524 -0
- package/src/agent/starter/watch.js +84 -0
- package/src/agent/starter/worktree.js +409 -0
- package/src/agent/text-diff.js +210 -0
- package/src/agent/thread-history.js +223 -0
- package/src/agent/threads.js +399 -0
- package/src/agent/tools.js +200 -0
- package/src/agent/turn-changes.js +424 -0
- package/src/agent/undo-state.js +26 -0
- package/src/agent/user-settings.js +308 -0
- package/src/auth/record.js +375 -0
- package/src/broken-links.js +164 -0
- package/src/buzz/client.js +75 -0
- package/src/buzz/config.js +151 -0
- package/src/buzz/environment.js +13 -0
- package/src/buzz/gateway.js +192 -0
- package/src/buzz/routes.js +61 -0
- package/src/buzz/signer-child.js +205 -0
- package/src/buzz/store.js +89 -0
- package/src/buzz/transport.js +60 -0
- package/src/buzz/verify.js +140 -0
- package/src/capture/actions.js +159 -0
- package/src/capture/capture.js +776 -0
- package/src/capture/dom-names.js +189 -0
- package/src/capture/element-map.js +509 -0
- package/src/capture/live.js +827 -0
- package/src/capture/media-scheme.js +317 -0
- package/src/capture/network-summary.js +86 -0
- package/src/capture/pacing.js +34 -0
- package/src/capture/requests.js +167 -0
- package/src/capture/sanitize.js +752 -0
- package/src/checks/accessibility.js +134 -0
- package/src/checks/budgets.js +58 -0
- package/src/checks/cli.js +55 -0
- package/src/checks/comparison.js +113 -0
- package/src/checks/environments.js +32 -0
- package/src/checks/flow-config.js +82 -0
- package/src/checks/flow-origin.js +53 -0
- package/src/checks/flows.js +398 -0
- package/src/checks/lighthouse-auth.js +145 -0
- package/src/checks/lighthouse-findings.js +130 -0
- package/src/checks/lighthouse.js +395 -0
- package/src/checks/robots.js +85 -0
- package/src/checks/routes.js +52 -0
- package/src/checks/run-control.js +259 -0
- package/src/checks/runner.js +724 -0
- package/src/checks/schema.js +133 -0
- package/src/checks/seo-analysis.js +443 -0
- package/src/checks/seo-probe.js +190 -0
- package/src/checks/seo-snapshot.js +99 -0
- package/src/checks/store.js +214 -0
- package/src/checks/transport.js +47 -0
- package/src/cli/args.js +319 -0
- package/src/cli/capture.js +79 -0
- package/src/cli/commands.js +92 -0
- package/src/cli/comments.js +84 -0
- package/src/cli/help.js +243 -0
- package/src/cli/init.js +214 -0
- package/src/cli/misc.js +64 -0
- package/src/cli/notify.js +87 -0
- package/src/cli/open.js +22 -0
- package/src/cli/serve.js +274 -0
- package/src/cli/variant.js +82 -0
- package/src/cli/watch.js +70 -0
- package/src/cli.js +130 -0
- package/src/comment-fields.js +76 -0
- package/src/comments-cli.js +208 -0
- package/src/config-reload.js +100 -0
- package/src/config.js +1061 -0
- package/src/devices-cli.js +21 -0
- package/src/diff.js +95 -0
- package/src/discover.js +284 -0
- package/src/doctor.js +295 -0
- package/src/event-log.js +268 -0
- package/src/events-cli.js +102 -0
- package/src/events.js +113 -0
- package/src/export.js +119 -0
- package/src/feedback.js +246 -0
- package/src/github.js +551 -0
- package/src/hosted/LICENSE.md +105 -0
- package/src/hosted/access-cli.js +78 -0
- package/src/hosted/admin.js +682 -0
- package/src/hosted/agent-approvals.js +163 -0
- package/src/hosted/agent-policy.js +189 -0
- package/src/hosted/app.js +510 -0
- package/src/hosted/auth-routes.js +540 -0
- package/src/hosted/auth.js +536 -0
- package/src/hosted/backup.js +483 -0
- package/src/hosted/board-context.js +35 -0
- package/src/hosted/board-routes.js +486 -0
- package/src/hosted/board-view.js +94 -0
- package/src/hosted/clean-worker.js +24 -0
- package/src/hosted/cleaner.js +89 -0
- package/src/hosted/comments.js +355 -0
- package/src/hosted/console-routes.js +401 -0
- package/src/hosted/cookies.js +18 -0
- package/src/hosted/crypto.js +80 -0
- package/src/hosted/db.js +496 -0
- package/src/hosted/device-routes.js +175 -0
- package/src/hosted/device.js +233 -0
- package/src/hosted/events.js +63 -0
- package/src/hosted/guards.js +172 -0
- package/src/hosted/guest-view.js +65 -0
- package/src/hosted/http.js +39 -0
- package/src/hosted/import.js +300 -0
- package/src/hosted/mail.js +73 -0
- package/src/hosted/mcp-http.js +71 -0
- package/src/hosted/membership.js +114 -0
- package/src/hosted/operator.js +478 -0
- package/src/hosted/ops-cli.js +345 -0
- package/src/hosted/pages.js +146 -0
- package/src/hosted/permissions.js +113 -0
- package/src/hosted/presence.js +372 -0
- package/src/hosted/projects.js +124 -0
- package/src/hosted/public.js +109 -0
- package/src/hosted/push.js +622 -0
- package/src/hosted/quotas.js +115 -0
- package/src/hosted/ratelimit.js +96 -0
- package/src/hosted/rebind.js +316 -0
- package/src/hosted/retention.js +128 -0
- package/src/hosted/server.js +260 -0
- package/src/hosted/setup-link.js +64 -0
- package/src/hosted/setup.js +323 -0
- package/src/hosted/shares.js +444 -0
- package/src/hosted/tailscale.js +204 -0
- package/src/hosted/tenancy.js +301 -0
- package/src/hosted/token-api.js +455 -0
- package/src/hosted/token-events.js +60 -0
- package/src/hosted/tokens.js +57 -0
- package/src/hosted/turnstile.js +49 -0
- package/src/hosted/usercontent.js +154 -0
- package/src/hosted/zip.js +155 -0
- package/src/invocation.js +58 -0
- package/src/journey-paths.js +282 -0
- package/src/journeys.js +189 -0
- package/src/links.js +106 -0
- package/src/local-projects.js +182 -0
- package/src/lock.js +193 -0
- package/src/mcp.js +417 -0
- package/src/mentions.js +151 -0
- package/src/net.js +15 -0
- package/src/notify/config.js +275 -0
- package/src/notify/index.js +301 -0
- package/src/notify/lease.js +73 -0
- package/src/notify/messages.js +212 -0
- package/src/notify/run.js +174 -0
- package/src/pixeldiff.js +49 -0
- package/src/png.js +143 -0
- package/src/reactions.js +111 -0
- package/src/remote/cli.js +133 -0
- package/src/remote/credentials.js +62 -0
- package/src/remote/ids.js +12 -0
- package/src/remote/login.js +155 -0
- package/src/remote/remote-mcp.js +237 -0
- package/src/remote/remote-watch.js +291 -0
- package/src/remote/remote.js +313 -0
- package/src/remote/share-state.js +78 -0
- package/src/remote/share.js +369 -0
- package/src/remote/terminal.js +13 -0
- package/src/serve-state.js +64 -0
- package/src/server/app.js +824 -0
- package/src/server/devices.js +186 -0
- package/src/server/local-console.js +28 -0
- package/src/server/local-user.js +59 -0
- package/src/server/pairing-routes.js +159 -0
- package/src/server/share-routes.js +89 -0
- package/src/server/tailscale.js +97 -0
- package/src/sitemap.js +431 -0
- package/src/store.js +983 -0
- package/src/tokens.js +11 -0
- package/src/update/routes.js +245 -0
- package/src/watch.js +403 -0
- package/src/which.js +58 -0
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Local Lighthouse navigation audits
|
|
2
|
+
|
|
3
|
+
Shapewall's Lighthouse runner audits the original application URL. It does not
|
|
4
|
+
measure the screenshot viewer, capture duration or PNG size. Audits run only
|
|
5
|
+
when explicitly invoked locally or in CI. The hosted server never launches an
|
|
6
|
+
audit or fetches an arbitrary submitted URL.
|
|
7
|
+
|
|
8
|
+
The runner exports `auditCommand(config, positional, flags, out, err)` for the
|
|
9
|
+
CLI and `runLighthouseAudits({ config, ...options })` for trusted local tooling.
|
|
10
|
+
The CLI integration mounts it under `shapewall audit`. The runner itself
|
|
11
|
+
does not change captures or application configuration.
|
|
12
|
+
|
|
13
|
+
## Runtime and limits
|
|
14
|
+
|
|
15
|
+
Use Node 22.19 or later and an installed Chrome. The exact runtime dependencies
|
|
16
|
+
are Lighthouse 13.6.0, chrome-launcher 1.2.2 and puppeteer-core 25.16.0. No browser
|
|
17
|
+
is downloaded. `config.browser.executablePath` selects Chrome explicitly;
|
|
18
|
+
otherwise the installed Chrome is discovered. An unsupported browser channel
|
|
19
|
+
fails honestly. An optional `--browser-version` requires an exact installed
|
|
20
|
+
browser version for reproducible CI comparisons.
|
|
21
|
+
|
|
22
|
+
Run audits through the machine's capped browser wrapper, for example
|
|
23
|
+
`browser-slot node ...` in local tooling. Each navigation gets its own private
|
|
24
|
+
browser profile beneath the configured output directory. The runner closes the
|
|
25
|
+
browser and removes this profile on success or failure.
|
|
26
|
+
|
|
27
|
+
Selection flags are `--board`, `--env`, `--only page-a,page-b` and
|
|
28
|
+
`--viewports desktop,phone`. The defaults allow at most five pages and ten
|
|
29
|
+
navigations. Explicit `--max-pages` and `--max-runs` can raise those caps to 20
|
|
30
|
+
pages and 40 navigations. `--samples` defaults to one and cannot exceed ten.
|
|
31
|
+
All navigations run serially, with a two-minute hard deadline per navigation.
|
|
32
|
+
An oversized selection fails before starting Chrome.
|
|
33
|
+
|
|
34
|
+
Each repeat is a separate raw report with `sampleCount: 1`, a distinct report
|
|
35
|
+
identifier and the same run identifier. Repeats do not silently become a median
|
|
36
|
+
or a more confident score. `--json` prints only the bounded report result.
|
|
37
|
+
A partial, unsupported or failed audit returns a nonzero command status.
|
|
38
|
+
|
|
39
|
+
## Measurement profile
|
|
40
|
+
|
|
41
|
+
The report records the actual Chrome version, a hash of the emulated user
|
|
42
|
+
agent, the configured viewport dimensions, device scale, mobile emulation and
|
|
43
|
+
the pinned Lighthouse version. Tablet and phone use Lighthouse's mobile user
|
|
44
|
+
agent; desktop uses its desktop agent. The emulated user agent is independent
|
|
45
|
+
of the installed Chrome version.
|
|
46
|
+
|
|
47
|
+
Network and CPU conditions use Lighthouse simulation, not field measurements.
|
|
48
|
+
Desktop uses 40 ms RTT, 10240 Kbps throughput and a CPU multiplier of one.
|
|
49
|
+
Mobile uses 150 ms RTT, 1638.4 Kbps throughput and a CPU multiplier of four.
|
|
50
|
+
The exact conditions are persisted in the profile, so unlike profiles must not
|
|
51
|
+
be compared as equivalent runs.
|
|
52
|
+
|
|
53
|
+
Anonymous audits default to `--cache cold`: browser cache and origin storage
|
|
54
|
+
are cleared before navigation. `--cache warm` performs an unmeasured initial
|
|
55
|
+
navigation before the measured one. Configured authentication requires
|
|
56
|
+
`--cache auth-preserved`, which retains authentication storage, cache and
|
|
57
|
+
service workers. These conditions are deliberately different profiles.
|
|
58
|
+
|
|
59
|
+
Set `--production production` or `--production development` to declare the
|
|
60
|
+
build mode; the default is `unknown`. Set `--source-build` to an opaque build
|
|
61
|
+
identifier when available, such as a Git commit SHA or build hash. Identifiers
|
|
62
|
+
accept one to 120 letters, digits, dots, underscores or hyphens. Both checks
|
|
63
|
+
runners hash the identifier with the same fingerprint function before storing it. The runner does not infer a production build from
|
|
64
|
+
a fast response or a familiar hostname. A capture association and target state
|
|
65
|
+
fingerprint identify which existing wall entry was audited, while
|
|
66
|
+
`sampledSeparately: true` makes clear that this was a later navigation.
|
|
67
|
+
|
|
68
|
+
Raw metrics are `largestContentfulPaintMs`, `cumulativeLayoutShift` (unitless),
|
|
69
|
+
`firstContentfulPaintMs`, `totalBlockingTimeMs`, `speedIndexMs`,
|
|
70
|
+
`transferredResourceBytes` and `observedRequests`. Unknown values remain `null`.
|
|
71
|
+
`lighthouseLabScore` and optional `lighthouseSeoLabScore` are secondary scores
|
|
72
|
+
from zero to 100. Enable the latter with `--seo`; it is an automated local
|
|
73
|
+
check, not a search ranking claim. Navigation audits do not establish field
|
|
74
|
+
INP or interaction responsiveness. Configured actions run once during the
|
|
75
|
+
navigation window; their presence is recorded as a limitation.
|
|
76
|
+
|
|
77
|
+
## Authentication and intended state
|
|
78
|
+
|
|
79
|
+
A Playwright storage file is not passed blindly to Lighthouse. The adapter
|
|
80
|
+
reads the configured storage file, or executes the trusted configured
|
|
81
|
+
Playwright login script, then deliberately transfers cookies and localStorage
|
|
82
|
+
to the prepared Chrome target. It records a hash of the resulting state and
|
|
83
|
+
never persists the credentials in a report.
|
|
84
|
+
|
|
85
|
+
Only bounded cookie and localStorage state is supported. Partitioned cookies,
|
|
86
|
+
IndexedDB content and unsupported storage shapes fail as unsupported.
|
|
87
|
+
Session storage, browser extensions, custom Playwright selectors and other
|
|
88
|
+
browser-only session mechanisms are not translated. Use standard CSS selectors
|
|
89
|
+
for ready states and configured actions.
|
|
90
|
+
|
|
91
|
+
A configured signed-in audit must declare `waitFor` with a selector visible
|
|
92
|
+
only in the intended signed-in state. The original origin, path and query state
|
|
93
|
+
must match before and after readiness checks and actions. An authentication
|
|
94
|
+
redirect, missing ready selector or unexpected document status produces a
|
|
95
|
+
failed report with unknown metrics. A login page never counts as a successful
|
|
96
|
+
measurement of the intended application.
|
|
97
|
+
|
|
98
|
+
Login scripts are existing trusted local configuration, not code submitted by
|
|
99
|
+
a hosted user. They can have application side effects. Use a dedicated test
|
|
100
|
+
account and the same deliberate fixture discipline as capture automation.
|
|
101
|
+
|
|
102
|
+
## Reports and privacy
|
|
103
|
+
|
|
104
|
+
Reports use the shared bounded checks schema and retain at most 200 reports per
|
|
105
|
+
board. They contain raw numeric metrics, a measurement profile, completeness
|
|
106
|
+
limitations and a capped set of static actionable performance findings.
|
|
107
|
+
Only audited, applicable opportunities from an allowlist become findings.
|
|
108
|
+
Resource URLs, private paths, query values, headers, cookies, response bodies,
|
|
109
|
+
DOM snippets, raw Lighthouse logs and traces are not written to reports.
|
|
110
|
+
Failures also use fixed safe messages rather than raw browser errors.
|
|
111
|
+
|
|
112
|
+
A complete report requires all four primary navigation metrics: LCP, CLS, FCP
|
|
113
|
+
and TBT. Missing metrics produce `partial`; failures and unsupported conditions
|
|
114
|
+
produce no trustworthy numeric measurements. Never substitute zero for missing
|
|
115
|
+
data or mix these reports with capture timings.
|
|
116
|
+
|
|
117
|
+
Reference: [Lighthouse authentication guidance](https://github.com/GoogleChrome/lighthouse/blob/main/docs/authenticated-pages.md),
|
|
118
|
+
[Lighthouse programmatic usage](https://github.com/GoogleChrome/lighthouse/blob/main/docs/readme.md).
|
|
119
|
+
|
|
120
|
+
## Performance budgets and report history
|
|
121
|
+
|
|
122
|
+
Checks keeps up to 200 reports per board. In the Checks panel, expand **History and comparison**,
|
|
123
|
+
choose an after report and a baseline, then inspect raw measurements and finding changes. History
|
|
124
|
+
remains usable when its screenshot has expired. Reports stay separated by runner, page, environment
|
|
125
|
+
and device; repeat samples are individually selectable, not silently averaged.
|
|
126
|
+
|
|
127
|
+
The comparison requires the same recorded runner version, browser, authentication state, configured
|
|
128
|
+
page state, viewport, device emulation, cache, throttling, observation coverage and service worker
|
|
129
|
+
state. Older reports missing browser/device/throttling evidence explain why comparison is unavailable.
|
|
130
|
+
Different declared builds can be compared only by explicitly choosing **Allow declared build as the
|
|
131
|
+
changed variable**. Both runs must have a build fingerprint; this choice never relaxes other conditions.
|
|
132
|
+
Build identifiers are stored as fingerprints, not raw labels. Undeclared builds remain labelled unknown.
|
|
133
|
+
|
|
134
|
+
Missing or failed measurements show **Unknown**, never zero. Deltas use the metric's units. Movement
|
|
135
|
+
below either 5 percent or the display floor (50 ms, 1024 bytes, 0.01 layout shift, otherwise 1) is labelled
|
|
136
|
+
small; these are display rules, not statistical confidence or regression detection. An increase alone
|
|
137
|
+
is not proof of a regression. Finding changes require two complete comparable runs and unchanged budget
|
|
138
|
+
policy; absence in a later run is only “no longer observed,” not proof of a fix.
|
|
139
|
+
|
|
140
|
+
Set optional explicit maximums in the top-level configuration. No performance budgets are enabled by
|
|
141
|
+
default. Choose values appropriate to the app, device and lab setup; the following is an example, not
|
|
142
|
+
an enforced universal target:
|
|
143
|
+
|
|
144
|
+
```json
|
|
145
|
+
{
|
|
146
|
+
"checks": {
|
|
147
|
+
"budgets": {
|
|
148
|
+
"largestContentfulPaintMs": 2500,
|
|
149
|
+
"totalBlockingTimeMs": 200,
|
|
150
|
+
"cumulativeLayoutShift": 0.1,
|
|
151
|
+
"transferredResourceBytes": 1500000,
|
|
152
|
+
"loadMs": 3000
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Each newly run report records the exact configured thresholds and policy version. A known measurement
|
|
159
|
+
above its maximum produces a performance warning with the observation and next action; equality is
|
|
160
|
+
within budget. Missing metrics, including metrics belonging to another runner, remain unknown. Failed
|
|
161
|
+
and unsupported runs never pass budgets. Importing or viewing an old report does not recompute it
|
|
162
|
+
against a newer configuration.
|
|
163
|
+
|
|
164
|
+
Supported metrics are `ttfbMs`, `loadMs`, `domContentLoadedMs`, `documentTransferBytes`,
|
|
165
|
+
`resourceTransferBytes`, `resourceDecodedBytes`, `requestCount`, `largestContentfulPaintMs`,
|
|
166
|
+
`firstContentfulPaintMs`, `totalBlockingTimeMs`, `cumulativeLayoutShift`, `transferredResourceBytes`,
|
|
167
|
+
`observedRequests` and `speedIndexMs`. Values are finite nonnegative maxima in the named units. These
|
|
168
|
+
budgets apply to explicit local `checks` and `audit` runs; they do not schedule scans or measure field vitals.
|
|
169
|
+
|
|
170
|
+
**Problems first** prioritizes failed/unsupported runners, warnings, stale results and partial runs.
|
|
171
|
+
**Performance findings** narrows to observed performance warnings. **Slowest LCP first** orders the
|
|
172
|
+
latest Lighthouse value per page/device view, placing unknown and failed values last. Use the device
|
|
173
|
+
selector to narrow the list. It never combines device scores, and this triage ordering does not make
|
|
174
|
+
runs with different conditions comparable.
|
|
@@ -0,0 +1,325 @@
|
|
|
1
|
+
# The sandboxed starter agent
|
|
2
|
+
|
|
3
|
+
`shapewall agent` takes one board comment at a time and works on it inside a container: it reads the request, edits files in a fresh
|
|
4
|
+
checkout of your repo (with no `.git` in it), runs your tests, replies on the comment and leaves the change on a new branch (and, if you ask, a pull request). It is
|
|
5
|
+
meant for **shared boards**, where the people writing comments are not all people you would hand a shell to.
|
|
6
|
+
|
|
7
|
+
The board chat ([agents.md](agents.md)) runs an agent _as you_, on your machine. The starter agent assumes the comment may be hostile and
|
|
8
|
+
puts walls around the agent instead: the container, an egress allow list, a fixed set of tools, a trigger gate, budgets and branch-only
|
|
9
|
+
output. This page says what each wall does and, as plainly, what it does not.
|
|
10
|
+
|
|
11
|
+
## Quick start
|
|
12
|
+
|
|
13
|
+
You need podman or docker, a git repo with a `shapewall.config.json`, and an OpenAI-compatible model endpoint (the same settings as the
|
|
14
|
+
chat: `agent.baseUrl` and `agent.model`, or `SHAPEWALL_AGENT_BASE_URL` and `SHAPEWALL_AGENT_MODEL`, with the key in
|
|
15
|
+
`SHAPEWALL_AGENT_API_KEY` or the variable `agent.apiKeyEnv` names).
|
|
16
|
+
|
|
17
|
+
1. Build the agent image once. It is built on your machine from the `Dockerfile.agent` that ships in the package, and never pulled
|
|
18
|
+
or published:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npx shapewall agent build-image # --runtime podman|docker, --image NAME (default localhost/shapewall-agent:latest)
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
It builds from a folder holding only what the image needs, with the locked dependency versions (npm never puts
|
|
25
|
+
`package-lock.json` in a package, so the package carries a copy in `dist/agent/`). In a clone of the repository,
|
|
26
|
+
`podman build -f Dockerfile.agent -t localhost/shapewall-agent:latest .` (or `docker build ...`) does the same by hand.
|
|
27
|
+
|
|
28
|
+
2. Say who may dispatch work, and how to test, in `shapewall.config.json`:
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
"starterAgent": {
|
|
32
|
+
"trusted": ["robin", "sam"],
|
|
33
|
+
"setupCommand": "npm ci",
|
|
34
|
+
"testCommand": "npm test"
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
3. Check the machine and the sandbox:
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
npx shapewall agent doctor
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The doctor starts a container exactly like the agent's (same network, proxy, mounts, user and limits) with a probe in place of the
|
|
45
|
+
agent, and reports each check: not root, no capabilities, no new privileges, read-only root, only the checkout mounted, no home
|
|
46
|
+
folder, SSH keys or runtime socket, no host environment, no direct egress or outside DNS, no way to this machine's own ports, and a
|
|
47
|
+
proxy that refuses hosts off the list and TLS names other than the allowed one.
|
|
48
|
+
|
|
49
|
+
`agent run` and `agent watch` start by removing what runs that died left behind (containers, networks and checkout folders whose
|
|
50
|
+
owner process is gone).
|
|
51
|
+
|
|
52
|
+
4. Run it on a comment, or watch the board:
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
npx shapewall agent run --comment 12
|
|
56
|
+
npx shapewall agent watch # every comment the gate lets through; --once to drain and exit
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The reply on the comment says what changed, the branch, the tests, anything the proxy blocked, and the budget used, for example
|
|
60
|
+
`Budget: 6 of 20 turns, 41,200 of 200,000 tokens, 2m 14s of 15m.` The comment's agent status ends as `done` or `needs-human`.
|
|
61
|
+
|
|
62
|
+
## The trigger gate
|
|
63
|
+
|
|
64
|
+
Anyone who can comment can write text the agent will act on, so a comment is dispatched only when a trusted member stands behind it:
|
|
65
|
+
|
|
66
|
+
- a **share link guest's** comment (`authorGuest`) is never dispatched, whoever tags it later, and guest replies are left out of the
|
|
67
|
+
task;
|
|
68
|
+
- a comment **written by an agent** is never dispatched, so agents do not feed each other;
|
|
69
|
+
- a **trusted member's** own comment is dispatched;
|
|
70
|
+
- anyone else's comment **waits** until a trusted member replies with `@agent`. The tag vouches for the text as it was: if the comment
|
|
71
|
+
is edited after the tag, it waits for a new one.
|
|
72
|
+
|
|
73
|
+
`starterAgent.trusted` is the default list; `starterAgent.boards.<id>.trusted` replaces it for one board; `--trusted NAME` adds to it for
|
|
74
|
+
one run. An empty list dispatches nothing. `--trust-comment` runs one comment the gate holds back (never a guest's or an agent's).
|
|
75
|
+
|
|
76
|
+
Who counts as a member depends on the board:
|
|
77
|
+
|
|
78
|
+
- **Hosted boards** (`--remote`): the account handle the server attests (`authorHandle`, `reply.handle`). Display names never count.
|
|
79
|
+
- **Local boards**: the author name as typed. A local board has no accounts, so this is only as strong as who can reach the board. On
|
|
80
|
+
a board shared through a proxy, anyone who can comment can type a trusted name: put real authentication in front (see
|
|
81
|
+
[deployment.md](deployment.md)) or use a hosted board.
|
|
82
|
+
|
|
83
|
+
A comment is claimed with a compare-and-set on its agent status, so two runs never take the same comment. `--retry` takes one whose
|
|
84
|
+
status is `done` or `needs-human`.
|
|
85
|
+
|
|
86
|
+
## What the agent can do
|
|
87
|
+
|
|
88
|
+
A fixed set of tools, nothing else:
|
|
89
|
+
|
|
90
|
+
| Tool | What it does |
|
|
91
|
+
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
92
|
+
| `list_files`, `read_file`, `search` | Read the checkout. `.git` is refused. |
|
|
93
|
+
| `write_file`, `edit_file` | Change files in the checkout. Paths are resolved after symlinks; anything outside the checkout, or in `.git`, is refused. |
|
|
94
|
+
| `run_tests` | Runs `starterAgent.testCommand` (no shell), only when one is set. Needs your approval after the agent changed what it runs. |
|
|
95
|
+
| `capture` | `shapewall capture --only <page>` in the checkout. Offered only when the site is reachable from the sandbox (see below). |
|
|
96
|
+
| `reply`, `set_status` | Up to 3 replies on the comment (2,000 characters each), and its agent status. |
|
|
97
|
+
| `run_shell` | Any command, but only after you approve that exact command on the board (local boards only, see below). |
|
|
98
|
+
|
|
99
|
+
`starterAgent.setupCommand` (for example `npm ci`) runs once before the agent starts, in the container, with the package registry
|
|
100
|
+
reachable.
|
|
101
|
+
|
|
102
|
+
Paths are relative to the repo root. Models often write the container's mount point into them, so `/work/src/app.js`, and
|
|
103
|
+
`work/src/app.js` when the repo has no top-level `work`, both mean `src/app.js`. A path that does not exist answers
|
|
104
|
+
`path not found: <path>; paths are relative to the repo root`, for reads, listings, searches and edits alike.
|
|
105
|
+
|
|
106
|
+
`capture` is offered only when the board's `baseUrl` can be reached from the sandbox: its host and port must be on the egress allow list
|
|
107
|
+
(`--allow-host`), and it must not be this machine (`localhost`, `127.0.0.1`: in the container that is the container itself) or a
|
|
108
|
+
private address you did not allow. A dev server on your machine is not reachable, by design, so with the usual
|
|
109
|
+
`http://127.0.0.1:...` baseUrl the agent has no `capture` tool and its prompt says it cannot see the site. If it calls `capture` anyway,
|
|
110
|
+
or a capture cannot connect, the answer is `capture is unavailable in the sandbox; skip it`.
|
|
111
|
+
|
|
112
|
+
### Tests run the agent's code
|
|
113
|
+
|
|
114
|
+
Be plain about this: `run_tests` runs your test command over files the agent may have just changed, so a test is code the agent wrote,
|
|
115
|
+
and it runs with everything the sandbox allows. The walls around the container are what limit it, not the tool list. The approval of
|
|
116
|
+
`run_shell` happens inside the agent's own process (the host shows the card and waits for you; the container asks), so it limits what the
|
|
117
|
+
model can do through the tools, not what code already running in the sandbox can do.
|
|
118
|
+
|
|
119
|
+
One rule narrows it: once the agent changed a file that decides what the test command runs (a manifest or lockfile, `.npmrc`, a test,
|
|
120
|
+
build or TypeScript config, `Makefile`, `justfile`, `pyproject.toml` and the like, or a file the test command names), or ran an approved
|
|
121
|
+
shell command, `run_tests` asks for your approval on the board like `run_shell` does, and is not run where there are no approvals.
|
|
122
|
+
|
|
123
|
+
### Approving shell commands
|
|
124
|
+
|
|
125
|
+
When the agent asks for `run_shell`, the comment's chat thread on the board shows a permission card with the exact command and the
|
|
126
|
+
agent's reason. The terminal running `agent run` prints the command and a link that opens the board on the comment with its chat
|
|
127
|
+
thread (the running `shapewall serve`'s own address when it recorded one, else `SHAPEWALL_BOARD_URL`, `notifications.boardUrl` or the
|
|
128
|
+
default). **Run** runs that command once; **Deny**, or no answer within two minutes, is a no. The card can only be answered from
|
|
129
|
+
the board on this machine: the request needs the settings token from the link `shapewall serve` prints, must be a direct local request,
|
|
130
|
+
same-origin, on a board that is not shared. Nobody at the board means no answer, which is a no. On hosted boards (`--remote`) the card
|
|
131
|
+
is on the hosted board instead (see [Hosted boards](#hosted-boards)).
|
|
132
|
+
|
|
133
|
+
## Budgets
|
|
134
|
+
|
|
135
|
+
Each comment gets a budget of model turns, tokens and wall time (defaults 20 turns, 200,000 tokens, 15 minutes; at most 100, 2,000,000 and
|
|
136
|
+
120). Set them in `starterAgent.budget` or per run with `--max-turns`, `--max-tokens` and `--max-minutes`.
|
|
137
|
+
|
|
138
|
+
They are enforced on the host, not by the agent: every model call goes through Shapewall on the host, one at a time, which refuses calls
|
|
139
|
+
past the turn or token budget, reserves each call's prompt (estimated at four characters a token) and caps its `max_tokens` at what is
|
|
140
|
+
left after that. Tokens are counted from the usage the endpoint reports (or estimated
|
|
141
|
+
at four characters a token, and the reply says "estimated"). At the wall time the host asks the agent to stop, and kills the container a
|
|
142
|
+
few seconds later. The reply always reports what was used.
|
|
143
|
+
|
|
144
|
+
Each model call has a time limit to start answering (its response headers): 180 seconds until the model first answers in a run (a
|
|
145
|
+
local model loading on a cold start can take minutes), 60 seconds after. `starterAgent.modelTimeoutSeconds` or `--model-timeout SECONDS`
|
|
146
|
+
(1 to 900) sets both. A call that times out or cannot connect is tried once more, as the same turn, within the wall time; if that fails
|
|
147
|
+
too, the run stops with one plain line, such as `Stopped: the model endpoint failed (could not reach it: timed out after 180 s).`
|
|
148
|
+
|
|
149
|
+
The checkout has a disk cap too (`starterAgent.limits.disk` or `--max-disk`, default `2g`, at most `64g`): a bind mount has no size limit
|
|
150
|
+
of its own on podman or docker, so the host measures the folder every few seconds (`du`, one file system, no symlink followed) and
|
|
151
|
+
kills the container as soon as it is over. Nothing is committed then, and the reply says how much it took. `/tmp` in the container is a
|
|
152
|
+
tmpfs with its own size (`limits.tmp`, default `1g`).
|
|
153
|
+
|
|
154
|
+
## Output: a branch, never main
|
|
155
|
+
|
|
156
|
+
The change is committed on a new branch, `shapewall-agent/<board>-<comment>-<id>` (prefix from `starterAgent.branchPrefix`), authored
|
|
157
|
+
`Shapewall starter agent <starter-agent@shapewall.invalid>`, with `shapewall:<board>/<comment>` in the message so
|
|
158
|
+
[GitHub connect](github.md) links it. Branch names that are, or end in, `main`, `master`, `trunk`, `develop`, `production`, `staging`
|
|
159
|
+
or `release` are refused, for the branch and for the push, and the branch is only created if it does not exist.
|
|
160
|
+
|
|
161
|
+
The commit is made without trusting anything in the folder the container had. That folder has no `.git` (an agent that writes one
|
|
162
|
+
changes nothing), and git on the host always names your repository explicitly, with a temporary index outside the folder, no system
|
|
163
|
+
config, and hooks, fsmonitor and signing off. Shapewall reads the changed files itself, without following a symlink anywhere in a path
|
|
164
|
+
(a symlink is committed as a symlink) and refusing hard-linked files, and writes them with `git hash-object --no-filters`, so no clean
|
|
165
|
+
filter, attribute or config from the agent's files runs. `.gitattributes` and `.gitmodules` keep the base's version, and submodules are
|
|
166
|
+
left as they were. The reply calls out changes to dot files, package manifests, `Makefile`, `Dockerfile`, `justfile` and
|
|
167
|
+
`shapewall.config.json`, and symlinks that point outside the repository (`--pr` does not push those without `--allow-ci-push`).
|
|
168
|
+
Nothing is read from the folder until the agent container is confirmed gone; if it cannot be removed, nothing is committed and the
|
|
169
|
+
folder is left for the sweep. One commit reads in at most the disk cap's worth of changed files (a sparse file looks small to `du`).
|
|
170
|
+
|
|
171
|
+
`--pr` also pushes the branch to `--git-remote NAME` (default `origin`, explicit refspec, `--no-verify`, no tags, no submodules) and opens a pull request into
|
|
172
|
+
`starterAgent.prBase` (default: the remote's default branch) through GitHub connect, then links it to the comment. The token is GitHub
|
|
173
|
+
connect's (`SHAPEWALL_GITHUB_TOKEN` or `GITHUB_TOKEN`) and never enters the container. Nothing is ever pushed to main.
|
|
174
|
+
|
|
175
|
+
A pushed branch runs CI with the repository's secrets before anyone reviews it. So `--pr` does not push a change to CI config
|
|
176
|
+
(`.github/`, `.gitlab-ci.yml`, `.circleci/` and the like), dependency manifests and lockfiles, or build and task files (`Makefile`,
|
|
177
|
+
`Dockerfile`, ...): the branch stays local and the reply says why. `--allow-ci-push` pushes it anyway, for that run. Better still, pass
|
|
178
|
+
`--fork-remote NAME` with a git remote of your fork: the branch goes there and the pull request comes from
|
|
179
|
+
`<owner>:<branch>`, so the main repository's workflows treat it as a fork's (no secrets, unless a workflow uses `pull_request_target`; the CI-file rule above still applies). Even a change to plain source files can do
|
|
180
|
+
harm in a job that runs tests with secrets on push to any branch: prefer a fork, or CI that gives branch pushes no secrets.
|
|
181
|
+
|
|
182
|
+
The checkout lives under `~/.cache/shapewall/starter-agent/` (or `--work-dir`) and is removed after the run; the branch stays.
|
|
183
|
+
|
|
184
|
+
A run that only added new files and changed no existing one says so in the reply ("check it edited the right place"): a small model
|
|
185
|
+
that cannot find the file behind a page often makes a new one the site never uses.
|
|
186
|
+
|
|
187
|
+
The run's log is kept next to the board (`<board>/agent/starter-<comment>-<run>.log`, hosted runs: in the work folder). It starts with
|
|
188
|
+
a line naming the comment, model, endpoint host and budget, and ends with the outcome (status, why it stopped, the branch, the budget
|
|
189
|
+
used), failures and timeouts included. In between: which tools were offered, each turn's answer text (up to 4,000 characters a turn),
|
|
190
|
+
each tool call with its arguments (long values cut) and result, every approval asked and answered with the command's text and its
|
|
191
|
+
SHA-256, model endpoint retries, egress refusals and the container's stderr. The key is removed from every line, and no request header
|
|
192
|
+
is logged.
|
|
193
|
+
|
|
194
|
+
## Configuration
|
|
195
|
+
|
|
196
|
+
`starterAgent` in `shapewall.config.json` (usually committed) may only choose what stays inside the sandbox:
|
|
197
|
+
|
|
198
|
+
| Key | Default | Notes |
|
|
199
|
+
| --------------------- | -------------------------------------------------- | -------------------------------------------------------- |
|
|
200
|
+
| `trusted` | `[]` | Who may dispatch work, on every board. |
|
|
201
|
+
| `boards.<id>.trusted` | | Replaces `trusted` for one board. |
|
|
202
|
+
| `testCommand` | none | One program and its arguments, no shell. |
|
|
203
|
+
| `setupCommand` | none | Runs once before the agent, with the registry reachable. |
|
|
204
|
+
| `budget` | `{ turns: 20, tokens: 200000, minutes: 15 }` | |
|
|
205
|
+
| `modelTimeoutSeconds` | 180 for the first call, then 60 | Time for a model call to start answering, 1 to 900. |
|
|
206
|
+
| `limits` | `{ memory: "4g", cpus: 2, pids: 512, disk: "2g" }` | Memory and `tmp` up to `16g`, CPUs up to 8, disk `64g`. |
|
|
207
|
+
| `branchPrefix` | `shapewall-agent/` | Lowercase, ending in `/`. |
|
|
208
|
+
| `prBase` | the remote's default branch | The base branch of `--pr`. |
|
|
209
|
+
|
|
210
|
+
What decides what leaves the sandbox comes only from you, never from the repo: a config with `image`, `runtime`, `registry`, `egress`,
|
|
211
|
+
`allowHosts`, `network`, `apiKey`, `env` or `mounts` under `starterAgent` is refused, and so is `remote` or `forkRemote` (where the
|
|
212
|
+
branch is pushed is a flag: `--git-remote`, `--fork-remote`).
|
|
213
|
+
|
|
214
|
+
| Flag | Environment | What |
|
|
215
|
+
| -------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
216
|
+
| `--runtime` | `SHAPEWALL_AGENT_RUNTIME` | `podman` or `docker` (default: whichever is installed, podman first). |
|
|
217
|
+
| `--image` | `SHAPEWALL_AGENT_IMAGE` | Default `localhost/shapewall-agent:latest`. |
|
|
218
|
+
| `--registry HOST`, `none` | `SHAPEWALL_AGENT_REGISTRY` | Default `registry.npmjs.org:443`. |
|
|
219
|
+
| `--allow-host HOST[:PORT]` | `SHAPEWALL_AGENT_EGRESS` (comma-separated) | Extra egress hosts (port 443 if none given). |
|
|
220
|
+
| `--profile` | | `openai-compatible` (the default). `claude-code` and `codex` are reserved and say "not available yet". |
|
|
221
|
+
| `--max-disk SIZE` | | The disk cap on the checkout for this run (default `2g`). |
|
|
222
|
+
| `--model-timeout SECONDS` | | Time for a model call to start answering, 1 to 900 (overrides `starterAgent.modelTimeoutSeconds`). |
|
|
223
|
+
| `--work-dir` | | Where checkouts go. |
|
|
224
|
+
| `--allow-ci-push` | | With `--pr`: push even when the change touches CI config, manifests or build files. |
|
|
225
|
+
| `--git-remote NAME` | | With `--pr`: the remote to push to (default `origin`). |
|
|
226
|
+
| `--fork-remote NAME` | | With `--pr`: push to this remote (your fork) and open the pull request from it. |
|
|
227
|
+
| `--remote URL` | | A hosted board instead of the local one (`run` and `watch`). |
|
|
228
|
+
|
|
229
|
+
The model endpoint and key follow the chat's rules ([agents.md](agents.md)): a config cannot send your key to a host you did not
|
|
230
|
+
confirm. The starter agent always uses the OpenAI-compatible endpoint, never the chat's ACP agent.
|
|
231
|
+
|
|
232
|
+
## Threat model
|
|
233
|
+
|
|
234
|
+
The starting assumption: the comment, the page text and the repo can all be hostile, and the model may do whatever they talk it into.
|
|
235
|
+
|
|
236
|
+
### The container
|
|
237
|
+
|
|
238
|
+
Every run gets its own network and two containers, both from the local image (`--pull never`):
|
|
239
|
+
|
|
240
|
+
- **The agent container:** on the run's internal network (no route out, no outside DNS). The fresh checkout is mounted read-write at
|
|
241
|
+
`/work`, and nothing else: not your home folder, SSH keys, browser profile, the docker or podman socket, or your repository's `.git`
|
|
242
|
+
(the checkout has none). It runs as your
|
|
243
|
+
uid (never root; `--userns keep-id` on podman), with a read-only root file system and a small `/tmp`, every capability dropped,
|
|
244
|
+
`no-new-privileges`, memory, CPU and process limits, and an environment of a few fixed names: no host variable, and no key. The
|
|
245
|
+
agent is the container's first process (no init) and runs from a copy of node its user may execute but not read, which makes the
|
|
246
|
+
kernel mark it not dumpable: a test or approved command, running as the same user, cannot open its `/proc` files, so it cannot write
|
|
247
|
+
to the agent's line protocol with the host or read its memory. The host still checks every line it gets (results field by field, one
|
|
248
|
+
approval at a time, at most 10 per run, replies and cards limited).
|
|
249
|
+
- **The egress proxy:** on the run network and on `shapewall-egress`, the only way out. It passes HTTP `CONNECT` and plain `http://`
|
|
250
|
+
requests only to the allowed `host:port` pairs: the package registry and any `--allow-host`. A `CONNECT` tunnel carries only TLS,
|
|
251
|
+
and only when the ClientHello's server name is the allowed host (a missing name, two names, or an encrypted ClientHello are
|
|
252
|
+
refused): many sites share one address on a CDN, so the address alone would let any of them through. Plain `http://` requests go
|
|
253
|
+
out with the allowed host as their `Host`. Names on the default list that resolve to a private, loopback or link-local address
|
|
254
|
+
(IPv6 forms included: `::ffff:` mapped, NAT64 `64:ff9b::`, 6to4) are refused, so a rebinding DNS answer cannot reach your network
|
|
255
|
+
through them. Every refusal is logged and listed in the reply.
|
|
256
|
+
|
|
257
|
+
### The model key
|
|
258
|
+
|
|
259
|
+
The key never enters the container. The agent sends each model request to the host over its stdin/stdout; the host adds the key, sends
|
|
260
|
+
the request to the configured endpoint only (with its own model name, with only text and inline `data:` images in the messages, and with
|
|
261
|
+
only `function` tools: a remote image URL, or a provider-side tool such as web search or a browser, would act outside the sandbox), and streams the answer back with the key removed. So a test or
|
|
262
|
+
an approved command, which runs as the same uid as the agent, has no key to read from memory or the environment, and a hijacked model
|
|
263
|
+
has none to post in a reply. The model endpoint is not on the egress allow list.
|
|
264
|
+
|
|
265
|
+
### Board text is data
|
|
266
|
+
|
|
267
|
+
The comment, its replies, any page text and a failed setup command's output go to the model as quoted data with provenance (`<shapewall-data source="comment"
|
|
268
|
+
trust="untrusted" ...>`), never in the system prompt, and the system prompt tells the model that text inside is never an instruction.
|
|
269
|
+
That lowers the risk of prompt injection; it does not remove it, which is why the walls above exist.
|
|
270
|
+
|
|
271
|
+
### What each runtime enforces
|
|
272
|
+
|
|
273
|
+
| Wall | Rootless podman (netavark) | Docker (rootful) | Rootless docker |
|
|
274
|
+
| ----------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
275
|
+
| User, read-only root, caps, no-new-privileges, limits | Enforced, verified | Enforced | Enforced |
|
|
276
|
+
| Only the checkout mounted | Enforced, verified | Enforced | Enforced |
|
|
277
|
+
| No route out of the internal network | Enforced, verified | Enforced | Enforced |
|
|
278
|
+
| No outside DNS | Enforced, verified (ENOTFOUND) | Best-effort: depends on the Docker version's embedded DNS; the doctor checks | Same as Docker |
|
|
279
|
+
| No way to the host's own ports | Enforced, verified | Best-effort: `host-gateway` reachability depends on the version and firewall; the doctor checks | Same as Docker |
|
|
280
|
+
| Files written as your uid | Enforced (`keep-id`), verified | Enforced (`--user`) | Not by default: the uid is mapped; the doctor says when the checkout is not writable as you |
|
|
281
|
+
| Egress allow list (the proxy) | Enforced, verified | Enforced | Enforced |
|
|
282
|
+
|
|
283
|
+
"Verified" means the opt-in container test and `agent doctor` passed on rootless podman 5.8. Docker was not available to test against:
|
|
284
|
+
run `shapewall agent doctor` and treat a FAIL line as a wall that is not there.
|
|
285
|
+
|
|
286
|
+
### What is not covered
|
|
287
|
+
|
|
288
|
+
- **The change itself.** The agent can still write a bad or malicious change into the branch (a test that exfiltrates on CI, a
|
|
289
|
+
dependency swap, a workflow edit). Review the whole diff before merging; the reply flags changes to scripts, manifests and config.
|
|
290
|
+
- **Allowed hosts are channels.** Anything the proxy lets through (the registry, your `--allow-host` entries) can carry data out. The
|
|
291
|
+
npm registry takes publishes: code in the sandbox can publish a package (to an account it creates) with whatever it read, and the
|
|
292
|
+
TLS name check does not stop that. Keep the list short; `--registry none` when setup does not need it.
|
|
293
|
+
- **Tests and approved commands** run code the agent may have written (see [Tests run the agent's code](#tests-run-the-agents-code)).
|
|
294
|
+
- **What your model provider sees**: the comment, the files the agent reads, and the tool output.
|
|
295
|
+
- **Local author names are not authenticated** (see [The trigger gate](#the-trigger-gate)).
|
|
296
|
+
- **Commands you approve** run in the sandbox with the same walls as the agent, but they run: read them.
|
|
297
|
+
- **`capture`** works only for a site the sandbox can reach, and is not offered otherwise. A dev server on your machine is not
|
|
298
|
+
reachable, by design.
|
|
299
|
+
- **The `claude-code` and `codex` profiles** are reserved names, not implementations: those CLIs would need their own login inside the
|
|
300
|
+
sandbox, which this version does not do.
|
|
301
|
+
- **Container escapes** through kernel or runtime bugs. Keep podman or docker up to date.
|
|
302
|
+
|
|
303
|
+
### Hosted boards
|
|
304
|
+
|
|
305
|
+
Run the starter on your own machine with a local repository and configuration:
|
|
306
|
+
`shapewall agent run --remote https://board.example --board site --comment 12`.
|
|
307
|
+
Supply the project token through `SHAPEWALL_TOKEN`, a protected token file, or
|
|
308
|
+
`shapewall login`; it needs `read,reply,status,claim`. Hosted trust comes only
|
|
309
|
+
from the server's Agent policy and hash-bound Send to agent action. Local
|
|
310
|
+
`starterAgent.trusted`, `--trusted` and `--trust-comment` cannot bypass it.
|
|
311
|
+
Guest and agent comments never start work; imports require a trusted vouch.
|
|
312
|
+
|
|
313
|
+
Shell requests create permission cards at the top of the hosted board. A
|
|
314
|
+
trusted admin checks the exact command and approves once with a fresh passkey.
|
|
315
|
+
No answer within two minutes means no execution. Editing the comment, ending
|
|
316
|
+
the claim, changing policy, or losing token authority invalidates the card.
|
|
317
|
+
The hosted server never executes the command; the developer's sandbox does.
|
|
318
|
+
|
|
319
|
+
`--pr` also works with a hosted source when the local repository has GitHub
|
|
320
|
+
connect configured. The existing push guard still blocks CI/workflow-sensitive
|
|
321
|
+
changes unless explicitly allowed by the runner. The GitHub credential remains
|
|
322
|
+
on the runner; it is never uploaded with the board or given to the sandbox.
|
|
323
|
+
Comments and captures are untrusted text. A shell-capable agent with a readable
|
|
324
|
+
token remains a prompt-injection risk: read [agent-hardening.md](agent-hardening.md)
|
|
325
|
+
and keep both server claim budgets and per-run turns/tokens/minutes limits.
|
package/docs/updates.md
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Installation updates
|
|
2
|
+
|
|
3
|
+
The small credit and version below the board and workspace console open **About & Updates**. On a local installation, the profile menu
|
|
4
|
+
opens **Workspace Console** at `/console`, with real local board cards and a **Settings** section for appearance preferences, installation details and **About & Updates**. The version includes the source revision,
|
|
5
|
+
so two builds of the same package version can still be distinguished. A static export or public demo shows its own build version;
|
|
6
|
+
it cannot update a server.
|
|
7
|
+
|
|
8
|
+
Updates are manual. Opening the panel reads installation details but never contacts a release provider or installs anything. There are
|
|
9
|
+
no update timers, automatic downloads or automatic restarts. **Check for updates** asks the installer-provided helper for the latest
|
|
10
|
+
prepared release. **Update now** explicitly activates it. After the server restarts, the panel verifies the new running revision and
|
|
11
|
+
offers **Reload Shapewall**.
|
|
12
|
+
|
|
13
|
+
## Ordinary installations
|
|
14
|
+
|
|
15
|
+
Without an update helper, the panel explains that the installation owner manages updates. Update using the same method used to install
|
|
16
|
+
Shapewall, then restart `shapewall serve`. Keep the project's config and `.shapewall/` data. An npm install, a source checkout and a
|
|
17
|
+
container image do not share an updater; Shapewall does not guess a command or run `npm update` on your behalf.
|
|
18
|
+
|
|
19
|
+
- **A clone:** stop your server, `git pull` (or check out the release tag you want), run `npm ci` in the clone, and start the server
|
|
20
|
+
again with the same config.
|
|
21
|
+
- **Installed in a project from npm:** run `npm install --save-dev shapewall@latest` (or a version, such as `shapewall@0.2.1`), then
|
|
22
|
+
restart with `npx shapewall serve`.
|
|
23
|
+
- **Installed in a project from GitHub:** run `npm install --save-dev github:danbaruch/shapewall` again (add `#<tag>` to pin a
|
|
24
|
+
release tag), then restart with `npx shapewall serve`.
|
|
25
|
+
- **A tarball:** `npm install --save-dev /absolute/path/to/shapewall-0.2.1.tgz`, then restart.
|
|
26
|
+
|
|
27
|
+
The source revision in **About & Updates** tells two builds of the same version apart. Before switching, back up the config, captures, comments and account data, and keep the previous build
|
|
28
|
+
so you can go back. A server that runs as a service should be updated by replacing its release, not by editing the live folder.
|
|
29
|
+
|
|
30
|
+
## Managed installations
|
|
31
|
+
|
|
32
|
+
An operator can provide `SHAPEWALL_UPDATE_HELPER`, an absolute path to a trusted executable. Shapewall invokes that exact executable
|
|
33
|
+
with one argument, `check` or `apply`, without a shell. The browser cannot supply commands, paths, download URLs or target revisions.
|
|
34
|
+
The helper must serialize changes across processes and preserve the previous release for rollback. The server supplies the actual
|
|
35
|
+
running source revision as `SHAPEWALL_RUNNING_REVISION`, overriding inherited values. Compare that revision with the new release,
|
|
36
|
+
not only the installation symlink: a previous attempt may have switched the pointer before its server restarted.
|
|
37
|
+
|
|
38
|
+
On success the helper prints only JSON:
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{ "latest": { "version": "0.1.0", "revision": "abcdef1234567890abcdef1234567890abcdef1234" }, "updateAvailable": true }
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
An apply operation that needs this server to restart also returns `"restartRequired": true`. Only managed `serve` installations with
|
|
45
|
+
`SHAPEWALL_UPDATE_RESTART=1` honor that flag: after acknowledging the request they exit with code 75. The existing service manager must
|
|
46
|
+
restart failures. Do not enable this option for an unmanaged terminal process. The UI waits for the advertised revision to run; helper
|
|
47
|
+
success alone is not installation success. Failed helpers and checks never restart the app. The helper must not print credentials or
|
|
48
|
+
diagnostic logs to stdout; the server returns bounded, generic errors.
|
|
49
|
+
|
|
50
|
+
### Prepared immutable releases
|
|
51
|
+
|
|
52
|
+
`scripts/managed-update.py` is a reference helper for Linux services. It does not fetch or build software, execute package managers,
|
|
53
|
+
change a service unit or require sudo. An operator first builds, tests and stages a release into a root-owned installation's `releases/`
|
|
54
|
+
directory, including `dist/client/build-info.json`. The operator installs the helper root-owned and configures the fixed file
|
|
55
|
+
`/etc/shapewall/updater.json`:
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{ "installRoot": "/opt/example-shapewall", "pointerRoot": "/var/lib/example-shapewall/install" }
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The installation root, release directories and metadata must be root-owned and not writable by other users. The pointer directory must
|
|
62
|
+
be owned by the app user with mode 0700. Its `current` and `previous` symlinks point at immutable release directories. Start the service
|
|
63
|
+
through that `current` pointer, directly or through another fixed symlink. Give the app write permission only to its data and pointer
|
|
64
|
+
directory; existing `NoNewPrivileges` and filesystem restrictions can stay enabled.
|
|
65
|
+
|
|
66
|
+
Publish a prepared release by atomically writing the root-owned `installRoot/update-channel.json`:
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{ "release": "release-abcdef1" }
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Checking reads that file and validates release metadata. Applying takes a file lock, saves `previous`, atomically switches `current`,
|
|
73
|
+
and asks the app to restart. Config, captures and comments remain in their data directory. A rollback points `current` at `previous`
|
|
74
|
+
and restarts the service. After an update, open the board and try a real flow: a running service can still serve a broken UI. If a
|
|
75
|
+
release starts and fails later, roll back by hand.
|
|
76
|
+
|
|
77
|
+
### Who can update
|
|
78
|
+
|
|
79
|
+
The local owner link authorizes updates using the existing settings capability, sent in a header. Shared, read-only and unpaired
|
|
80
|
+
visitors cannot update. Mutations require same-origin JSON requests and accept an empty object only.
|
|
81
|
+
|
|
82
|
+
For a service behind a separately authenticated owner-only reverse proxy, an operator can configure `SHAPEWALL_UPDATE_TOKEN` (at least 32 characters, or the server refuses to start) and have
|
|
83
|
+
that proxy overwrite `X-Shapewall-Update-Token` with the same secret **only after verifying the installation owner**. Keep the token in
|
|
84
|
+
private server/proxy configuration, never browser code, a URL or a public repository. Ten wrong tokens from one address within 15 minutes block requests carrying the header from that address until the window ends. The application listener must remain private;
|
|
85
|
+
do not trust a client-supplied header or configure the header on a multi-user board. Shapewall still checks Host, Origin and JSON.
|
|
86
|
+
|
|
87
|
+
This capability can replace executable app code. Enable it only for the installation owner, independently of comment or board access.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"pageId": "checkout",
|
|
4
|
+
"viewport": "desktop",
|
|
5
|
+
"accessibility": true,
|
|
6
|
+
"steps": [
|
|
7
|
+
{
|
|
8
|
+
"action": { "click": "button.cart" },
|
|
9
|
+
"ready": "section.cart",
|
|
10
|
+
"maxDurationMs": 1500
|
|
11
|
+
},
|
|
12
|
+
{
|
|
13
|
+
"action": { "fill": ["input.quantity", "2"] },
|
|
14
|
+
"ready": "button.update"
|
|
15
|
+
}
|
|
16
|
+
]
|
|
17
|
+
}
|