shapewall 0.6.0 → 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.
Files changed (127) hide show
  1. package/CHANGELOG.md +252 -0
  2. package/README.md +39 -2
  3. package/THIRD_PARTY.md +15 -0
  4. package/dist/agent/package-lock.json +594 -2
  5. package/dist/client/assets/{BoardChat-DdwBcb2N.js → BoardChat-WS8mAIW6.js} +1 -1
  6. package/dist/client/assets/{BuzzDialog-DpUcnU6S.js → BuzzDialog-B-Mlr6wF.js} +1 -1
  7. package/dist/client/assets/{ChecksPanel-CngYV4yz.js → ChecksPanel-Dx1ZLBR6.js} +1 -1
  8. package/dist/client/assets/{History-CD0saQA5.js → History-sXhmpcvs.js} +1 -1
  9. package/dist/client/assets/{LocalSettings-MZy2baig.js → LocalSettings-CtGzz9F3.js} +1 -1
  10. package/dist/client/assets/{Management-CSvZ-SHO.js → Management-CGHe8Wt9.js} +1 -1
  11. package/dist/client/assets/{QuickConnect-foLh2QUm.js → QuickConnect-DEk84E4A.js} +1 -1
  12. package/dist/client/assets/{ShareDialog-DPWDftoL.js → ShareDialog-CGGx-AYK.js} +1 -1
  13. package/dist/client/assets/{app-update-dialog-CtiXpTRD.js → app-update-dialog-_bVp8hnC.js} +1 -1
  14. package/dist/client/assets/{circle-x-CteRBtXC.js → circle-x-BWoHA1QY.js} +1 -1
  15. package/dist/client/assets/index-Bm-Xd3YN.js +37 -0
  16. package/dist/client/assets/index-C7Ostk3K.css +2 -0
  17. package/dist/client/assets/{play-BjRNIGSf.js → play-BzQ3tRTv.js} +1 -1
  18. package/dist/client/assets/{refresh-cw-r_tZiFfB.js → refresh-cw-BYBMyDKT.js} +1 -1
  19. package/dist/client/assets/{ui-zQpn-PdL.js → ui-CAY6myRA.js} +1 -1
  20. package/dist/client/build-info.json +1 -1
  21. package/dist/client/index.html +3 -3
  22. package/dist/client/sw.js +2 -2
  23. package/dist/console/assets/LocalAccountsApp-CWRguRRL.js +1 -0
  24. package/dist/console/assets/LocalConsole--I2SaIpr.js +2 -0
  25. package/dist/console/assets/LocalUsage-BmpCZ36k.js +1 -0
  26. package/dist/console/assets/app-update-dialog-B8M9plaT.js +1 -0
  27. package/dist/console/assets/app-version-muKrQqbL.js +1 -0
  28. package/dist/console/assets/console-CrhTsPbz.css +2 -0
  29. package/dist/console/assets/console-DxapQ9oS.js +11 -0
  30. package/dist/console/assets/local-agents-CoqD4dSN.js +6 -0
  31. package/dist/console/assets/minus-DDQ0ydcM.js +1 -0
  32. package/dist/console/assets/tailnet-C5Flwl_d.js +2 -0
  33. package/dist/console/assets/theme-DCd0qh4l.js +1 -0
  34. package/dist/console/assets/ui-Bry1mnCY.js +41 -0
  35. package/dist/console/assets/usage-CIPWnHaS.css +1 -0
  36. package/dist/console/assets/usage-CqVjMb7m.js +5 -0
  37. package/dist/console/assets/usage-D1G0GgE3.js +56 -0
  38. package/dist/console/build-info.json +1 -1
  39. package/dist/console/console.html +8 -2
  40. package/docs/agent-hardening.md +31 -17
  41. package/docs/agents.md +35 -0
  42. package/docs/architecture.md +10 -4
  43. package/docs/deployment.md +39 -17
  44. package/docs/design-system.md +56 -7
  45. package/docs/hosted.md +1004 -43
  46. package/docs/images/board-overview.png +0 -0
  47. package/docs/images/journeys.png +0 -0
  48. package/docs/images/live-comment.png +0 -0
  49. package/docs/images/phone-comment.png +0 -0
  50. package/docs/images/phone-overview.png +0 -0
  51. package/docs/images/variant.png +0 -0
  52. package/docs/where-to-run.md +82 -1
  53. package/package.json +6 -1
  54. package/src/agent/backends/acp.js +224 -26
  55. package/src/agent/routes.js +21 -0
  56. package/src/agent/usage-log.js +251 -0
  57. package/src/cli/args.js +24 -0
  58. package/src/cli/help.js +37 -2
  59. package/src/cli/init.js +2 -1
  60. package/src/cli/serve.js +20 -5
  61. package/src/cli.js +8 -0
  62. package/src/hosted/access-cli.js +99 -1
  63. package/src/hosted/activity-core.js +232 -0
  64. package/src/hosted/activity.js +375 -0
  65. package/src/hosted/admin.js +80 -13
  66. package/src/hosted/agent-approvals.js +2 -2
  67. package/src/hosted/agent-routes.js +3 -3
  68. package/src/hosted/agents.js +11 -4
  69. package/src/hosted/app.js +89 -7
  70. package/src/hosted/auth-routes.js +156 -15
  71. package/src/hosted/auth.js +123 -20
  72. package/src/hosted/board-routes.js +3 -3
  73. package/src/hosted/chat-frames.js +5 -15
  74. package/src/hosted/chat-permissions.js +12 -0
  75. package/src/hosted/chat-routes.js +8 -8
  76. package/src/hosted/chat-store.js +20 -3
  77. package/src/hosted/comment-files.js +5 -2
  78. package/src/hosted/console-routes.js +111 -34
  79. package/src/hosted/db.js +130 -0
  80. package/src/hosted/device-routes.js +25 -3
  81. package/src/hosted/device.js +23 -4
  82. package/src/hosted/guards.js +337 -27
  83. package/src/hosted/http.js +6 -3
  84. package/src/hosted/membership.js +13 -2
  85. package/src/hosted/operator-access.js +418 -0
  86. package/src/hosted/operator.js +106 -2
  87. package/src/hosted/ops-cli.js +238 -3
  88. package/src/hosted/pages.js +2 -0
  89. package/src/hosted/passkey-policy.js +75 -0
  90. package/src/hosted/permissions.js +14 -6
  91. package/src/hosted/presence.js +14 -2
  92. package/src/hosted/projects.js +2 -1
  93. package/src/hosted/public.js +4 -4
  94. package/src/hosted/ratelimit.js +6 -0
  95. package/src/hosted/retention.js +18 -2
  96. package/src/hosted/server.js +123 -11
  97. package/src/hosted/shares.js +2 -2
  98. package/src/hosted/step-up-settings.js +68 -0
  99. package/src/hosted/step-up.js +135 -0
  100. package/src/hosted/tailnet-identity.js +24 -0
  101. package/src/hosted/tailnet-routes.js +342 -0
  102. package/src/hosted/tailnet.js +220 -0
  103. package/src/hosted/tailscale.js +75 -9
  104. package/src/hosted/tenancy.js +48 -1
  105. package/src/hosted/token-api.js +2 -2
  106. package/src/hosted/tokens.js +9 -2
  107. package/src/hosted/usage-core.js +624 -0
  108. package/src/hosted/usage-layout.js +724 -0
  109. package/src/hosted/usage-routes.js +375 -0
  110. package/src/hosted/usage-shape.js +256 -0
  111. package/src/hosted/usage.js +641 -0
  112. package/src/remote/agent-connect.js +37 -1
  113. package/src/remote/agent-link.js +2 -0
  114. package/src/remote/login.js +33 -8
  115. package/src/remote/share.js +1 -1
  116. package/src/remote/tailnet-cli.js +547 -0
  117. package/src/server/app.js +15 -0
  118. package/src/server/pairing-routes.js +34 -5
  119. package/src/server/tailscale.js +97 -4
  120. package/src/tailnet-proof.js +766 -0
  121. package/dist/client/assets/index-Cxz1UVcV.css +0 -2
  122. package/dist/client/assets/index-uUZVBYUS.js +0 -37
  123. package/dist/console/assets/LocalAccountsApp-DIdy1KnN.js +0 -1
  124. package/dist/console/assets/LocalConsole-DfcQztF-.js +0 -1
  125. package/dist/console/assets/app-update-dialog-ttl9lF5A.js +0 -1
  126. package/dist/console/assets/console-OqAjD0kV.js +0 -55
  127. package/dist/console/assets/console-kvjrAArQ.css +0 -2
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
@@ -7,9 +7,10 @@ Shapewall has two shapes. Pick by who needs the board and when, not by how big t
7
7
  | One person, reviewing your own project | `npx shapewall serve` in the project, next to its dev server | You, on this machine | No: start it when you work |
