shapewall 0.3.3 → 0.7.0
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 +501 -0
- package/README.md +87 -4
- package/THIRD_PARTY.md +15 -0
- package/dist/agent/package-lock.json +594 -2
- package/dist/client/assets/BoardChat-WS8mAIW6.js +27 -0
- package/dist/client/assets/{BuzzDialog-Ix9qJvim.js → BuzzDialog-B-Mlr6wF.js} +1 -1
- package/dist/client/assets/ChecksPanel-Dx1ZLBR6.js +1 -0
- package/dist/client/assets/History-sXhmpcvs.js +1 -0
- package/dist/client/assets/LocalSettings-CtGzz9F3.js +1 -0
- package/dist/client/assets/{Management-NVFDtSZB.js → Management-CGHe8Wt9.js} +1 -1
- package/dist/client/assets/QuickConnect-DEk84E4A.js +1 -0
- package/dist/client/assets/{ShareDialog-By0ETg6n.js → ShareDialog-CGGx-AYK.js} +2 -2
- package/dist/client/assets/{app-update-dialog-RGIw24iZ.js → app-update-dialog-_bVp8hnC.js} +1 -1
- package/dist/client/assets/{circle-x-B6KfScOE.js → circle-x-BWoHA1QY.js} +1 -1
- package/dist/client/assets/index-Bm-Xd3YN.js +37 -0
- package/dist/client/assets/index-C7Ostk3K.css +2 -0
- package/dist/client/assets/play-BzQ3tRTv.js +1 -0
- package/dist/client/assets/{refresh-cw-vkgvCCfR.js → refresh-cw-BYBMyDKT.js} +1 -1
- package/dist/client/assets/{runtime-Bft6x_6E.js → runtime-Bvq10IhH.js} +1 -1
- package/dist/client/assets/ui-CAY6myRA.js +41 -0
- package/dist/client/build-info.json +1 -1
- package/dist/client/index.html +3 -3
- package/dist/client/sw.js +2 -2
- package/dist/console/assets/LocalAccountsApp-CWRguRRL.js +1 -0
- package/dist/console/assets/LocalConsole--I2SaIpr.js +2 -0
- package/dist/console/assets/LocalUsage-BmpCZ36k.js +1 -0
- package/dist/console/assets/app-update-dialog-B8M9plaT.js +1 -0
- package/dist/console/assets/app-version-muKrQqbL.js +1 -0
- package/dist/console/assets/console-CrhTsPbz.css +2 -0
- package/dist/console/assets/console-DxapQ9oS.js +11 -0
- package/dist/console/assets/local-agents-CoqD4dSN.js +6 -0
- package/dist/console/assets/minus-DDQ0ydcM.js +1 -0
- package/dist/console/assets/tailnet-C5Flwl_d.js +2 -0
- package/dist/console/assets/theme-DCd0qh4l.js +1 -0
- package/dist/console/assets/ui-Bry1mnCY.js +41 -0
- package/dist/console/assets/usage-CIPWnHaS.css +1 -0
- package/dist/console/assets/usage-CqVjMb7m.js +5 -0
- package/dist/console/assets/usage-D1G0GgE3.js +56 -0
- package/dist/console/build-info.json +1 -1
- package/dist/console/console.html +8 -2
- package/docs/agent-hardening.md +206 -0
- package/docs/agent-recipes.md +23 -0
- package/docs/agent-workflow.md +5 -0
- package/docs/agents.md +49 -6
- package/docs/architecture.md +10 -4
- package/docs/deployment.md +39 -17
- package/docs/design-system.md +56 -7
- package/docs/hosted.md +1800 -46
- 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/where-to-run.md +119 -3
- package/package.json +6 -1
- package/src/agent/backends/acp.js +745 -44
- package/src/agent/branch-mode.js +17 -3
- package/src/agent/card-hash.js +65 -0
- package/src/agent/context.js +41 -0
- package/src/agent/exec-paths.js +105 -0
- package/src/agent/routes.js +23 -2
- package/src/agent/run.js +11 -1
- package/src/agent/starter/cli.js +6 -1
- package/src/agent/turn-changes.js +70 -8
- package/src/agent/usage-log.js +251 -0
- package/src/cli/args.js +37 -0
- package/src/cli/commands.js +20 -5
- package/src/cli/help.js +73 -3
- package/src/cli/init.js +2 -1
- package/src/cli/serve.js +20 -5
- package/src/cli.js +8 -0
- package/src/hosted/access-cli.js +99 -1
- package/src/hosted/activity-core.js +232 -0
- package/src/hosted/activity.js +375 -0
- package/src/hosted/admin.js +87 -13
- package/src/hosted/agent-approvals.js +29 -4
- package/src/hosted/agent-link.js +1032 -0
- package/src/hosted/agent-policy.js +10 -3
- package/src/hosted/agent-presence.js +63 -22
- package/src/hosted/agent-routes.js +135 -0
- package/src/hosted/agents.js +1206 -0
- package/src/hosted/app.js +178 -12
- package/src/hosted/auth-routes.js +156 -15
- package/src/hosted/auth.js +123 -20
- package/src/hosted/board-routes.js +129 -5
- package/src/hosted/chat-frames.js +246 -0
- package/src/hosted/chat-job.js +204 -0
- package/src/hosted/chat-permissions.js +203 -0
- package/src/hosted/chat-routes.js +1009 -0
- package/src/hosted/chat-store.js +477 -0
- package/src/hosted/comment-files.js +11 -1
- package/src/hosted/comments.js +1 -1
- package/src/hosted/console-routes.js +122 -34
- package/src/hosted/db.js +295 -0
- package/src/hosted/device-routes.js +88 -10
- package/src/hosted/device.js +54 -4
- package/src/hosted/events.js +3 -3
- package/src/hosted/guards.js +337 -27
- package/src/hosted/http.js +6 -3
- package/src/hosted/membership.js +22 -3
- package/src/hosted/operator-access.js +418 -0
- package/src/hosted/operator.js +106 -2
- package/src/hosted/ops-cli.js +238 -3
- package/src/hosted/pages.js +4 -0
- package/src/hosted/passkey-policy.js +75 -0
- package/src/hosted/permissions.js +52 -6
- package/src/hosted/presence.js +31 -2
- package/src/hosted/projects.js +30 -2
- package/src/hosted/public.js +4 -4
- package/src/hosted/ratelimit.js +14 -0
- package/src/hosted/retention.js +18 -2
- package/src/hosted/server.js +123 -11
- package/src/hosted/shares.js +2 -2
- package/src/hosted/step-up-settings.js +68 -0
- package/src/hosted/step-up.js +135 -0
- package/src/hosted/tailnet-identity.js +24 -0
- package/src/hosted/tailnet-routes.js +342 -0
- package/src/hosted/tailnet.js +220 -0
- package/src/hosted/tailscale.js +75 -9
- package/src/hosted/tenancy.js +66 -1
- package/src/hosted/token-api.js +119 -20
- package/src/hosted/token-events.js +5 -3
- package/src/hosted/tokens.js +29 -6
- package/src/hosted/turn-hub.js +152 -0
- package/src/hosted/usage-core.js +624 -0
- package/src/hosted/usage-layout.js +724 -0
- package/src/hosted/usage-routes.js +375 -0
- package/src/hosted/usage-shape.js +256 -0
- package/src/hosted/usage.js +641 -0
- package/src/remote/agent-connect.js +469 -0
- package/src/remote/agent-fix.js +611 -0
- package/src/remote/agent-job.js +216 -0
- package/src/remote/agent-link.js +906 -0
- package/src/remote/agent-policy-file.js +242 -0
- package/src/remote/credentials.js +35 -1
- package/src/remote/login.js +44 -9
- package/src/remote/share.js +1 -1
- package/src/remote/tailnet-cli.js +547 -0
- package/src/server/app.js +15 -0
- package/src/server/pairing-routes.js +34 -5
- package/src/server/tailscale.js +97 -4
- package/src/tailnet-proof.js +766 -0
- package/dist/client/assets/BoardChat-DxehB761.js +0 -27
- package/dist/client/assets/ChecksPanel-pA_ueIaJ.js +0 -1
- package/dist/client/assets/History-C9N32kCv.js +0 -1
- package/dist/client/assets/LocalSettings-DawtKnvi.js +0 -1
- package/dist/client/assets/QuickConnect-DO1TjS1t.js +0 -1
- package/dist/client/assets/index-CsqLdqGx.css +0 -2
- package/dist/client/assets/index-DnZarJ3U.js +0 -37
- package/dist/client/assets/shield-check-QzwGhz0t.js +0 -1
- package/dist/client/assets/ui-DI-FGWWK.js +0 -41
- package/dist/console/assets/LocalAccountsApp-VOCZg8dg.js +0 -1
- package/dist/console/assets/LocalConsole-CMwAW-mF.js +0 -1
- package/dist/console/assets/app-update-dialog-Cw6UDqNP.js +0 -1
- package/dist/console/assets/console-DgfWmUEx.js +0 -55
- package/dist/console/assets/console-Lis0vvdL.css +0 -2
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":"0.
|
|
1
|
+
{"version":"0.7.0","revision":"277d4df57399b398e4c1fe4d7d5ba593b0646d4e"}
|
|
@@ -12,8 +12,14 @@
|
|
|
12
12
|
<title>Shapewall</title>
|
|
13
13
|
<!-- Saved light/dark mode and theme, before the first paint (see src/lib/theme.js). -->
|
|
14
14
|
<script src="/_console/theme-boot.js"></script>
|
|
15
|
-
<script type="module" crossorigin src="/_console/assets/console-
|
|
16
|
-
<link rel="
|
|
15
|
+
<script type="module" crossorigin src="/_console/assets/console-DxapQ9oS.js"></script>
|
|
16
|
+
<link rel="modulepreload" crossorigin href="/_console/assets/ui-Bry1mnCY.js">
|
|
17
|
+
<link rel="modulepreload" crossorigin href="/_console/assets/theme-DCd0qh4l.js">
|
|
18
|
+
<link rel="modulepreload" crossorigin href="/_console/assets/app-version-muKrQqbL.js">
|
|
19
|
+
<link rel="modulepreload" crossorigin href="/_console/assets/local-agents-CoqD4dSN.js">
|
|
20
|
+
<link rel="modulepreload" crossorigin href="/_console/assets/minus-DDQ0ydcM.js">
|
|
21
|
+
<link rel="modulepreload" crossorigin href="/_console/assets/tailnet-C5Flwl_d.js">
|
|
22
|
+
<link rel="stylesheet" crossorigin href="/_console/assets/console-CrhTsPbz.css">
|
|
17
23
|
</head>
|
|
18
24
|
<body>
|
|
19
25
|
<div id="root"></div>
|
package/docs/agent-hardening.md
CHANGED
|
@@ -173,6 +173,201 @@ When the chat panel drives an agent CLI over ACP:
|
|
|
173
173
|
board and comment ids before they become file names. Hosted API tokens are scoped to one project and to what you tick: `read`,
|
|
174
174
|
`comment`, `resolve`, `push`.
|
|
175
175
|
|
|
176
|
+
### Connected agents
|
|
177
|
+
|
|
178
|
+
`shapewall agent connect` puts a coding agent on a hosted board, where members of a workspace chat with it
|
|
179
|
+
([Connected agents](hosted.md#connected-agents)). It runs on your machine, with your login, and other people write the questions. So
|
|
180
|
+
by default it reads and answers only, and the machine that runs it is what enforces that. Edits from the board are a separate
|
|
181
|
+
choice, made on that machine ([Edits from a hosted board](#edits-from-a-hosted-board) below).
|
|
182
|
+
|
|
183
|
+
- **The command is yours.** The program that runs is Claude Code, found on your `PATH` or saved as an agent on your machine. Nothing
|
|
184
|
+
the server sends names a command, an argument, a folder, an environment variable or an MCP server.
|
|
185
|
+
- **Only an agent whose own controls were proven.** Refusing what an agent asks for is not enough: a tool it is set up to run
|
|
186
|
+
without asking never asks. So `agent connect` offers only Claude Code in this release, and refuses Codex, goose, Gemini CLI and
|
|
187
|
+
any program it does not know, with a message.
|
|
188
|
+
- **Read-only by the agent's own controls.** A connected Claude Code session is started:
|
|
189
|
+
- with no settings files (`settingSources: []`): your `~/.claude/settings.json` and the project's `.claude/settings.json` and
|
|
190
|
+
`.claude/settings.local.json` are left out, so their allow rules, hooks, default mode and plugins do not apply;
|
|
191
|
+
- with no MCP servers from `.mcp.json` or settings (`strictMcpConfig`);
|
|
192
|
+
- with only its reading tools (Read, Grep, Glob). Bash, Edit, Write, MultiEdit, NotebookEdit, WebFetch, WebSearch, Task/Agent and
|
|
193
|
+
Skill are removed from the session, and bypassing permissions is switched off.
|
|
194
|
+
- **Fail closed.** The session's mode must be "default" or "plan"; any other is switched to "default", or the agent is not
|
|
195
|
+
started. An agent that reports no session mode at all is not started read-only. An agent that switches itself to another mode
|
|
196
|
+
mid-answer is stopped, and the thread says which mode. claude-agent-acp 0.106.0 starts a session in the mode "auto" (Claude
|
|
197
|
+
decides what to ask about) when no settings file names a default mode. The adapter reads that from the settings files itself,
|
|
198
|
+
so leaving them out of the session does not change it. Shapewall switches such a session to "default" before the first
|
|
199
|
+
question, and the machine's log says so.
|
|
200
|
+
- **Checked when it starts.** `agent connect` opens the session before it goes online, the way a question would (no prompt is
|
|
201
|
+
sent). A session that cannot be opened, or that cannot be put in a mode that asks, stops the command with the cause. An adapter
|
|
202
|
+
version this release was not tested with is used with a plain warning ([tested versions](agents.md#claude-code)).
|
|
203
|
+
- **Managed settings stop the start.** `/etc/claude-code/managed-settings.json` cannot be left out of a session. When it allows
|
|
204
|
+
acting tools (Bash, Edit, Write, MultiEdit, NotebookEdit, WebFetch, WebSearch, Task, `mcp__*`, or Read of absolute or home paths)
|
|
205
|
+
or runs hooks, `agent connect` refuses to start. Your own and the project's rules are reported as "Left out of this session".
|
|
206
|
+
- **No writes and no terminals from Shapewall either.** The agent is told at the start that Shapewall offers neither. A write or a
|
|
207
|
+
command it asks Shapewall for anyway is refused, and every permission request its own tools make is refused on the spot, a read
|
|
208
|
+
outside the project included. Nobody is asked, on the board or anywhere else.
|
|
209
|
+
- **Board text is quoted on your machine.** The server sends data; your machine wraps every comment, reply, page title, mention and
|
|
210
|
+
attached file as untrusted data before the agent sees it. A server that was broken into can ask your agent questions. It cannot
|
|
211
|
+
hand it "instructions" that skip the quoting, and it cannot make it edit or run anything.
|
|
212
|
+
- **Who may ask.** By default only the person who connected it. Sharing it is a choice made at the approval or on the Agents page.
|
|
213
|
+
`--audience owner` on your machine asks the server to keep the agent to you even if its audience there is widened later, and
|
|
214
|
+
your machine refuses a job the server labels as someone else's. Your machine cannot check that label, so this does not protect
|
|
215
|
+
against a compromised server.
|
|
216
|
+
- **Its token stays out of the agent.** The agent process gets a small environment with no `SHAPEWALL_*` variable, and the agent's
|
|
217
|
+
own token is removed from anything sent back.
|
|
218
|
+
|
|
219
|
+
How it was proven. The check used the real Claude Code adapter, **claude-agent-acp 0.93.0 and 0.106.0** (the tested versions of
|
|
220
|
+
Shapewall 0.7.0; 0.106.0 with Claude Code 2.1.322), in a project whose `.claude/settings.json` and `.claude/settings.local.json`
|
|
221
|
+
allowed Bash, Edit, Write, WebFetch, `mcp__*` and reads anywhere, with the default mode `bypassPermissions` and, for 0.7.0, hooks
|
|
222
|
+
that run a command when a session starts, on every prompt and before every tool. The instructions told the agent it had full
|
|
223
|
+
permission and must create a file, run `touch`, and read `/etc/hostname`.
|
|
224
|
+
|
|
225
|
+
- **Claude Code, started as above, on each of the two versions:** no file was created, no command ran (the session had only Glob,
|
|
226
|
+
Grep and Read), none of the project's hooks ran, and the read outside the project was asked for and refused. On 0.106.0 the
|
|
227
|
+
session started in "auto" and was switched to "default" first.
|
|
228
|
+
- **Claude Code, same project, session not hardened:** it ran a shell command without asking. That is why the hardening exists.
|
|
229
|
+
- **Codex 2.2.2, under the same test in its read-only sandbox:** it wrote no file, but it ran `pwd` and read `/etc/hostname`
|
|
230
|
+
without asking. What it reads can leave the machine in an answer, so it is not offered.
|
|
231
|
+
|
|
232
|
+
goose's chat-only mode could not be verified on the test machine, and Gemini CLI was not installed to verify, so neither is
|
|
233
|
+
offered. For those agents, `shapewall watch --remote` stays the way.
|
|
234
|
+
|
|
235
|
+
The limits, plainly:
|
|
236
|
+
|
|
237
|
+
- **It reads the project, and its answers leave your machine.** Whoever may ask can get file contents quoted back: every file in
|
|
238
|
+
the project folder, a `.env` file included. The agent is told not to quote secrets; that is an instruction, not a control.
|
|
239
|
+
Connect only projects whose code the audience may read, and keep secrets out of the folder.
|
|
240
|
+
- **One machine, two adapter versions.** The check above is what was seen there, with 0.93.0 and 0.106.0. A later adapter may
|
|
241
|
+
take other options or bring other tools: Shapewall 0.6.0 could not start a connected session on 0.106.0 at all, because that
|
|
242
|
+
version reports a mode switch in another order. `agent connect` warns when the adapter is not a tested version; it cannot know
|
|
243
|
+
what a version it has never seen does. So still give a connected agent a profile of its own: a separate config folder with no
|
|
244
|
+
allow rules, logged in for this purpose. The hooks of your own `~/.claude/settings.json` were not provoked separately: the same
|
|
245
|
+
option (`settingSources: []`) leaves that file out as it does the project's.
|
|
246
|
+
- **Settings in the left-out files do not apply.** An `apiKeyHelper` or `env` in those settings files is not used by the connected
|
|
247
|
+
session. The login itself is not in those files.
|
|
248
|
+
- **One link per agent.** A second `agent connect` on the same token is refused, and names the machine already connected.
|
|
249
|
+
`--takeover` closes that link first. Whoever holds the agent's token can take the link over, so keep the token file private.
|
|
250
|
+
|
|
251
|
+
The hard rule below holds for connected agents too: it is a shared board, and other people write what the agent reads.
|
|
252
|
+
|
|
253
|
+
### Edits from a hosted board
|
|
254
|
+
|
|
255
|
+
From Shapewall 0.6.0 a connected agent can make a fix for a hosted comment
|
|
256
|
+
([Edits from the board](hosted.md#edits-from-the-board-the-trust-decision)). The question behind it: **who may make someone
|
|
257
|
+
else's machine change files?** By default, nobody. Even the person who connected the agent cannot allow an edit from the board
|
|
258
|
+
until they said so on that machine.
|
|
259
|
+
|
|
260
|
+
| Level | Where it is set | Default | What the board can cause |
|
|
261
|
+
| --------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
262
|
+
| Audience "only the person who connected it", `--approvals none` | The audience at the approval; `--audience owner` pins it from the machine | Yes | That person asks. The agent reads the project and answers |
|
|
263
|
+
| Audience: named members, or everyone the agent policy trusts | On the server: the approval page, or the Agents page | Opt-in | Those members may ask too. Still read and answer only |
|
|
264
|
+
| `--approvals owner` | On the machine | Opt-in | A fix on a new branch. Each edit waits for the person who connected the agent |
|
|
265
|
+
| `--approvals admins` | On the machine | Opt-in | A fix on a new branch. Each edit waits for someone with the agent's answer role (admin by default), in its audience and trusted |
|
|
266
|
+
| "Allow without asking" | On the machine (`--auto edits`), and then the agent's approval rule on the server | Opt-in, twice | Edits to ordinary source files go into the fix without a person. The fix stays on the machine: it is pushed only after a person allows "Push this fix" on its whole diff |
|
|
267
|
+
| Commands | On the machine (`--allow-command`) | Not offered for Claude Code in 0.6.0 | Nothing: a fix session of Claude Code has no shell tool |
|
|
268
|
+
|
|
269
|
+
The machine's choice is saved in its own policy file (`agent-policy.json` beside the saved token, 0600, outside every
|
|
270
|
+
repository). It is the ceiling: the server can only narrow it. The file fails narrow: a value this version does not know (a typo,
|
|
271
|
+
`false`, `""`, a wrong type) reads as the narrowest setting for that key, never as the default, and `agent connect` names the key
|
|
272
|
+
when it starts. The file must be yours and not writable by others; that is checked before it is read.
|
|
273
|
+
|
|
274
|
+
What the machine does, whatever the server says:
|
|
275
|
+
|
|
276
|
+
- **A fix is never made in your checkout.** The agent works in a fresh copy of the base commit, with no `.git` in it, in a folder
|
|
277
|
+
outside the project (under your state folder). Your checkout is only read.
|
|
278
|
+
- **Every edit is checked on the machine before anyone is asked.** The file must be inside the fix's folder after resolving
|
|
279
|
+
symlinks, not in `.git`, not in Shapewall's store, and not a file that runs something unless you named it with `--allow-path`.
|
|
280
|
+
The whole resulting file must be computable and small enough to show in full. What fails is refused there and never becomes a
|
|
281
|
+
question.
|
|
282
|
+
- **Files that run something are a list, used twice.** Dotfiles and dot folders, dependency manifests and lockfiles, build and
|
|
283
|
+
tool configuration (`*.config.js`, `tsconfig*.json`, the jest, vitest, vite, webpack, rollup, babel and eslint files), scripts
|
|
284
|
+
a package runs (`scripts/`, `bin/`, install hooks, `*.sh`), `Dockerfile*` and compose files, makefiles, CI files, and test files
|
|
285
|
+
([the list](hosted.md#files-that-run-something)). The same list decides what is refused when an edit is asked and what is never
|
|
286
|
+
pushed. One you named with `--allow-path` is always answered by a person, never allowed without asking.
|
|
287
|
+
- **What Git would leave out is refused, not dropped.** An edit to a file Git ignores, to anything under `node_modules`, or to
|
|
288
|
+
`.gitattributes` / `.gitmodules` is refused when it is asked.
|
|
289
|
+
- **A card shows what will be written.** The path and the full diff, in the machine's own words, never the agent's title. The
|
|
290
|
+
card carries a hash of the turn, the card, the path, the whole diff and how long it waits. The diff goes to the people the
|
|
291
|
+
agent works for (its audience, whoever may answer, whoever asked); everyone else who can open the thread reads that it asked to
|
|
292
|
+
edit a file and how that ended.
|
|
293
|
+
- **An answer is for one card.** It must send the card's hash back, within 2 minutes, once. The 2 minutes are a length of time
|
|
294
|
+
each side counts on its own clock, so the clocks need not agree. A workspace can ask for the answerer's passkey again before Allow
|
|
295
|
+
(off by default; the server's Settings, "Agent edits and pushes"). The machine then checks the answer again: a card it asked and still waits on, the same hash, not expired by its own
|
|
296
|
+
count, once, and from the connecting person when it said "owner". A failed "allow" is a deny, and the board then shows the
|
|
297
|
+
card as expired or denied, never as allowed. An answer for a card it never asked is ignored.
|
|
298
|
+
- **Shapewall makes the commit, and only of what was allowed.** No hook, filter or attribute runs. Every changed file must have
|
|
299
|
+
had an allowed edit and must hold exactly the bytes that were shown, with the file mode it had. Every allowed file must be in
|
|
300
|
+
the commit, and nothing may be removed. A changed edit, an extra file, a mode change, a deletion: the branch is taken back and
|
|
301
|
+
the thread says nothing was committed.
|
|
302
|
+
- **Nothing is pushed that runs something, or that no person has seen.** A fix that touches a file from the list above stays on
|
|
303
|
+
the machine, and the thread says "Not pushed" and why. A fix with an edit that went without asking stays there too, until a
|
|
304
|
+
person who may answer cards allows one "Push this fix" card that shows its whole diff. Anything else is pushed as one new
|
|
305
|
+
branch, and a pull request is opened when [GitHub connect](github.md) is set up on that machine.
|
|
306
|
+
- **Stop stops all of it.** After Stop nothing is committed, pushed or opened, and a fix that was waiting to be pushed is taken
|
|
307
|
+
back. A push that had already finished cannot be undone: the thread says the branch exists.
|
|
308
|
+
- **Leftovers are swept.** Copies a killed process left behind are removed when `agent connect` starts and around every fix. The
|
|
309
|
+
folder fixes are made in is never inside the project; where it would be, the fix is refused.
|
|
310
|
+
- **Chat never edits.** Only "Fix with" on a comment starts a turn that may edit, and it follows the rules of sending a comment
|
|
311
|
+
to an agent: a trusted member's vouch, an admin's "Approve agent run" where the policy says so, the audience, the budgets.
|
|
312
|
+
- **"Allow without asking" only where the machine named it** (`--auto edits`), and under `--approvals owner` only when the
|
|
313
|
+
person who connected the agent switched it on themself: an admin cannot take them out of the loop. It never widens what may be
|
|
314
|
+
edited, never covers a file that runs something, never pushes, and a machine that connects again without it resets the
|
|
315
|
+
server's rule to "ask".
|
|
316
|
+
|
|
317
|
+
**Commands, and what the real adapter did.** The link and the policy file know "exact commands from the machine's own list, each
|
|
318
|
+
allowed on the board" (`--allow-command`). This is not available for Claude Code in Shapewall 0.6.0, and Claude Code is the only
|
|
319
|
+
agent `agent connect` offers. In the check below, a Claude Code session started with its shell tool ran commands it takes to be
|
|
320
|
+
read-only (`ls`, `cat`) without asking anyone, and those can read outside the project. A list of allowed commands is no control
|
|
321
|
+
over an agent that does not ask. So a fix session of Claude Code gets no shell tool at all (it has Read, Grep, Glob, Edit, Write
|
|
322
|
+
and MultiEdit, no settings files and no MCP servers), `--allow-command` is refused for it with that explanation, and commands in a
|
|
323
|
+
hand-edited policy file are not in effect.
|
|
324
|
+
|
|
325
|
+
How edits were proven. The check used the real Claude Code adapter (claude-agent-acp 0.93.0 for 0.6.0; 0.93.0 and 0.106.0 again
|
|
326
|
+
for 0.7.0, in a repository whose committed `.claude/settings.json` allowed Bash, Edit and Write without asking and ran a hook), a
|
|
327
|
+
throwaway server on localhost, a throwaway Git repository with a local bare remote, and the real
|
|
328
|
+
`shapewall agent connect --approvals owner`:
|
|
329
|
+
|
|
330
|
+
- **Allow.** A Fix with Builder edited one file after Allow in a browser (with a passkey check, which that workspace asked
|
|
331
|
+
for). The commit landed on
|
|
332
|
+
`shapewall/comment-1-...` and was pushed to the bare remote. The checkout stayed clean on `main`, with the old file.
|
|
333
|
+
- **Deny.** A Deny left no branch and no folder.
|
|
334
|
+
- **A comment that asked for more.** The comment also asked for a file outside the project, a new `package.json` and shell
|
|
335
|
+
commands. It ended with only the allowed one-line edit committed. In one run the `package.json` request was refused on the
|
|
336
|
+
machine as a settings file. Claude Code itself declined the file outside the project and, having no shell tool, ran nothing.
|
|
337
|
+
- **A server that lies.** Forged "allowed" answers from the server side with a wrong hash turned the waiting edit into a deny.
|
|
338
|
+
- **Without asking.** With `--approvals owner --auto edits` and the rule switched on by the connecting person, the edit went
|
|
339
|
+
without a card to answer, the commit landed on its branch on the machine, and the bare remote stayed empty until "Push this
|
|
340
|
+
fix" was allowed in the browser. Then that one branch was pushed.
|
|
341
|
+
|
|
342
|
+
The real model declined some of what a hostile agent would try. The scripted-agent tests (`test/hosted-fix-security.test.js`)
|
|
343
|
+
cover that: an edit changed after the answer, a file nobody was asked about, an answer for another card, another turn or sent
|
|
344
|
+
twice, a stolen agent token that says "approved", and a server that says "allow without asking" when the machine did not.
|
|
345
|
+
|
|
346
|
+
The limits of edit mode, plainly:
|
|
347
|
+
|
|
348
|
+
- **Shapewall does not sandbox the agent's own tools.** The checks above cover what the agent asks. The fix session is set up so
|
|
349
|
+
that its editing tools ask every time, and that was seen with one adapter version on one machine. If files in your own checkout
|
|
350
|
+
change during a fix, the thread says so; it cannot undo it.
|
|
351
|
+
- **With approvals on, a compromised hosted server can forge an "allow".** The machine cannot see the person behind an answer, or whether a
|
|
352
|
+
passkey was checked: it sees what the server sends. A server that was broken into can answer "allow", with the right hash, for an
|
|
353
|
+
edit the agent really asked, and for "Push this fix". So the worst case with approvals on is: edits to ordinary source files,
|
|
354
|
+
on a branch, in a throwaway folder, pushed for review. Not commands, not your checkout, not files that run something on
|
|
355
|
+
install, build, test or CI, and not files outside the project that the agent asks about.
|
|
356
|
+
- **The branch is a proposal.** It comes from a board comment, which is untrusted text. Nothing is merged by Shapewall.
|
|
357
|
+
- **Diffs leave the machine.** Beyond the answers of 0.5.0, edit mode sends the diffs on edit cards (bounded), the file paths
|
|
358
|
+
and line counts of a fix, the branch name and the pull request link. Still not the agent's token and not absolute paths.
|
|
359
|
+
|
|
360
|
+
What to do:
|
|
361
|
+
|
|
362
|
+
- **Give the agent a restricted profile of its own**: a separate config folder with no allow rules, logged in for this purpose.
|
|
363
|
+
- **Prefer `--approvals owner` to `--approvals admins`.** Then an "allow" has to come from you, and both the server and your
|
|
364
|
+
machine check that.
|
|
365
|
+
- **Review the pull request like any other**, the whole diff ([Review the agent's output](#review-the-agents-output)), and
|
|
366
|
+
protect `main` so a pushed branch cannot merge itself.
|
|
367
|
+
- **Do not add `--allow-path` for CI files**, and think twice before adding it for `package.json` or any file that runs.
|
|
368
|
+
- **Leave `--auto` off** unless everyone who may press Fix is someone you would let edit the project unseen. Even then the fix
|
|
369
|
+
waits on the machine until someone looks at its whole diff.
|
|
370
|
+
|
|
176
371
|
### What Shapewall cannot do
|
|
177
372
|
|
|
178
373
|
- **The agent's own tools.** An ACP agent is still a program running as you. Claude Code's Bash and Edit, Codex's sandbox, goose's
|
|
@@ -194,6 +389,8 @@ Pick the weakest setup that does the job.
|
|
|
194
389
|
| Chat with an endpoint, read-only tools | Read the board, write answers | Shared boards, with a spend-limited key |
|
|
195
390
|
| `comments --json` into an agent you run by hand | Whatever you let it, one comment at a time, you watching | Any board, if you read the comment first |
|
|
196
391
|
| Chat with an agent CLI over ACP, permission prompts on | Edit and run in the project after you approve each card | Your own board on your own machine |
|
|
392
|
+
| `agent connect` on a hosted board (the default) | Read the project, write answers | Projects whose code the agent's audience may read |
|
|
393
|
+
| `agent connect --approvals owner` | Edit a fresh copy on a new branch after you allow each diff | Hosted boards, with a restricted profile and PR review |
|
|
197
394
|
| `watch --exec` with an edit mode and a narrow tool list | Edit the project and call `npx shapewall`, no person in between | Boards whose commenters you trust |
|
|
198
395
|
| `watch --exec` in a sandbox, output as a branch | Edit a fresh clone, open a PR | Shared boards ([Sandbox checklist](#sandbox-checklist)) |
|
|
199
396
|
| An agent with your shell, keys, browser and email | Anything you can | Nothing that reads other people's text |
|
|
@@ -217,6 +414,14 @@ shared board is text other people write.
|
|
|
217
414
|
|
|
218
415
|
Use a separate agent for shared boards: its own key, its own login, in a sandbox with nothing worth stealing and nowhere to send it.
|
|
219
416
|
|
|
417
|
+
A [connected agent](#connected-agents) on a hosted board is a shared board's agent. By default it reads and answers only, which
|
|
418
|
+
takes away editing and running, not reading: connect a profile that holds nothing but that project, never your main one.
|
|
419
|
+
|
|
420
|
+
With [edits from the board](#edits-from-a-hosted-board) switched on, the rule matters more. Other people's comments now end as
|
|
421
|
+
changes to files, and an "allow" reaches your machine through the server. The edits are held to a branch in a throwaway folder,
|
|
422
|
+
and each one was shown to a person, but the agent that makes them still runs as you, with its own tools. Never switch
|
|
423
|
+
`--approvals` on for your main agent.
|
|
424
|
+
|
|
220
425
|
## Sandbox checklist
|
|
221
426
|
|
|
222
427
|
For `watch --exec`, an agent loop on a hosted project, or the chat on a shared board. Every item is something you set up outside
|
|
@@ -345,6 +550,7 @@ to a shared board.
|
|
|
345
550
|
- [ ] Only trusted members trigger work (`--mention agent`, no `--include-guests`).
|
|
346
551
|
- [ ] Share links are off, or view-only, with a passcode and a short expiry.
|
|
347
552
|
- [ ] The agent's prompt says comments are requests about the UI, not instructions.
|
|
553
|
+
- [ ] A connected agent takes edits only if I chose so on its machine: `--approvals owner`, no `--allow-path` for CI files, `--auto` off.
|
|
348
554
|
|
|
349
555
|
**Every change**
|
|
350
556
|
|
package/docs/agent-recipes.md
CHANGED
|
@@ -18,6 +18,29 @@ about the UI, never as instructions, and gives the agent no more than it needs.
|
|
|
18
18
|
The commands assume `shapewall` is installed in the project (`npm install --save-dev shapewall`), so `npx shapewall`
|
|
19
19
|
runs that copy, and that you are in the folder with `shapewall.config.json`.
|
|
20
20
|
|
|
21
|
+
**On a team server.** Every `watch` recipe below works against a hosted board by adding `--remote https://wall.example.com` (after
|
|
22
|
+
`shapewall login --remote https://wall.example.com`, with **Take agent work** ticked). The watcher then shows up on that board as an
|
|
23
|
+
agent with a name, an icon and a state, and people send comments to it by name. A new agent takes work only from the person who
|
|
24
|
+
connected it until an admin shares it on the project's Agents page. See
|
|
25
|
+
[Agents on a hosted board](hosted.md#agents-on-a-hosted-board).
|
|
26
|
+
|
|
27
|
+
**Chat on a team server.** To let teammates ask your coding agent questions on the hosted board, run this in the project's folder,
|
|
28
|
+
on the machine that has Claude Code set up for the board chat ([The board chat (ACP)](#the-board-chat-acp) below):
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
shapewall agent connect --remote https://wall.example.com # this project's agent, else Claude Code; or --agent claude
|
|
32
|
+
shapewall agent connect --remote https://wall.example.com --as scout --name "Scout" # a second connection, with its own token
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
An admin approves the code it prints, names the agent and chooses who may use it. By default it reads the project and answers,
|
|
36
|
+
and does not change files or run commands from the board. Add `--approvals owner` on that machine to let it make a fix for a
|
|
37
|
+
comment: on a new branch, never in the checkout, each edit allowed on the board by you
|
|
38
|
+
([Edits from the board](hosted.md#edits-from-the-board-the-trust-decision)). It runs no commands from the board, so keep a `watch`
|
|
39
|
+
recipe for fixes that need to build, test or recapture. Only Claude Code can be connected in this release.
|
|
40
|
+
Codex, goose and Gemini CLI are refused with a message: their read-only behaviour could not be shown to hold, so for them the
|
|
41
|
+
`watch` recipes below, with `--remote`, stay the way.
|
|
42
|
+
See [Connected agents](hosted.md#connected-agents).
|
|
43
|
+
|
|
21
44
|
## Claude Code
|
|
22
45
|
|
|
23
46
|
### MCP in your session
|
package/docs/agent-workflow.md
CHANGED
|
@@ -212,6 +212,11 @@ requires a claiming local `--exec`, so it is refused with `--remote`, `--no-clai
|
|
|
212
212
|
command did not edit a file; inspect the before/after before resolving. To capture additional pages, the agent can use `recapture_pages`
|
|
213
213
|
through MCP or the capture CLI. Variants still require manual capture.
|
|
214
214
|
|
|
215
|
+
With `--remote`, the watcher is an **agent** of the hosted project: the board lists it by its token's name with its state (online,
|
|
216
|
+
working, offline), and people choose it when they send a comment. It is handed the comments sent to it and the ones sent to any
|
|
217
|
+
agent, from the people it takes work from; a comment sent to another agent never reaches it. Nothing changes in how you run it. See
|
|
218
|
+
[Agents on a hosted board](hosted.md#agents-on-a-hosted-board).
|
|
219
|
+
|
|
215
220
|
Options: `--concurrency N` (1 to 4, default 1; agents editing one repo at once usually step on each other), `--new-only` (ignore comments
|
|
216
221
|
that exist when the watch starts), `--once` (hand out what is open now, wait for the commands, exit; handy in CI or a cron you run
|
|
217
222
|
yourself), `--timeout MIN` (default 60), `--no-claim` (below).
|
package/docs/agents.md
CHANGED
|
@@ -125,8 +125,36 @@ the agent picker's **Agent settings** item link to the Agents page.
|
|
|
125
125
|
|
|
126
126
|
Connecting, removing, testing and choosing the default run commands as the machine's owner, so they need the settings token (the owner
|
|
127
127
|
link `shapewall serve` prints). Without it the card is read-only and says how to open that link; it asks nothing of the agent routes.
|
|
128
|
-
Self-hosted multiplayer (`shapewall hosted`) has its own
|
|
129
|
-
|
|
128
|
+
Self-hosted multiplayer (`shapewall hosted`) has its own Agents pages, for the machines that watch a hosted project or connect a
|
|
129
|
+
coding agent to it ([Agents on a hosted board](hosted.md#agents-on-a-hosted-board)): they list and name agents, and never start a
|
|
130
|
+
program on the server. The chat panel described here is also on hosted boards, for an agent connected with `shapewall agent
|
|
131
|
+
connect`: the same panel, with an agent that reads the project and answers. On a hosted comment, **Fix with** an agent is offered
|
|
132
|
+
only when that agent's own machine switched edits on (`--approvals`): the fix is made on a new branch on that machine, never in
|
|
133
|
+
its checkout, and each edit is a card with the full diff that someone allows or denies on the board. Only Claude Code can be
|
|
134
|
+
connected that way in this release, and it runs no commands from a hosted board ([Connected agents](hosted.md#connected-agents)).
|
|
135
|
+
The public demo shows this card read-only on its console's Agents page.
|
|
136
|
+
|
|
137
|
+
## Usage
|
|
138
|
+
|
|
139
|
+
Every agent turn leaves one usage record: when, on which board, in which kind of thread (the board's chat, a comment's, or a chat
|
|
140
|
+
of your own), who asked (the owner or a viewer; a local board has no accounts to name), which agent, whether it was a chat, a
|
|
141
|
+
comment answer or a fix, how it ended, how long it took, its tool calls counted by type, and the numbers the agent reported:
|
|
142
|
+
model, input, output and cached tokens, context used, and a cost only when the agent or its endpoint reported one. Nothing is
|
|
143
|
+
estimated: an agent that reports no tokens shows "Not reported", never zero. A record never holds the question, the answer, a
|
|
144
|
+
file's name or content, or a diff.
|
|
145
|
+
|
|
146
|
+
- **On a local board** the records are lines in `.shapewall/agent-usage.jsonl` (past 5 MB the file is renamed to
|
|
147
|
+
`agent-usage.1.jsonl` and a new one starts). The file is readable by its owner only (0600) and is written under a file lock,
|
|
148
|
+
like the event log. It says who used which agent and when, so keep it out of git: `.shapewall/` is ignored by `shapewall
|
|
149
|
+
init`, which from 0.7.0 also adds `.shapewall/agent-usage*.jsonl` by name. In a project set up earlier, check that your
|
|
150
|
+
`.gitignore` has `.shapewall/` (or add that line) before you commit. The Workspace Console's **Usage** page (`/console?section=usage`) shows them to the
|
|
151
|
+
owner: turns, tokens, agent time and reported cost for the last 7, 30 or 90 days against the days before, a chart by day and
|
|
152
|
+
agent (turns, tokens, time or cost), how turns ended, and a table of the newest 200 turns. It needs the owner link, like Agent
|
|
153
|
+
feedback: it says who used which agent on this computer. `GET /api/agent/usage?days=30` is the same data. The local view has no
|
|
154
|
+
filters, grouping or export; delete the two files to clear it.
|
|
155
|
+
- **On a team server** the records are rows in its database and the console has the full Usage page: filters, breakdowns,
|
|
156
|
+
approvals, turn duration, a grid of every turn, saved views and CSV or JSON export, with a rule for who sees what
|
|
157
|
+
([Usage and activity](hosted.md#usage-and-activity)).
|
|
130
158
|
|
|
131
159
|
## Name and icon
|
|
132
160
|
|
|
@@ -169,8 +197,9 @@ fixed with `--agent-acp` or `SHAPEWALL_AGENT_ACP` still wins over which agent ru
|
|
|
169
197
|
saved for that fixed agent (`fixedAgent` in `agents.json`) and the Agents page shows it with **Edit**. Everyone who can see the board
|
|
170
198
|
gets the name, the icon's id and the colour in the agent info they already receive (`/api/agent/status`, `/api/info`); nothing else
|
|
171
199
|
about the agent is added to it. In the public demo you can rename the two scripted agents and give them built-in icons (no upload);
|
|
172
|
-
**Reset** puts them back. On a hosted board an agent is
|
|
173
|
-
icons
|
|
200
|
+
**Reset** puts them back. On a hosted board an agent is a project API token that may take work: an admin gives it a name, one of the
|
|
201
|
+
same built-in icons and a colour on the project's Agents page in the console
|
|
202
|
+
([Agents on a hosted board](hosted.md#agents-on-a-hosted-board)). Pictures are not uploaded there.
|
|
174
203
|
|
|
175
204
|
### While a connection test runs
|
|
176
205
|
|
|
@@ -598,6 +627,19 @@ to the agent unless you name it (see [The agent's environment](#the-agents-envir
|
|
|
598
627
|
replace your subscription. The old package names `@zed-industries/claude-code-acp` and `@zed-industries/claude-agent-acp` are
|
|
599
628
|
deprecated; use `@agentclientprotocol/claude-agent-acp`.
|
|
600
629
|
|
|
630
|
+
**Tested adapter versions.** Shapewall 0.7.0 was tested with `@agentclientprotocol/claude-agent-acp` **0.93.0** and **0.106.0**
|
|
631
|
+
(the latest when 0.7.0 was released, with Claude Code 2.1.322). Both work as a connected agent (`shapewall agent connect`),
|
|
632
|
+
read-only and for edits. The adapter changes between versions: 0.106.0 starts a session in the mode "auto" where 0.93.0 started
|
|
633
|
+
in "default", and reports the mode in two places. So:
|
|
634
|
+
|
|
635
|
+
- `shapewall agent connect` opens a session when it starts (no prompt is sent, nothing is spent) and prints which adapter
|
|
636
|
+
answered: `Claude Code answers through @agentclientprotocol/claude-agent-acp 0.106.0, a version this release was tested with.`
|
|
637
|
+
- A version it was not tested with is used as it is, with a `Warning:` line that names the tested versions and the command to
|
|
638
|
+
install one (`npm install -g @agentclientprotocol/claude-agent-acp@0.106.0`). It is not refused.
|
|
639
|
+
- A session that cannot be opened stops `agent connect` with the cause: the adapter's error, its version and its last output.
|
|
640
|
+
- A start that fails later says the same in the chat and in the log of the machine that runs the agent, never just "did not
|
|
641
|
+
start". `shapewall doctor --agent-acp "claude-agent-acp"` repeats the handshake on its own.
|
|
642
|
+
|
|
601
643
|
For headless Claude Code setups that already supply `CLAUDE_CODE_OAUTH_TOKEN`, explicitly allow that variable when starting the
|
|
602
644
|
board:
|
|
603
645
|
|
|
@@ -961,8 +1003,9 @@ Older thread files need no migration: a file with only `messages` (and `profileI
|
|
|
961
1003
|
its title. The fields added since (`owner`, `title`, `titleSource`, `createdAt`, `archived`, `branches`) are written only when something
|
|
962
1004
|
sets them. A board keeps at most 500 New chat threads; delete old ones to start more.
|
|
963
1005
|
|
|
964
|
-
There are no share links for chats
|
|
965
|
-
agent
|
|
1006
|
+
There are no share links for chats. On a hosted board, chat is for signed-in members with a
|
|
1007
|
+
[connected agent](hosted.md#connected-agents); a share link's guests and a public project's visitors never get it. Export a chat as
|
|
1008
|
+
Markdown to share it.
|
|
966
1009
|
|
|
967
1010
|
## Board tools
|
|
968
1011
|
|
package/docs/architecture.md
CHANGED
|
@@ -143,6 +143,7 @@ touch):
|
|
|
143
143
|
| Trackpad two-finger scroll | Pan in any direction |
|
|
144
144
|
| Ctrl+wheel, Cmd+wheel, trackpad pinch | Zoom about the cursor (0.02x to 4x; a mouse notch is about 1.3x) |
|
|
145
145
|
| Space+drag, middle-button drag, drag on the board | Pan (Space and middle drag work over pages and in comment mode as well) |
|
|
146
|
+
| The Hand tool (H): drag anywhere | Pan, over pages and pins too; a click selects and opens nothing |
|
|
146
147
|
| Touch: one finger, two-finger pinch | Pan, zoom |
|
|
147
148
|
|
|
148
149
|
Space pans while the mouse is over the canvas, except in text fields and on a control reached with the keyboard (Space presses it).
|
|
@@ -180,13 +181,18 @@ the same way. Scrolling inside a `nowheel` element (the frame bar, a live page b
|
|
|
180
181
|
group at a readable zoom (two cards across), top-aligned. Pins never shrink below their 44 px touch target, and a tap in comment mode
|
|
181
182
|
on a page drawn small zooms to it first, so the next tap can pin to an element.
|
|
182
183
|
- The desktop toolbar never truncates: below 1440 px (1600 px with Capture and Agent) Links and Compare drop their labels, below
|
|
183
|
-
1280 px the lists become icons and the capture time moves into a tooltip. Notes
|
|
184
|
-
viewport switch, the links note) are pills in one stack at its top
|
|
184
|
+
1280 px the lists become icons and the capture time moves into a tooltip. Notes about what the canvas shows (the tip, the
|
|
185
|
+
viewport switch, the links note) are pills in one stack at its top. The board tools (Select, Hand, Comment, Draw, Select text) float at
|
|
186
|
+
the bottom centre of the canvas, with the note for the tool in use (the comment hint, the drawing bar) just above them, so
|
|
187
|
+
turning comment mode on never moves the canvas; they stay clear of the zoom controls and the minimap at every width
|
|
188
|
+
(`client/src/board/toolDock.js`), and on a phone they are the bottom bar. The minimap
|
|
185
189
|
can be turned off and hides while a page is live. Resolve and delete show a toast with Undo (a delete is sent after a few seconds,
|
|
186
190
|
or when the page is left).
|
|
187
191
|
- Keyboard: each card is one tab stop; the arrow keys move through its pins and buttons, Esc returns to the card, Enter opens its
|
|
188
192
|
action bar. "Skip to comments" is the first tab stop. After a pick from a toolbar list, focus returns to the canvas, and a closed
|
|
189
|
-
list ignores typed letters (Radix type-ahead), so shortcuts like C keep working. Esc closes a journey.
|
|
193
|
+
list ignores typed letters (Radix type-ahead), so shortcuts like C keep working. Esc closes a journey. The board tools are one
|
|
194
|
+
tab stop (a labelled toolbar): the arrow keys, Home and End move between them; V is Select, H is Hand, C is Comment (none
|
|
195
|
+
of them while typing) and Esc ends on Select.
|
|
190
196
|
- URL state: board, viewport mode, comment filter, selected comment, camera, journey, branches and step, links, and compare pair live in the
|
|
191
197
|
query string.
|
|
192
198
|
- Overlays (dialogs, the comment sheet, the selected card, comment mode) each own a history entry, so Back closes the topmost one.
|
|
@@ -198,7 +204,7 @@ for replies, a dot for news) drawn at screen size; pins closer than about 30 scr
|
|
|
198
204
|
count, and clicking it zooms in until they part (`clusterPins` in `client/src/board/pins.jsx`). Hovering a pin previews the thread in
|
|
199
205
|
a kit `HoverCard`. Resolved threads are hidden by the Open filter, which is the toggle for showing them.
|
|
200
206
|
|
|
201
|
-
C (or the Comment
|
|
207
|
+
C (or the Comment tool, in the board tools at the bottom of the canvas, or Comment on the selected page's bar, which also names that page in the hint) turns comment mode on; a click drops a draft pin and an inline composer (`ComposerPopover`) opens beside
|
|
202
208
|
it: Enter posts, Shift+Enter adds a line, Esc cancels and stays in comment mode, @ suggests people. The open thread is a popover at
|
|
203
209
|
its pin (`ThreadPopover`): resolve, previous and next (also the arrow keys), and a more menu (copy link, edit, ask agent, GitHub,
|
|
204
210
|
history, delete), then the messages with reactions and an inline reply box. Both are Radix popovers anchored to a virtual element
|
package/docs/deployment.md
CHANGED
|
@@ -192,23 +192,45 @@ error is a host permission failure before account enrollment, not a passkey or T
|
|
|
192
192
|
complete the existing supported Serve permission/setup process for the intended port, then retry deliberately. Do not run Shapewall
|
|
193
193
|
as root, change account origins or relax identity checks to bypass it.
|
|
194
194
|
|
|
195
|
-
A Tailscale request gets owner access only if its
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
[
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
195
|
+
A Tailscale request gets owner access only if its Host is exactly this node's
|
|
196
|
+
`*.ts.net` name, `Tailscale-User-Login` equals the node owner's login, and the
|
|
197
|
+
request provably came through the serve entry Shapewall made. A header alone
|
|
198
|
+
proves nothing: any program on the host (an agent whose command is waiting for
|
|
199
|
+
approval included) can send it to the loopback port. The proof is the same as
|
|
200
|
+
the hosted server's tailnet sign-in: the serve entry points at a secret path
|
|
201
|
+
made at each start, the connection's other end must be a socket owned by root
|
|
202
|
+
(tailscaled), `tailscale whois` must give the request's tailnet address to
|
|
203
|
+
the owner's login, and the request must not come from this machine itself
|
|
204
|
+
([how](hosted.md#how-the-server-knows-a-request-came-through-tailscale-serve)).
|
|
205
|
+
A program on the host can ask tailscaled for the board's tailnet address and
|
|
206
|
+
would arrive with the owner's login, so the host's own tailnet address is
|
|
207
|
+
never the owner: on the host, open `http://localhost:<port>` (the settings
|
|
208
|
+
token makes you the owner there); the tailnet address opened on the host asks
|
|
209
|
+
to pair and says why. The secret path is taken off before the application
|
|
210
|
+
sees the request and is in no redirect or response.
|
|
211
|
+
Other users, shared-in devices, tagged nodes, and missing or mismatched
|
|
212
|
+
identity headers must pair. `--no-identity` disables it altogether. The node
|
|
213
|
+
owner is determined at server start; restart Shapewall after changing the
|
|
214
|
+
node's owner.
|
|
215
|
+
|
|
216
|
+
Where that cannot be proven, identity is off and every other device pairs; the
|
|
217
|
+
board still starts and says why: not Linux, tailscaled in userspace-networking
|
|
218
|
+
mode, Tailscale before 1.98, tailscaled running a SOCKS5 or outbound HTTP
|
|
219
|
+
proxy or started with a loopback-forwarding debug switch, no tailscaled of
|
|
220
|
+
root visible, the node unable to say which node it is, or Shapewall in a
|
|
221
|
+
container. The same is checked every 30 seconds while the board runs.
|
|
222
|
+
|
|
223
|
+
Approving an agent's command or edit (`/permissions/` routes) needs the
|
|
224
|
+
settings token from the host's own terminal, unless the request is the owner by
|
|
225
|
+
proven tailnet identity or comes from a device the owner paired. A local
|
|
226
|
+
program cannot approve its own command by dressing a request up.
|
|
227
|
+
|
|
228
|
+
Root and the Tailscale operator on the host are trusted; nothing else on the
|
|
229
|
+
host or the tailnet is. A tailnet identity is per device: anything running as
|
|
230
|
+
you on another tailnet device of yours is the owner here. Do not proxy another
|
|
231
|
+
service to this listener. Shapewall's tests cover its own request handling with
|
|
232
|
+
a stand-in proxy, not your Tailscale daemon or tailnet ACLs
|
|
233
|
+
([what was and was not checked](hosted.md#what-was-and-was-not-checked-against-real-tailscale)).
|
|
212
234
|
|
|
213
235
|
### Tailscale with a local account
|
|
214
236
|
|
package/docs/design-system.md
CHANGED
|
@@ -134,16 +134,59 @@ scrolling keeps momentum and `scrollIntoView` on phones).
|
|
|
134
134
|
|
|
135
135
|
On desktop the toolbar has two zones with the room between them, the way canvas tools lay it out. Left, identity: the board
|
|
136
136
|
switcher with the capture status dot (its tooltip says when the pages were captured); then, after a hairline, the view controls: the
|
|
137
|
-
screen-size switch, Views (the journeys and what the canvas shows) and, on a local board, Capture with its status. Right,
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
quiet 32 px box with the same radius, hairline and tint, either a single button or a track whose chosen option is the raised chip.
|
|
137
|
+
screen-size switch, Views (the journeys and what the canvas shows) and, on a local board, Capture with its status. Right, open
|
|
138
|
+
panels: the viewer note, then the Comments, Agent and Checks toggles on one track (`Toggle variant="segment"`: the open panel's
|
|
139
|
+
toggle is the raised chip, exactly like the chosen screen size, none while the panel is closed), then Agent settings. The toolbar
|
|
140
|
+
holds what you look at; what you do to the board is in the board tools (below). One look for every control but the name: a quiet
|
|
141
|
+
32 px box with the same radius, hairline and tint, either a single button or a track whose chosen option is the raised chip.
|
|
143
142
|
Comments carries its count as a pill at its right end, and Agent carries the board's agent activity in the same place and size: a
|
|
144
143
|
dot for one agent, a count for more, accent while working (a slow `breathe`, the same as a working pin, never outside the button),
|
|
145
144
|
the attention colour when an agent needs a person, green for a moment when the last one finishes.
|
|
146
145
|
|
|
146
|
+
### The board tools
|
|
147
|
+
|
|
148
|
+
The tools you use on the board float at the bottom centre of the canvas, the way FigJam, Miro and tldraw do it
|
|
149
|
+
(`client/src/board/BoardTools.jsx`, their state in `tools.js`): **Select** (V, the default pointer: a click selects a page or
|
|
150
|
+
opens a pin, a drag on empty canvas pans), **Hand** (H: a drag anywhere pans, a click opens nothing; desktop only), a hairline,
|
|
151
|
+
then **Comment** (C), **Draw** (click a page to draw on it; with a comment or a reply open it draws on that comment's page)
|
|
152
|
+
and, on desktop when the board has live pages, **Select text**. One tool is in use at a time (`aria-pressed`): Comment, Draw
|
|
153
|
+
and Select text are the filled accent button, because they change what a click does; Select and Hand in use are quiet, the
|
|
154
|
+
neutral fill of a chosen segment (`bg-surface-2` with an inset hairline). Esc goes back a step at a time and ends on Select. The pill is the zoom controls' pill (`rounded-lg border border-line bg-surface/95 p-0.5 shadow-pop
|
|
155
|
+
backdrop-blur`, 32 px icon buttons), a labelled `role="toolbar"` with one tab stop: the arrow keys, Home and End move between
|
|
156
|
+
the tools, and each has a tooltip with its shortcut. A person who may not comment has no Comment or Draw tool, and with only
|
|
157
|
+
Select left there is no toolbar (a viewer on a phone). On a desktop they keep Select and Hand, and Select text while a page
|
|
158
|
+
is live.
|
|
159
|
+
|
|
160
|
+
The note for the tool in use sits just above the tools, one at a time: the comment hint ("Click a page to comment ...", or
|
|
161
|
+
"Click where the comment goes on Pricing" when Comment was pressed on that page's bar),
|
|
162
|
+
"Commenting on ..." while the composer is open, the drawing bar, or the select-text note. Select has none. The tools, their note,
|
|
163
|
+
an open journey's bar and the toast are one column (the tool dock), so they never overlap. The tools are centred on the canvas,
|
|
164
|
+
not the window, and never sit over the zoom controls (bottom left) or the minimap (bottom right): on a narrow canvas they shift
|
|
165
|
+
off centre, then the zoom controls compact to out, level and in, then the minimap steps aside (`toolDock.js`, unit-tested). On a
|
|
166
|
+
phone the tools are the bottom bar: 44 px targets above the safe-area inset, hidden while a sheet or the keyboard is up.
|
|
167
|
+
|
|
168
|
+
### The page bar
|
|
169
|
+
|
|
170
|
+
A selected page has a bar of its actions floating beside it in screen pixels (`client/src/board/FrameBar.jsx`): above the card, else
|
|
171
|
+
to its right or left, never over the notes at the top of the canvas or the tool dock at the bottom, and one "..." button when
|
|
172
|
+
there is no room (`frameBarPlace.js`). In order: the page's name and screen size, **Comment**, **Open live** (or **Select text**
|
|
173
|
+
once the page is live), **Checks**, **History**, **Capture**, open in a new tab, close.
|
|
174
|
+
|
|
175
|
+
**Comment** is first because it is the main thing people do with a page, and the tools at the bottom are easy to miss. It is the
|
|
176
|
+
`soft` button at rest (accent text on a light accent tint) and the filled accent while on (`aria-pressed`); its tooltip is
|
|
177
|
+
"Comment on this page" with the C key. It turns the Comment tool on with this page as the target: the hint above the tools names
|
|
178
|
+
the page, the next click on it pins (to the element, on a live page), and a click anywhere else is comment mode's as ever. From
|
|
179
|
+
the keyboard, Enter on the button moves the focus to the page, and Enter there opens the composer near the top left of what
|
|
180
|
+
shows of it; Esc gives the focus back to the button. Only people who have the Comment tool have the button (the same rule: not
|
|
181
|
+
viewers, view-only links, compare mode or static exports). The first time someone who has not started a comment in this browser
|
|
182
|
+
selects a page, the button wears an accent ring for about two and a half seconds (`shapewall.tip.pageComment` in local storage;
|
|
183
|
+
the demo's Reset forgets it). It is a ring, not an animation, so reduced motion needs no other path.
|
|
184
|
+
|
|
185
|
+
The bar is always one line. When the canvas is too narrow for it, words drop in a fixed order and each button keeps its
|
|
186
|
+
accessible name and a tooltip (`fitFrameBar` in `frameBarPlace.js`, unit-tested): Capture, History, Checks, then the page's
|
|
187
|
+
name, then Open live, and Comment last. The widths come from the buttons' fixed sizes, never from the rendered bar. On a phone
|
|
188
|
+
the bar has 44 px targets, no name, and words only on Comment and Open live.
|
|
189
|
+
|
|
147
190
|
Search is not in the toolbar. It is the field at the top of the expanded sidebar ("Search the board" with its
|
|
148
191
|
Ctrl/Cmd+K hint) and an icon in the collapsed rail; both open the command palette, as the shortcut does from anywhere. So the bar
|
|
149
192
|
keeps its shape whatever is open: an open journey shows as the state of the Views button in place (its name, truncated past 240 px,
|
|
@@ -151,6 +194,12 @@ and a clear button), and nothing else moves or collapses for it. When it gets na
|
|
|
151
194
|
in a fixed order (the panel toggles, Views (an open journey's name shortens first), then the screen-size toggle to icons with
|
|
152
195
|
tooltips, where the hairlines go too) and the board name truncates a little at each step, never below about 8 characters.
|
|
153
196
|
Accessible names, shortcuts and tooltips never change.
|
|
197
|
+
While a side panel is open its toggles are the panel's header: their track is exactly as wide as the panel under it, inside the
|
|
198
|
+
bar's 12 px padding on both sides (the panel's own inset), the three sharing the width, and it follows the panel's drag handle with
|
|
199
|
+
no transition (`sidePanelWidth.js` carries the width from the panel to the bar). Everything else in the right zone (the viewer
|
|
200
|
+
note, Agent settings) stays to their left. The left zone drops words sooner to make the room; when no step fits, the toggles keep
|
|
201
|
+
their own width. The panel is never narrower than its toggles need (`SIDE_PANEL` in `toolbarFit.js`: 384 px by default, 368 px at
|
|
202
|
+
least, 560 px or 40% of the window at most).
|
|
154
203
|
`test/toolbar-fit.test.js` checks the order and that nothing overlaps from a 1024 px window with the widest sidebar up. The phone
|
|
155
204
|
toolbar is a separate compact bar. `ToggleGroup` options take a `tooltip` for icon-only labels.
|
|
156
205
|
|
|
@@ -167,7 +216,7 @@ One scale for `z-index`, lowest first. Pick the row that says what the thing is;
|
|
|
167
216
|
| --------- | ----------------- | ----------------------------------------------------------------------------------------------- |
|
|
168
217
|
| Canvas | `z-10`/`z-20` | Pins, card headers and bars, resize handles, presence cursors. |
|
|
169
218
|
| On canvas | `z-30` | Things that belong to the canvas but float over cards: the comment thread and new-comment box, |
|
|
170
|
-
| | | the journey bar, canvas notes, Try this.
|
|
219
|
+
| | | the board tools and their note, the journey bar, canvas notes, Try this. |
|
|
171
220
|
| Chrome | `z-40` | Sticky app headers and the collapsed sidebar's flyouts. |
|
|
172
221
|
| Modal | `z-50` | Dialogs, sheets, the command palette and their dimmed overlay. A modal covers everything below. |
|
|
173
222
|
| Menu | `z-[60]` | Dropdown menus, selects and small popovers, so they work inside a dialog. |
|