8
8
  | One person, also on your phone or second laptop | `npx shapewall serve --tailscale` | Your own devices on your tailnet | No |
9
9
  | A team, or you and your agents around the clock | `shapewall hosted --tailscale` on a machine that stays on | Everyone you invite, on your tailnet | Yes |
10
+ | The same, with no passkeys to set up | `shapewall hosted --tailscale --tailnet-sign-in` | Tailnet users you invite by login | Yes |
10
11
  | A team with people outside your tailnet | `shapewall hosted` behind your own domain | Everyone you invite, from anywhere | Yes |
11
12
 
12
- The first two are the same local board. The last two are the same hosted server, reached two ways. Nothing about a project changes
13
+ The first two are the same local board. The others are the same hosted server, reached in different ways. Nothing about a project changes
13
14
  when you move between them: the config, the captures and the comments are the same files.
14
15
 
15
16
  ## The local board
@@ -46,6 +47,86 @@ and sign-in stay private. When people outside your tailnet need accounts, put th
46
47
  `shapewall hosted --setup --domain app.example.com` writes a Docker Compose and Caddy folder for that
47
48
  ([Own domain deployment](hosted.md#own-domain-deployment-mode-2)).
48
49
 
50
+ ### How people sign in
51
+
52
+ | How you reach it | Sign-in |
53
+ | ---------------------------- | ------------------------------------------------------------------------------------------ |
54
+ | Local board | None. It is yours, on your machine |
55
+ | Over an SSH tunnel | A local board: none, as if you sat at that machine. A hosted server: a passkey each |
56
+ | Tailnet, `--tailnet-sign-in` | Your Tailscale account, on every tailnet device of yours. No passkey. An admin invites you |
57
+ | Own domain | A passkey each |
58
+
59
+ On the hosted server, being signed in with the right role is enough for everything in a workspace. A few things always ask
60
+ (deleting an account or a workspace, changing owners): for a passkey where passkeys are the sign-in, and for a typed name on
61
+ a tailnet sign-in server, where Tailscale is the only sign-in and the tailnet is the trust boundary (anything running as you
62
+ on one of your tailnet devices can act as you; lock your devices and keep the tailnet to people and machines you trust). A
63
+ tailnet server can also allow passkeys (`--tailnet-passkeys`). Details: [Signing in](hosted.md#signing-in).
64
+
65
+ ### Over SSH
66
+
67
+ No Tailscale? Tunnel one port over SSH.
68
+
69
+ ```sh
70
+ shapewall hosted --data ./hosted-data --port 4700 --origin http://shapewall.localhost:4700 # on the server; loopback, no TLS
71
+ ssh -L 4700:127.0.0.1:4700 you@server # on your machine
72
+ # then open http://shapewall.localhost:4700
73
+ ```
74
+
75
+ A hosted server reached this way uses passkey accounts. `shapewall.localhost` is a name browsers send to your own machine and
76
+ treat as a secure context, so passkeys work, and it keeps the server's cookies to itself; plain `http://localhost:4700` works
77
+ too, but there the session cookie is also sent to any other web server on your machine's localhost. Everyone who tunnels in
78
+ shares `127.0.0.1` for rate limits and in the audit log. A local board reached this way (`shapewall serve` on the remote
79
+ machine, the same kind of tunnel) sees you as the person at that machine: no sign-in, and so not something to tunnel for
80
+ other people. More: [Over SSH](hosted.md#over-ssh).
81
+
82
+ With tailnet sign-in the server believes Tailscale's identity headers only on requests that provably came through the serve
83
+ entry it made (a secret path, a connection owned by tailscaled, tailscaled's own whois), never on direct loopback requests,
84
+ raw forwards or Funnel traffic, never for a request from the server's own machine (use a passkey or another device there),
85
+ and each tailnet login is its own account: being on the tailnet alone puts nobody in a
86
+ workspace. It needs Linux, Tailscale 1.98 or newer in its normal (TUN) mode, and a server that is not in a container. A
87
+ tailnet identity is per device, not per person: anything running as you on a tailnet device of yours can act as you there.
88
+ See [Tailnet sign-in](hosted.md#tailnet-sign-in).
89
+
90
+ ### From your coding agent
91
+
92
+ On a server with tailnet sign-in, a terminal or a coding agent on a tailnet machine needs no browser: the server knows the
93
+ machine's tailnet user.
94
+
95
+ An owner, from nothing to a first project. On the machine that runs the server (the data folder is the proof; `--login`
96
+ says whose server it is):
97
+
98
+ ```sh
99
+ shapewall hosted --data ./hosted-data --tailscale --tailnet-sign-in &
100
+ shapewall hosted claim --data ./hosted-data --login ada@example.com --workspace-name "Team" # no browser
101
+ ```
102
+
103
+ Then on another tailnet device of the owner's (the server's own machine is never signed in by its tailnet identity):
104
+
105
+ ```sh
106
+ shapewall admin projects create "My site" --remote https://board.example.ts.net
107
+ shapewall login --remote https://board.example.ts.net # no code, no browser
108
+ shapewall capture && shapewall push --remote https://board.example.ts.net
109
+ shapewall admin invites create --login ben@example.com --role admin --remote https://board.example.ts.net
110
+ ```
111
+
112
+ Needs a browser: nothing now. Later, adding a passkey, for the few things that always ask for one (a first passkey can confirm
113
+ them 24 hours after it is added, so add it early).
114
+
115
+ A member, on their own tailnet machine, after an admin invited their login:
116
+
117
+ ```sh
118
+ shapewall join --remote https://board.example.ts.net # takes the invite; the role is the invite's
119
+ shapewall agent connect --remote https://board.example.ts.net --project my-site --name "Builder"
120
+ ```
121
+
122
+ Needs a browser: nothing for an admin, unless the workspace switched on "Approve command line logins in the browser" (then the
123
+ code, the browser and a passkey). A member or viewer may not connect a machine by themselves: `agent connect` shows a code
124
+ for an admin to approve, as on any server.
125
+
126
+ On a server without tailnet sign-in these commands change nothing: `login` and `agent connect` use the code and the browser,
127
+ `join` says an account needs a passkey (made in the browser), and `admin` points at the console. The rules, and every refusal:
128
+ [From your coding agent](hosted.md#from-your-coding-agent).
129
+
49
130
  ### Where the work happens
50
131
 
51
132
  The hosted server never captures a page and never edits code. Those happen on a machine that has the project:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shapewall",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Every page of your site on one zoomable wall: desktop and phone captures, sandboxed live HTML, and element-anchored comments your coding agent can read.",
5
5
  "license": "Apache-2.0 AND FSL-1.1-ALv2",
6
6
  "author": "Dan Baruch",
@@ -114,6 +114,9 @@
114
114
  "devDependencies": {
115
115
  "@eslint/js": "^10.0.1",
116
116
  "@tailwindcss/vite": "^4.3.4",
117
+ "@tanstack/react-query": "5.107.1",
118
+ "@tanstack/react-table": "9.3.1",
119
+ "@tanstack/react-virtual": "3.14.26",
117
120
  "@titan-design/speech-g2p": "0.0.0",
118
121
  "@vitejs/plugin-react": "^6.2.1",
119
122
  "@xyflow/react": "^12.12.1",
@@ -129,6 +132,8 @@
129
132
  "radix-ui": "^1.8.1",
130
133
  "react": "^19.3.1",
131
134
  "react-dom": "^19.3.1",
135
+ "react-grid-layout": "2.3.0",
136
+ "recharts": "3.10.1",
132
137
  "tailwind-merge": "^3.7.0",
133
138
  "tailwindcss": "^4.3.4",
134
139
  "vite": "^8.3.5"
@@ -76,6 +76,48 @@ export const READ_ONLY_MODES = {
76
76
  codex: ['read-only'],
77
77
  goose: ['chat'],
78
78
  }
79
+ // The adapter versions the read-only and edit sessions were proven with,
80
+ // against the real adapter (docs/agent-hardening.md). Another version is
81
+ // used as it is, with a plain warning: an adapter changes what it starts a
82
+ // session with (0.106.0 starts in the mode "auto" where 0.93.0 started in
83
+ // "default"), and only a tested version is known to keep what is promised.
84
+ export const TESTED_ADAPTERS = {
85
+ claude: { name: '@agentclientprotocol/claude-agent-acp', versions: ['0.93.0', '0.106.0'] },
86
+ }
87
+ const versionParts = (text) => {
88
+ const found = /^(\d+)\.(\d+)\.(\d+)/.exec(String(text || ''))
89
+ return found ? found.slice(1).map(Number) : null
90
+ }
91
+ const versionOrder = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2]
92
+ // What an adapter says it is (initialize's agentInfo), for a log line or an
93
+ // error: "@agentclientprotocol/claude-agent-acp 0.106.0", or '' when it says nothing.
94
+ export function adapterName(agentInfo) {
95
+ const name = showable(String(agentInfo?.name || agentInfo?.title || '')).slice(0, 80)
96
+ const version = showable(String(agentInfo?.version || '')).slice(0, 40)
97
+ return [name, version].filter(Boolean).join(' ')
98
+ }
99
+ // { state, versions, install }: 'tested', 'newer' (than every tested one) or
100
+ // 'untested' (older, in between, another package, or no version said); null
101
+ // for an agent with no tested list.
102
+ export function adapterStatus(kind, agentInfo) {
103
+ const known = TESTED_ADAPTERS[kind]
104
+ if (!known) return null
105
+ const out = { versions: known.versions, install: `npm install -g ${known.name}@${known.versions.at(-1)}` }
106
+ const version = versionParts(agentInfo?.version)
107
+ if (agentInfo?.name !== known.name || !version) return { ...out, state: 'untested' }
108
+ if (known.versions.includes(version.join('.'))) return { ...out, state: 'tested' }
109
+ return { ...out, state: known.versions.every((item) => versionOrder(version, versionParts(item)) > 0) ? 'newer' : 'untested' }
110
+ }
111
+ // One plain line about an adapter that is not a tested one, or null.
112
+ export function adapterWarning(kind, agentInfo, label) {
113
+ const status = adapterStatus(kind, agentInfo)
114
+ if (!status || status.state === 'tested') return null
115
+ const said = adapterName(agentInfo) || 'an adapter that does not say its version'
116
+ const tested = `${TESTED_ADAPTERS[kind].name} ${status.versions.join(' and ')}`
117
+ const what = status.state === 'newer' ? 'which is newer than the versions' : 'which is not a version'
118
+ return `${label} runs through ${said}, ${what} Shapewall ${VERSION} was tested with (${tested}). It is used as it is. If chats fail or behave oddly, install a tested one: ${status.install}`
119
+ }
120
+
79
121
  // Claude Code's tools that only read. Everything else is removed from the
80
122
  // session, so no allow rule and no mode can run it.
81
123
  const CLAUDE_READ_TOOLS = ['Read', 'Grep', 'Glob']
@@ -699,6 +741,12 @@ class AcpProcess {
699
741
  child.stderr.on('data', (chunk) => {
700
742
  this.stderr = (this.stderr + chunk.toString('utf8')).slice(-STDERR_KEEP)
701
743
  })
744
+ // Everything it wrote has been read (lastWords waits for this).
745
+ this.stderrClosed = new Promise((resolve) => {
746
+ child.stderr.once('end', resolve)
747
+ child.stderr.once('close', resolve)
748
+ child.stderr.once('error', resolve)
749
+ })
702
750
  child.stdin.on('error', () => {})
703
751
  // A later error (a failed kill) must not take the server down.
704
752
  child.on('error', () => {})
@@ -757,7 +805,15 @@ class AcpProcess {
757
805
  this.state = 'ready'
758
806
  if (this.asks) await this.askingMode()
759
807
  } catch (error) {
760
- throw this.startError(error)
808
+ // Its output closed: the exit follows in a moment, and says more (the code, its last words) than the request that failed.
809
+ if (!this.exited && !this.killedFor && (child.stdout.readableEnded || child.stdout.destroyed))
810
+ await Promise.race([this.exitedPromise, new Promise((resolve) => setTimeout(resolve, 500))])
811
+ // What happened is settled now, before it is stopped: stopping it is an exit of our own making.
812
+ const was = { why: this.killedFor, exited: Boolean(this.exited) }
813
+ this.kill('start_failed')
814
+ // Its answer and its stderr are two pipes: the failed request can be read before the words that explain it.
815
+ await this.lastWords()
816
+ throw this.startError(error, was)
761
817
  } finally {
762
818
  clearTimeout(timer)
763
819
  signal?.removeEventListener('abort', onAbort)
@@ -765,17 +821,82 @@ class AcpProcess {
765
821
  return this
766
822
  }
767
823
 
768
- startError(error) {
769
- if (this.killedFor === 'start_timeout') {
770
- this.kill('start_failed')
771
- return new AgentError('agent_start', `${this.label} did not answer within ${Math.round(this.limits.startMs / 1000)} seconds.`)
772
- }
824
+ // Waits, for a bounded moment, until all of a stopped agent's stderr has
825
+ // been read: the pipe closes when the process is gone, and everything it
826
+ // wrote comes before that. An agent that does not stop (it ignores the
827
+ // signal) delays the error by `ms` at most.
828
+ async lastWords(ms = 750) {
829
+ if (!this.stderrClosed) return
830
+ let timer
831
+ await Promise.race([
832
+ this.stderrClosed,
833
+ new Promise((resolve) => {
834
+ timer = setTimeout(resolve, ms)
835
+ }),
836
+ ])
837
+ clearTimeout(timer)
838
+ }
839
+
840
+ // `was`: why it had been stopped, and whether it had exited, before start() stopped it itself.
841
+ startError(error, { why = null, exited = false } = {}) {
773
842
  this.kill('start_failed')
843
+ if (why === 'start_timeout')
844
+ return this.startFailure(`${this.label} did not answer within ${Math.round(this.limits.startMs / 1000)} seconds`)
845
+ // Stopped while it started (an unsafe mode, a cancel): said as that, not as the request that then failed.
846
+ if (why) return this.stoppedError(why)
774
847
  // Read only, and the agent's mode cannot be trusted to ask: said as it is.
775
- if (error instanceof AgentError && error.code === 'agent_unsafe_mode') return error
848
+ if (error instanceof AgentError && error.code === 'agent_unsafe_mode') {
849
+ const said = adapterName(this.agentInfo)
850
+ if (said) error.message = `${error.message} Its adapter: ${said}.`
851
+ return error
852
+ }
776
853
  if (authFailure(error)) return this.authError()
777
- if (this.exited) return this.exitError()
778
- return new AgentError('agent_start', `${this.label} did not start an ACP session (${cut(errorText(error) || 'no answer', 300)}).`)
854
+ if (exited) return this.exitError({ starting: true })
855
+ return this.startFailure(`${this.label} did not start an ACP session (${cut(errorText(error) || 'no answer', 300)})`)
856
+ }
857
+
858
+ // The agent's last words on stderr, for a message: a few lines, with
859
+ // anything that looks like a key removed and the home folder not spelled out.
860
+ stderrTail(max = 300, lines = 3) {
861
+ const home = os.homedir()
862
+ const tail = redact(this.stderr.trim().split('\n').slice(-lines).join(' ').trim())
863
+ return cut(home.length > 1 ? tail.split(home).join('~') : tail, max)
864
+ }
865
+
866
+ // What to try, after a start that failed: a tested adapter version when
867
+ // this one is not, else where to look.
868
+ startHint() {
869
+ const status = adapterStatus(acpAgentKind(this.argv), this.agentInfo)
870
+ if (status && status.state !== 'tested' && this.agentInfo)
871
+ return `This adapter version is not one Shapewall ${VERSION} was tested with (${status.versions.join(', ')}); a tested one: ${status.install}`
872
+ return 'To see more, run "shapewall doctor" in the project folder on the machine the agent runs on (docs/agents.md).'
873
+ }
874
+
875
+ // A start that failed, with everything known about why: what happened, the
876
+ // adapter and its version, its last output and what to try. Never just
877
+ // "did not start".
878
+ startFailure(what, code = 'agent_start') {
879
+ const tail = this.stderrTail()
880
+ const home = os.homedir()
881
+ const text = `${what}${this.via()}.${tail ? ` Its last output: ${tail}` : ''} ${this.startHint()}`.replace(/\s+/g, ' ')
882
+ // The agent's own error text may name files: the home folder is not spelled out in a chat.
883
+ return new AgentError(code, home.length > 1 ? text.split(home).join('~') : text)
884
+ }
885
+
886
+ // Stopped by Shapewall before it was ready, and why.
887
+ stoppedError(why = this.killedFor) {
888
+ if (why === 'unsafe_mode')
889
+ return this.startFailure(
890
+ `${this.label} moved to the mode "${this.unsafeWas ?? '?'}", which acts without asking, while it started. A connected agent must ask before it acts, so it was stopped`,
891
+ 'agent_unsafe_mode',
892
+ )
893
+ const reasons = {
894
+ aborted: 'the request was cancelled',
895
+ cleared: 'the thread was cleared',
896
+ shutdown: 'Shapewall is stopping',
897
+ evicted: 'another thread needed its place',
898
+ }
899
+ return this.startFailure(`${this.label} did not start: ${reasons[why] || `it was stopped while starting (${why || this.state})`}`)
779
900
  }
780
901
 
781
902
  // Not logged in: the fix goes to the chat and to the server log.
@@ -785,10 +906,13 @@ class AcpProcess {
785
906
  return error
786
907
  }
787
908
 
788
- exitError() {
789
- const tail = this.stderr.trim().split('\n').slice(-3).join(' ').trim()
909
+ // `starting`: it went away before its session was ready (the adapter, its
910
+ // version and what to try are said too).
911
+ exitError({ starting = false } = {}) {
912
+ const tail = this.stderrTail()
790
913
  const how = this.exited?.signal ? `signal ${this.exited.signal}` : `code ${this.exited?.code ?? '?'}`
791
- return new AgentError('agent_exited', `${this.label} stopped (${how})${tail ? `: ${cut(tail, 300)}` : '.'}`)
914
+ if (starting) return this.startFailure(`${this.label} stopped while it started (${how})`, 'agent_exited')
915
+ return new AgentError('agent_exited', `${this.label} stopped (${how})${tail ? `: ${tail}` : '.'}`)
792
916
  }
793
917
 
794
918
  gone(code, signalName) {
@@ -800,7 +924,15 @@ class AcpProcess {
800
924
  // Whatever a running turn was waiting for will not come.
801
925
  if (this.turn) {
802
926
  for (const permission of this.turn.permissions.values()) permission.settle('cancelled')
803
- this.turn.queue.end(this.turn.cancelled ? null : this.exitError())
927
+ // Stopped here for a mode that acts without asking: the chat hears that, not "signal SIGTERM".
928
+ const why =
929
+ this.killedFor === 'unsafe_mode'
930
+ ? new AgentError(
931
+ 'agent_unsafe_mode',
932
+ `${this.label} moved to the mode "${this.unsafeWas ?? '?'}", which acts without asking. A connected agent must ask before it acts, so it was stopped${this.via()}.`,
933
+ )
934
+ : this.exitError()
935
+ this.turn.queue.end(this.turn.cancelled ? null : why)
804
936
  }
805
937
  try {
806
938
  this.connection?.close()
@@ -965,12 +1097,29 @@ class AcpProcess {
965
1097
  const wanted = READ_ONLY_MODES[acpAgentKind(this.argv)]
966
1098
  return wanted ? wanted.includes(item.value) : !UNSAFE_VALUE_RE.test(`${item.value} ${item.name}`)
967
1099
  }
1100
+ // A mode's display name, as the agent lists it.
1101
+ modeName(id) {
1102
+ return this.modeState()?.values.find((item) => item.value === id)?.name || id
1103
+ }
968
1104
  // The mode when it is not allowed (see modeAllowed), else null.
969
1105
  unsafeMode() {
970
1106
  const state = this.modeState()
971
1107
  if (!state) return null
972
- const name = state.values.find((item) => item.value === state.current)?.name || state.current
973
- return this.modeAllowed({ value: state.current, name }) ? null : state
1108
+ return this.modeAllowed({ value: state.current, name: this.modeName(state.current) }) ? null : state
1109
+ }
1110
+ // A connected agent's session moved to a mode that acts without asking:
1111
+ // it stops, and the log and the chat say which mode.
1112
+ unsafeStop(mode) {
1113
+ if (this.unsafeWas === undefined) {
1114
+ this.unsafeWas = cut(showable(mode), 40)
1115
+ this.log(`acp: ${this.label} moved to the mode "${this.unsafeWas}", which acts without asking, so it was stopped${this.via()}`)
1116
+ }
1117
+ this.kill('unsafe_mode')
1118
+ }
1119
+ // " (through <adapter> <version>)" for a message, or ''.
1120
+ via() {
1121
+ const said = adapterName(this.agentInfo)
1122
+ return said ? ` (through ${said})` : ''
974
1123
  }
975
1124
  // Read only, fail closed: the session must report a mode, and it must be
976
1125
  // one that asks. Anything else is switched to one, or the agent does not
@@ -1015,7 +1164,9 @@ class AcpProcess {
1015
1164
  throw refuse()
1016
1165
  }
1017
1166
  if (this.unsafeMode()) throw refuse()
1018
- this.log(`acp: ${this.label} switched from mode "${cut(unsafe.current, 40)}" to "${cut(pick.value, 40)}" (read only)`)
1167
+ this.log(
1168
+ `acp: ${this.label} switched from mode "${cut(unsafe.current, 40)}" to "${cut(pick.value, 40)}" (${this.readOnly ? 'read only' : 'edits are asked on the board'})`,
1169
+ )
1019
1170
  }
1020
1171
 
1021
1172
  // Read only: what the agent asked for is refused here, and the answer
@@ -1250,14 +1401,26 @@ class AcpProcess {
1250
1401
  if (params?.sessionId === this.sessionId && params.update?.sessionUpdate === 'config_option_update') {
1251
1402
  // The agent changed its own model or effort (or confirmed ours): the composer shows it.
1252
1403
  if (Array.isArray(params.update.configOptions)) this.configOptions = params.update.configOptions
1253
- if (this.asks && this.unsafeMode()) this.kill('unsafe_mode')
1404
+ const unsafe = this.asks ? this.unsafeMode() : null
1405
+ if (unsafe) this.unsafeStop(unsafe.current)
1254
1406
  return
1255
1407
  }
1256
1408
  if (params?.sessionId === this.sessionId && params.update?.sessionUpdate === 'current_mode_update') {
1257
- if (this.modes && typeof params.update.currentModeId === 'string')
1258
- this.modes = { ...this.modes, currentModeId: params.update.currentModeId }
1259
- // Read only: an agent that switches itself to a mode that acts without asking stops.
1260
- if (this.asks && this.unsafeMode()) this.kill('unsafe_mode')
1409
+ const id = params.update.currentModeId
1410
+ if (typeof id !== 'string') return
1411
+ if (this.modes) this.modes = { ...this.modes, currentModeId: id }
1412
+ // An agent that reports its mode both ways (a "mode" config option and
1413
+ // modes) has one mode: this is it. The option's own update may come
1414
+ // later, or only with the answer to the request that changed it
1415
+ // (claude-agent-acp 0.106.0 sends this first when asked to switch), and
1416
+ // until then the option would still name the mode the session left.
1417
+ const option = this.configOptions.find((item) => item?.category === 'mode' && typeof item.currentValue === 'string')
1418
+ if (option && optionValues(option.options).some((item) => item.value === id))
1419
+ this.configOptions = this.configOptions.map((item) => (item === option ? { ...item, currentValue: id } : item))
1420
+ // Read only: an agent that switches itself to a mode that acts without
1421
+ // asking stops. The mode it names is checked itself, and so is what the
1422
+ // session's state then says.
1423
+ if (this.asks && (!this.modeAllowed({ value: id, name: this.modeName(id) }) || this.unsafeMode())) this.unsafeStop(id)
1261
1424
  return
1262
1425
  }
1263
1426
  const turn = this.turn
@@ -1829,6 +1992,7 @@ export function createAcpBackend(
1829
1992
  } catch (error) {
1830
1993
  agent.kill('start_failed')
1831
1994
  await agent.stoppingPromise
1995
+ startFailed(agent, error)
1832
1996
  throw error
1833
1997
  } finally {
1834
1998
  starting.delete(agent)
@@ -1841,11 +2005,32 @@ export function createAcpBackend(
1841
2005
  await agent.stoppingPromise
1842
2006
  throw new AgentError('agent_start', 'The server is stopping.')
1843
2007
  }
1844
- if (agent.state !== 'ready') throw agent.exited ? agent.exitError() : new AgentError('agent_start', `${settings.label} did not start.`)
2008
+ if (agent.state !== 'ready') {
2009
+ // Ready a moment ago, and gone or stopped since: said with the cause.
2010
+ const gone = Boolean(agent.exited)
2011
+ const why = agent.killedFor
2012
+ agent.kill('start_failed')
2013
+ await agent.lastWords()
2014
+ const error = gone ? agent.exitError({ starting: true }) : agent.stoppedError(why)
2015
+
2016
+ startFailed(agent, error)
2017
+ throw error
2018
+ }
1845
2019
  processes.set(thread, agent)
1846
2020
  return agent
1847
2021
  }
1848
2022
 
2023
+ // A start that failed goes to the log with its cause, as it goes to the
2024
+ // chat: the message, and more of the agent's last output than a chat shows.
2025
+ // Not when the person or Shapewall stopped it, and not twice for a login
2026
+ // (authError logs its own line).
2027
+ const startFailed = (agent, error) => {
2028
+ if (['aborted', 'cleared', 'shutdown', 'evicted', 'doctor'].includes(agent.killedFor) || error?.code === 'agent_auth') return
2029
+ log(`acp: ${error?.message || `${settings.label} did not start`}`)
2030
+ const tail = agent.stderrTail(1500, 12)
2031
+ if (tail) log(`acp: ${settings.label} last output: ${tail}`)
2032
+ }
2033
+
1849
2034
  return {
1850
2035
  id: 'acp',
1851
2036
  tools: 'own',
@@ -1973,7 +2158,10 @@ export function createAcpBackend(
1973
2158
 
1974
2159
  // `shapewall doctor`: starts the agent, does the initialize handshake, and
1975
2160
  // stops it again. Never sends a prompt (that would spend the subscription).
1976
- export async function acpHandshake(settings, { env = process.env, root, timeoutMs = 30000, processPool = null } = {}) {
2161
+ // `agent connect` does the same before it goes online, with the session a
2162
+ // connected agent gets (settings.readOnly, settings.remoteEdit): a session
2163
+ // that cannot be opened is said at once, with why, not at the first question.
2164
+ export async function acpHandshake(settings, { env = process.env, root, timeoutMs = 30000, processPool = null, log = () => {} } = {}) {
1977
2165
  const sandbox = createSandbox({ root })
1978
2166
  const agent = new AcpProcess({
1979
2167
  argv: settings.acp.argv,
@@ -1981,8 +2169,10 @@ export async function acpHandshake(settings, { env = process.env, root, timeoutM
1981
2169
  env,
1982
2170
  sandbox,
1983
2171
  limits: { ...ACP_DEFAULTS, startMs: timeoutMs },
1984
- log: () => {},
2172
+ log,
1985
2173
  thread: 'doctor',
2174
+ readOnly: settings.readOnly === true,
2175
+ remoteEdit: settings.readOnly !== true && settings.remoteEdit ? settings.remoteEdit : null,
1986
2176
  onGone: (item) => {
1987
2177
  if (item.stopped || !item.pid) processPool?.agents.delete(item)
1988
2178
  poolChanged(processPool)
@@ -1991,9 +2181,17 @@ export async function acpHandshake(settings, { env = process.env, root, timeoutM
1991
2181
  try {
1992
2182
  await reserveProcessSlot(processPool, agent)
1993
2183
  await agent.start()
1994
- return { ok: true, agentInfo: agent.agentInfo, image: agent.image, choices: agent.choices }
2184
+ // Stopped between its answer and now (a mode that acts without asking): not a session.
2185
+ if (agent.state !== 'ready') {
2186
+ const gone = Boolean(agent.exited)
2187
+ const why = agent.killedFor
2188
+ agent.kill('doctor')
2189
+ await agent.lastWords()
2190
+ throw gone ? agent.exitError({ starting: true }) : agent.stoppedError(why)
2191
+ }
2192
+ return { ok: true, agentInfo: agent.agentInfo, image: agent.image, choices: agent.choices, mode: agent.modeState()?.current ?? null }
1995
2193
  } catch (error) {
1996
- return { ok: false, code: error.code, message: error.message }
2194
+ return { ok: false, code: error.code, message: error.message, agentInfo: agent.agentInfo || null, stderr: agent.stderrTail(1500, 12) }
1997
2195
  } finally {
1998
2196
  agent.kill('doctor')
1999
2197
  await agent.stoppingPromise
@@ -61,6 +61,7 @@ import {
61
61
  writeMeta,
62
62
  } from './branch-mode.js'
63
63
  import { createBackend } from './backends/index.js'
64
+ import { localUsageRow, recordLocalTurn, summarizeLocalUsage } from './usage-log.js'
64
65
  import { AGENTS_EVENT, createSettingsEvents } from './settings-events.js'
65
66
  import { batchFixSettings, createBatchQueue } from './batch-fixes.js'
66
67
  import { FIX_PROMPT as BATCH_FIX_PROMPT } from './fix-prompt.js'
@@ -954,6 +955,20 @@ export function agentRouter({
954
955
  })
955
956
  }
956
957
  }
958
+ // The usage record of this turn (usage-log.js): numbers and ids, never text.
959
+ await recordLocalTurn(
960
+ config,
961
+ localUsageRow({
962
+ reply,
963
+ boardId: board.id,
964
+ threadId,
965
+ commentId,
966
+ kind: fix ? 'fix' : commentId ? 'review' : 'chat',
967
+ viewer: res.locals.viewer,
968
+ agent: { id: current.profileId || 'default', label: current.label, backend: current.backend, model: current.model },
969
+ startedAt: Date.now() - (reply.durationMs || 0),
970
+ }),
971
+ )
957
972
  if (previous) await replaceAnswer(config, board.id, threadId, previous.id, reply)
958
973
  else await appendAssistantMessage(config, board.id, threadId, reply)
959
974
  emit('done', { message: reply })
@@ -1437,6 +1452,12 @@ export function agentRouter({
1437
1452
  boards: config.boards.map((board) => ({ id: board.id, title: board.title })),
1438
1453
  })
1439
1454
  })
1455
+ // The owner's Usage view (Console > Usage): the turns agents ran on this
1456
+ // computer, from the usage log. An owner device only, like the feedback.
1457
+ router.get('/usage', reviewAllowed, (req, res) => {
1458
+ const days = Math.min(365, Math.max(1, Number.parseInt(req.query.days, 10) || 30))
1459
+ res.json(summarizeLocalUsage(config, { days }))
1460
+ })
1440
1461
  router.get('/feedback/export', reviewAllowed, (req, res) => {
1441
1462
  const data = exportRatings(config)
1442
1463
  res.setHeader('Content-Disposition', `attachment; filename="shapewall-agent-feedback-${data.exportedAt.slice(0, 10)}.json"`)