agent-canvas 0.9.0-dev.7 → 0.9.0-dev.8

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 (81) hide show
  1. package/README.md +10 -0
  2. package/bin/lib/commands/review-remote.ts +186 -0
  3. package/bin/lib/commands/review.ts +88 -25
  4. package/bin/lib/instructions/app-review.md +31 -0
  5. package/daemon/build.ts +2 -0
  6. package/daemon/dist/review.js +3 -3
  7. package/daemon/review-widget/client.ts +16 -1
  8. package/daemon/review-widget/index.tsx +69 -11
  9. package/daemon/review-widget/remote-client.ts +117 -0
  10. package/daemon/review-widget/widget.tsx +3 -9
  11. package/daemon/src/review/model.ts +0 -5
  12. package/daemon/src/review/remote.ts +112 -0
  13. package/daemon/src/review/sealing.ts +35 -0
  14. package/daemon/src/review/server.ts +2 -1
  15. package/daemon/src/review/store.ts +16 -35
  16. package/daemon/src/review/threads.ts +63 -0
  17. package/package.json +23 -6
  18. package/skills/canvas/SKILL.md +2 -1
  19. package/types/bin/agent-canvas.d.ts +2 -0
  20. package/types/bin/lib/commands/daemon.d.ts +1 -0
  21. package/types/bin/lib/commands/exec.d.ts +7 -0
  22. package/types/bin/lib/commands/fetch.d.ts +1 -0
  23. package/types/bin/lib/commands/install.d.ts +1 -0
  24. package/types/bin/lib/commands/instructions.d.ts +1 -0
  25. package/types/bin/lib/commands/push.d.ts +1 -0
  26. package/types/bin/lib/commands/review-remote.d.ts +52 -0
  27. package/types/bin/lib/commands/review.d.ts +1 -0
  28. package/types/bin/lib/commands/watch.d.ts +1 -0
  29. package/types/bin/lib/config.d.ts +9 -0
  30. package/types/bin/lib/daemon-lifecycle.d.ts +4 -0
  31. package/types/bin/lib/helpers.d.ts +13 -0
  32. package/types/daemon/build.d.ts +1 -0
  33. package/types/daemon/client/App.d.ts +1 -0
  34. package/types/daemon/client/CompareView.d.ts +17 -0
  35. package/types/daemon/client/FileBrowser.d.ts +4 -0
  36. package/types/daemon/client/FileViewer.d.ts +6 -0
  37. package/types/daemon/client/OverviewView.d.ts +18 -0
  38. package/types/daemon/client/ReviewerIdentityDialog.d.ts +17 -0
  39. package/types/daemon/client/RevisionSelect.d.ts +10 -0
  40. package/types/daemon/client/SessionSwitcher.d.ts +6 -0
  41. package/types/daemon/client/ShareDialog.d.ts +30 -0
  42. package/types/daemon/client/apiSchemas.d.ts +1311 -0
  43. package/types/daemon/client/canvas-runtime.d.ts +1 -0
  44. package/types/daemon/client/clientApi.d.ts +112 -0
  45. package/types/daemon/client/components/SecretInput.d.ts +10 -0
  46. package/types/daemon/client/components/index.d.ts +2 -0
  47. package/types/daemon/client/domDiff.d.ts +37 -0
  48. package/types/daemon/client/errorMessage.d.ts +1 -0
  49. package/types/daemon/client/exportMarkdown.d.ts +1 -0
  50. package/types/daemon/client/lcs.d.ts +2 -0
  51. package/types/daemon/client/shareCrypto.d.ts +40 -0
  52. package/types/daemon/client/unifiedDiff.d.ts +26 -0
  53. package/types/daemon/langMap.d.ts +2 -0
  54. package/types/daemon/review-widget/anchor.d.ts +18 -0
  55. package/types/daemon/review-widget/browser.d.ts +6 -0
  56. package/types/daemon/review-widget/client.d.ts +38 -0
  57. package/types/daemon/review-widget/index.d.ts +1 -0
  58. package/types/daemon/review-widget/markup.d.ts +4 -0
  59. package/types/daemon/review-widget/remote-client.d.ts +29 -0
  60. package/types/daemon/review-widget/screenshot.d.ts +8 -0
  61. package/types/daemon/review-widget/source.d.ts +17 -0
  62. package/types/daemon/review-widget/style.d.ts +7 -0
  63. package/types/daemon/review-widget/widget.d.ts +7 -0
  64. package/types/daemon/src/components.d.ts +10 -0
  65. package/types/daemon/src/handlers/api.d.ts +11 -0
  66. package/types/daemon/src/handlers/files.d.ts +3 -0
  67. package/types/daemon/src/handlers/static.d.ts +2 -0
  68. package/types/daemon/src/handlers/uploads.d.ts +3 -0
  69. package/types/daemon/src/paths.d.ts +12 -0
  70. package/types/daemon/src/remote-feedback.d.ts +4 -0
  71. package/types/daemon/src/review/markdown.d.ts +3 -0
  72. package/types/daemon/src/review/model.d.ts +1089 -0
  73. package/types/daemon/src/review/proxy.d.ts +30 -0
  74. package/types/daemon/src/review/remote.d.ts +258 -0
  75. package/types/daemon/src/review/sealing.d.ts +11 -0
  76. package/types/daemon/src/review/server.d.ts +24 -0
  77. package/types/daemon/src/review/store.d.ts +34 -0
  78. package/types/daemon/src/review/threads.d.ts +35 -0
  79. package/types/daemon/src/server.d.ts +7 -0
  80. package/types/daemon/src/share.d.ts +98 -0
  81. package/types/daemon/src/stubFetch.d.ts +2 -0
@@ -31,8 +31,23 @@ function readFrame(data: unknown): ReviewBrowserFrame | undefined {
31
31
  return parsed.success ? { type: 'threads', threads: parsed.data.threads } : undefined
32
32
  }
33
33
 
34
+ /** Where the widget keeps threads: the local daemon, or a remote project on the share worker. */
35
+ export interface ReviewClient {
36
+ /** The presence label while the widget cannot reach its store. */
37
+ readonly offlineLabel: string
38
+ connect(events: ReviewEvents): void
39
+ close(): void
40
+ createThread(anchor: ReviewAnchor, body: string, send: boolean, screenshot?: string): Promise<unknown>
41
+ comment(threadId: string, body: string, send: boolean): Promise<unknown>
42
+ send(threadId: string): Promise<unknown>
43
+ sendNotes(): Promise<unknown>
44
+ setResolved(threadId: string, resolved: boolean): Promise<unknown>
45
+ delete(threadId: string): Promise<unknown>
46
+ }
47
+
34
48
  /** The widget's side of the daemon: thread mutations over HTTP, the thread list and agent presence over a WebSocket. */
35
- export class ReviewClient {
49
+ export class DaemonReviewClient implements ReviewClient {
50
+ readonly offlineLabel = 'Daemon offline'
36
51
  private socket: WebSocket | null = null
37
52
  private closed = false
38
53
 
@@ -1,21 +1,50 @@
1
1
  import { render } from 'preact'
2
+ import { importShareKey } from '../client/shareCrypto'
2
3
  import { PROJECT_RE } from '../src/review/model'
3
- import { ReviewClient } from './client'
4
+ import { formatReviewCredentials, parseReviewCredentials, REVIEW_FRAGMENT_PARAM, type ReviewCredentials } from '../src/review/remote'
5
+ import { DaemonReviewClient, type ReviewClient } from './client'
6
+ import { RemoteReviewClient } from './remote-client'
4
7
  import styles from './styles.css' with { type: 'text' }
5
8
  import { ReviewWidget } from './widget'
6
9
 
7
10
  const HOST_TAG = 'agent-canvas-review'
11
+ const REMOTE_KEY = 'agent-canvas-review:remote'
12
+ const FORGET = 'off'
8
13
 
9
14
  /**
10
- * `<script src="http://localhost:19400/assets/review.js" data-project="my-app"></script>` in the application under
11
- * review mounts the widget. Its own origin is the daemon's.
15
+ * The reviewer's link carries the remote project and its key in the fragment, which never reaches a server. The page
16
+ * keeps them for its origin, so navigation and later visits keep the widget; `#agent-canvas-review=off` forgets them.
12
17
  */
13
- function mount(script: HTMLScriptElement): void {
14
- const project = script.dataset['project'] ?? ''
15
- if (!PROJECT_RE.test(project)) {
16
- console.error(`agent-canvas review: data-project must match ${PROJECT_RE}, got "${project}"`)
17
- return
18
+ function takeRemoteCredentials(): ReviewCredentials | null {
19
+ const fromLink = new URLSearchParams(location.hash.slice(1)).get(REVIEW_FRAGMENT_PARAM)
20
+ if (fromLink !== null) {
21
+ // The key must not stay in the address bar, the history, or the page URL a thread records.
22
+ history.replaceState(history.state, '', `${location.pathname}${location.search}`)
23
+ if (fromLink === FORGET) {
24
+ try {
25
+ localStorage.removeItem(REMOTE_KEY)
26
+ } catch {}
27
+ return null
28
+ }
29
+ const credentials = parseReviewCredentials(fromLink)
30
+ if (credentials === null) {
31
+ console.error('agent-canvas review: the review link is malformed')
32
+ return null
33
+ }
34
+ try {
35
+ localStorage.setItem(REMOTE_KEY, formatReviewCredentials(credentials))
36
+ } catch {}
37
+ return credentials
38
+ }
39
+ try {
40
+ const stored = localStorage.getItem(REMOTE_KEY)
41
+ return stored === null ? null : parseReviewCredentials(stored)
42
+ } catch {
43
+ return null
18
44
  }
45
+ }
46
+
47
+ function mountWidget(client: ReviewClient): void {
19
48
  if (document.querySelector(HOST_TAG) !== null) return
20
49
 
21
50
  const pageStyle = document.createElement('style')
@@ -28,9 +57,38 @@ function mount(script: HTMLScriptElement): void {
28
57
  const style = document.createElement('style')
29
58
  style.textContent = styles
30
59
  root.append(style)
31
- render(<ReviewWidget client={new ReviewClient(new URL(script.src).origin, project)} host={host} />, root)
60
+ render(<ReviewWidget client={client} host={host} />, root)
61
+ }
62
+
63
+ /**
64
+ * - `<script src="http://localhost:19400/assets/review.js" data-project="my-app"></script>`: the local daemon keeps the
65
+ * threads.
66
+ * - `<script src="https://<share worker>/assets/review.js"></script>`: a remote project on the share worker, mounted
67
+ * only for a reviewer who opened its link.
68
+ */
69
+ async function mount(script: HTMLScriptElement): Promise<void> {
70
+ const origin = new URL(script.src).origin
71
+ const project = script.dataset['project']
72
+ if (project !== undefined) {
73
+ if (!PROJECT_RE.test(project)) {
74
+ console.error(`agent-canvas review: data-project must match ${PROJECT_RE}, got "${project}"`)
75
+ return
76
+ }
77
+ mountWidget(new DaemonReviewClient(origin, project))
78
+ return
79
+ }
80
+ const credentials = takeRemoteCredentials()
81
+ if (credentials === null) return
82
+ mountWidget(new RemoteReviewClient(origin, credentials.projectId, await importShareKey(credentials.key)))
32
83
  }
33
84
 
34
85
  const script = document.currentScript
35
- if (script instanceof HTMLScriptElement) mount(script)
36
- else console.error('agent-canvas review: load review.js with a classic <script> tag')
86
+ if (script instanceof HTMLScriptElement) {
87
+ void mount(script)
88
+ // A link opened on a page already showing loads no new document; reloading lets it mount or forget the project.
89
+ if (script.dataset['project'] === undefined) {
90
+ window.addEventListener('hashchange', () => {
91
+ if (new URLSearchParams(location.hash.slice(1)).has(REVIEW_FRAGMENT_PARAM)) location.reload()
92
+ })
93
+ }
94
+ } else console.error('agent-canvas review: load review.js with a classic <script> tag')
@@ -0,0 +1,117 @@
1
+ import { z } from 'zod'
2
+ import type { ReviewAnchor, ReviewThread } from '../src/review/model'
3
+ import { KEEPALIVE_PING, type SealedThread, sealedThreadSchema, sealedThreadsSchema } from '../src/review/remote'
4
+ import { openThread, sealAnchor, sealText } from '../src/review/sealing'
5
+ import type { ReviewClient, ReviewEvents } from './client'
6
+
7
+ const KEEPALIVE_MS = 30_000
8
+
9
+ const frameSchema = z.discriminatedUnion('type', [
10
+ z.object({ type: z.literal('threads'), threads: z.array(sealedThreadSchema) }),
11
+ z.object({ type: z.literal('agent-status'), watching: z.boolean() }),
12
+ ])
13
+ const errorSchema = z.object({ error: z.string() })
14
+
15
+ /**
16
+ * The widget's side of a remote review project on the share worker. Everything the reviewer writes is sealed with the
17
+ * project key before it leaves the page, and every thread the worker sends is opened here.
18
+ */
19
+ export class RemoteReviewClient implements ReviewClient {
20
+ readonly offlineLabel = 'Offline'
21
+ private socket: WebSocket | null = null
22
+ private keepalive: ReturnType<typeof setInterval> | null = null
23
+ private closed = false
24
+ /** Opening threads is asynchronous; only the newest list may reach the widget. */
25
+ private generation = 0
26
+
27
+ constructor(private readonly workerOrigin: string, private readonly projectId: string, private readonly key: CryptoKey) {}
28
+
29
+ connect(events: ReviewEvents): void {
30
+ const socket = new WebSocket(`${this.workerOrigin.replace(/^http/, 'ws')}/review/${this.projectId}/ws`)
31
+ this.socket = socket
32
+ socket.onopen = () => {
33
+ events.connected(true)
34
+ this.keepalive = setInterval(() => socket.send(KEEPALIVE_PING), KEEPALIVE_MS)
35
+ void this.request('GET', '/threads').then((body) => this.publish(sealedThreadsSchema.parse(body).threads, events))
36
+ }
37
+ socket.onmessage = (event) => {
38
+ if (typeof event.data !== 'string' || event.data === 'pong') return
39
+ let data: unknown
40
+ try {
41
+ data = JSON.parse(event.data)
42
+ } catch {
43
+ return
44
+ }
45
+ const frame = frameSchema.safeParse(data)
46
+ if (!frame.success) return
47
+ if (frame.data.type === 'threads') this.publish(frame.data.threads, events)
48
+ else events.agentWatching(frame.data.watching)
49
+ }
50
+ socket.onclose = () => {
51
+ if (this.keepalive !== null) clearInterval(this.keepalive)
52
+ events.connected(false)
53
+ if (!this.closed) setTimeout(() => this.connect(events), 2000)
54
+ }
55
+ }
56
+
57
+ close(): void {
58
+ this.closed = true
59
+ this.socket?.close()
60
+ }
61
+
62
+ async createThread(anchor: ReviewAnchor, body: string, send: boolean, screenshot?: string): Promise<unknown> {
63
+ return this.request('POST', '/threads', {
64
+ anchor: await sealAnchor(this.key, anchor),
65
+ body: await sealText(this.key, body),
66
+ send,
67
+ ...(screenshot === undefined ? {} : { screenshot: await sealText(this.key, screenshot) }),
68
+ })
69
+ }
70
+
71
+ async comment(threadId: string, body: string, send: boolean): Promise<unknown> {
72
+ return this.request('POST', `/threads/${threadId}/comments`, { body: await sealText(this.key, body), send })
73
+ }
74
+
75
+ send(threadId: string): Promise<unknown> {
76
+ return this.request('POST', `/threads/${threadId}/send`)
77
+ }
78
+
79
+ sendNotes(): Promise<unknown> {
80
+ return this.request('POST', '/notes/send')
81
+ }
82
+
83
+ setResolved(threadId: string, resolved: boolean): Promise<unknown> {
84
+ return this.request('POST', `/threads/${threadId}/${resolved ? 'resolve' : 'reopen'}`)
85
+ }
86
+
87
+ delete(threadId: string): Promise<unknown> {
88
+ return this.request('DELETE', `/threads/${threadId}`)
89
+ }
90
+
91
+ /** A thread that does not open was not sealed with this project's key; the reviewer never sees it. */
92
+ private publish(sealed: readonly SealedThread[], events: ReviewEvents): void {
93
+ const generation = ++this.generation
94
+ void Promise.allSettled(sealed.map((thread) => openThread(this.key, thread))).then((results) => {
95
+ if (generation !== this.generation) return
96
+ const threads: ReviewThread[] = []
97
+ for (const result of results) {
98
+ if (result.status === 'fulfilled') threads.push(result.value)
99
+ else console.warn('agent-canvas review: a thread did not open with this project key')
100
+ }
101
+ events.threads(threads)
102
+ })
103
+ }
104
+
105
+ private async request(method: string, path: string, body?: unknown): Promise<unknown> {
106
+ const response = await fetch(`${this.workerOrigin}/review/${this.projectId}${path}`, {
107
+ method,
108
+ ...(body === undefined ? {} : { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }),
109
+ })
110
+ const result: unknown = await response.json()
111
+ if (!response.ok) {
112
+ const error = errorSchema.safeParse(result)
113
+ throw new Error(error.success ? error.data.error : `Request failed (${response.status})`)
114
+ }
115
+ return result
116
+ }
117
+ }
@@ -1,13 +1,7 @@
1
1
  import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks'
2
2
  import { z } from 'zod'
3
- import {
4
- isUnsentNote,
5
- type ReviewAnchor,
6
- reviewAnchorSchema,
7
- type ReviewSource,
8
- type ReviewThread,
9
- type ReviewThreadState,
10
- } from '../src/review/model'
3
+ import { type ReviewAnchor, reviewAnchorSchema, type ReviewSource, type ReviewThread, type ReviewThreadState } from '../src/review/model'
4
+ import { isUnsentNote } from '../src/review/threads'
11
5
  import { describe, find } from './anchor'
12
6
  import type { ReviewClient } from './client'
13
7
  import { captureElement } from './screenshot'
@@ -450,7 +444,7 @@ export function ReviewWidget(props: { client: ReviewClient; host: HTMLElement })
450
444
  if (pageKey(thread.anchor.url) !== page) navigate(thread.anchor.url, thread.id)
451
445
  }
452
446
 
453
- const presence = !connected ? 'Daemon offline' : watching ? 'Claude is listening' : 'Claude is not listening'
447
+ const presence = !connected ? client.offlineLabel : watching ? 'Claude is listening' : 'Claude is not listening'
454
448
  const hoveredBox = hovered === null ? null : boxOf(hovered)
455
449
 
456
450
  return (
@@ -102,11 +102,6 @@ export const reviewThreadSchema = z.object({
102
102
  })
103
103
  export type ReviewThread = z.infer<typeof reviewThreadSchema>
104
104
 
105
- /** A note the person saved and has not sent: open, with their own comment last rather than the agent's answer. */
106
- export function isUnsentNote(thread: ReviewThread): boolean {
107
- return thread.state === 'open' && thread.comments.at(-1)?.author === 'user'
108
- }
109
-
110
105
  export const reviewThreadsFileSchema = z.object({ threads: z.array(reviewThreadSchema) })
111
106
 
112
107
  const commentBody = z.string().trim().min(1).max(20_000)
@@ -0,0 +1,112 @@
1
+ import { z } from 'zod'
2
+ import { reviewAuthorSchema, reviewThreadStateSchema } from './model'
3
+
4
+ /**
5
+ * Remote review: the threads of an application deployed somewhere else, kept by the share worker. The reviewer's
6
+ * browser and the agent's CLI share a key the worker never sees, so the worker stores and relays ciphertext. It reads
7
+ * only what moves a thread through its lifecycle: ids, states, comment authors and timestamps.
8
+ */
9
+
10
+ /** The worker's name for a remote project: 12 random bytes, hex. Knowing it, from an allowed origin, lets a browser write. */
11
+ export const REMOTE_PROJECT_ID_RE = /^[a-f0-9]{24}$/
12
+
13
+ /** The fragment that hands a reviewer the project and its key: `#agent-canvas-review=<projectId>.<key>`. */
14
+ export const REVIEW_FRAGMENT_PARAM = 'agent-canvas-review'
15
+
16
+ export const MAX_ORIGINS = 5
17
+ export const MAX_THREADS = 1000
18
+ export const MAX_COMMENTS = 200
19
+ /** Ciphertext limits: base64 of AES-GCM over the plaintext limits in `model.ts`, with room for multi-byte UTF-8. */
20
+ export const MAX_SEALED_ANCHOR = 160_000
21
+ export const MAX_SEALED_BODY = 110_000
22
+ export const MAX_SEALED_SCREENSHOT = 11_000_000
23
+
24
+ /** `shareCrypto` packing: base64(IV || ciphertext || tag). */
25
+ function sealed(max: number) {
26
+ return z.string().min(1).max(max).regex(/^[A-Za-z0-9+/]+={0,2}$/, 'must be base64 ciphertext')
27
+ }
28
+
29
+ /** A deployed application's origin, or one on this machine for trying the setup out. */
30
+ export const reviewOriginSchema = z.string().refine((value) => {
31
+ let url: URL
32
+ try {
33
+ url = new URL(value)
34
+ } catch {
35
+ return false
36
+ }
37
+ if (url.origin !== value) return false
38
+ if (url.protocol === 'https:') return true
39
+ return url.protocol === 'http:' && (url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname.endsWith('.localhost'))
40
+ }, 'must be an origin such as https://app.example.com')
41
+
42
+ export const sealedCommentSchema = z.object({
43
+ id: z.string().max(64),
44
+ author: reviewAuthorSchema,
45
+ body: sealed(MAX_SEALED_BODY),
46
+ createdAt: z.string().max(64),
47
+ })
48
+ export type SealedComment = z.infer<typeof sealedCommentSchema>
49
+
50
+ export const sealedThreadSchema = z.object({
51
+ id: z.string().max(64),
52
+ /** The `ReviewAnchor` as JSON, sealed. */
53
+ anchor: sealed(MAX_SEALED_ANCHOR),
54
+ state: reviewThreadStateSchema,
55
+ comments: z.array(sealedCommentSchema).min(1).max(MAX_COMMENTS),
56
+ /** Whether the reviewer attached a screenshot; the agent fetches it separately. */
57
+ screenshot: z.boolean(),
58
+ createdAt: z.string().max(64),
59
+ updatedAt: z.string().max(64),
60
+ })
61
+ export type SealedThread = z.infer<typeof sealedThreadSchema>
62
+
63
+ export const sealedThreadsSchema = z.object({ threads: z.array(sealedThreadSchema) })
64
+
65
+ export const createRemoteProjectBodySchema = z.object({ origins: z.array(reviewOriginSchema).min(1).max(MAX_ORIGINS) })
66
+ export const createRemoteProjectResponseSchema = z.object({ projectId: z.string().regex(REMOTE_PROJECT_ID_RE), agentToken: z.string().min(32) })
67
+
68
+ export const sealedCreateThreadBodySchema = z.object({
69
+ anchor: sealed(MAX_SEALED_ANCHOR),
70
+ body: sealed(MAX_SEALED_BODY),
71
+ send: z.boolean(),
72
+ /** The PNG data URL, sealed. */
73
+ screenshot: sealed(MAX_SEALED_SCREENSHOT).optional(),
74
+ })
75
+ export const sealedCommentBodySchema = z.object({ body: sealed(MAX_SEALED_BODY), send: z.boolean() })
76
+ export const sealedAgentReplyBodySchema = z.object({ body: sealed(MAX_SEALED_BODY), resolve: z.boolean() })
77
+ export const sealedScreenshotSchema = z.object({ screenshot: sealed(MAX_SEALED_SCREENSHOT) })
78
+
79
+ /** Frames the worker sends to a project's browsers. */
80
+ export type RemoteBrowserFrame =
81
+ | { type: 'threads'; threads: readonly SealedThread[] }
82
+ | { type: 'agent-status'; watching: boolean }
83
+
84
+ /** Sockets send this to keep an idle connection open; the worker answers `pong` without waking the project. */
85
+ export const KEEPALIVE_PING = 'ping'
86
+ export const KEEPALIVE_PONG = 'pong'
87
+
88
+ export interface ReviewCredentials {
89
+ projectId: string
90
+ /** The base64url AES-GCM key, as `exportShareKey` writes it. */
91
+ key: string
92
+ }
93
+
94
+ const KEY_RE = /^[A-Za-z0-9_-]{43}$/
95
+
96
+ /** `<projectId>.<key>`, the value of the fragment parameter. */
97
+ export function formatReviewCredentials(credentials: ReviewCredentials): string {
98
+ return `${credentials.projectId}.${credentials.key}`
99
+ }
100
+
101
+ export function parseReviewCredentials(value: string): ReviewCredentials | null {
102
+ const [projectId, key, ...rest] = value.split('.')
103
+ if (projectId === undefined || key === undefined || rest.length > 0) return null
104
+ if (!REMOTE_PROJECT_ID_RE.test(projectId) || !KEY_RE.test(key)) return null
105
+ return { projectId, key }
106
+ }
107
+
108
+ /**
109
+ * A WebSocket client cannot always set headers, so the agent's wait socket offers its token as a second subprotocol:
110
+ * `[AGENT_SOCKET_PROTOCOL, <agent token>]`. The worker answers with the first one only.
111
+ */
112
+ export const AGENT_SOCKET_PROTOCOL = 'agent-canvas-review'
@@ -0,0 +1,35 @@
1
+ import { decryptString, encryptString } from '../../client/shareCrypto'
2
+ import { type ReviewAnchor, reviewAnchorSchema, type ReviewThread, reviewThreadSchema } from './model'
3
+ import type { SealedThread } from './remote'
4
+
5
+ /** What the reviewer's browser and the agent's CLI seal before a remote project's worker sees it, and open after. */
6
+
7
+ export function sealAnchor(key: CryptoKey, anchor: ReviewAnchor): Promise<string> {
8
+ return encryptString(key, JSON.stringify(anchor))
9
+ }
10
+
11
+ export function sealText(key: CryptoKey, text: string): Promise<string> {
12
+ return encryptString(key, text)
13
+ }
14
+
15
+ export function openText(key: CryptoKey, sealed: string): Promise<string> {
16
+ return decryptString(key, sealed)
17
+ }
18
+
19
+ /**
20
+ * Opens a thread into the shape the widget and the agent read. A thread that does not decrypt with the key or does not
21
+ * parse once open was not sealed by this project's browser or CLI; it throws.
22
+ */
23
+ export async function openThread(key: CryptoKey, thread: SealedThread, screenshot?: string): Promise<ReviewThread> {
24
+ const anchor: unknown = JSON.parse(await decryptString(key, thread.anchor))
25
+ const comments = await Promise.all(thread.comments.map(async (comment) => ({ ...comment, body: await decryptString(key, comment.body) })))
26
+ return reviewThreadSchema.parse({
27
+ id: thread.id,
28
+ anchor: reviewAnchorSchema.parse(anchor),
29
+ state: thread.state,
30
+ comments,
31
+ ...(screenshot === undefined ? {} : { screenshot }),
32
+ createdAt: thread.createdAt,
33
+ updatedAt: thread.updatedAt,
34
+ })
35
+ }
@@ -12,7 +12,8 @@ import {
12
12
  type ReviewWaitFrame,
13
13
  } from './model'
14
14
  import type { ReviewProxies } from './proxy'
15
- import { ReviewError, type ReviewStore } from './store'
15
+ import type { ReviewStore } from './store'
16
+ import { ReviewError } from './threads'
16
17
 
17
18
  export interface ReviewSocketData {
18
19
  type: 'review'
@@ -1,22 +1,16 @@
1
1
  import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs'
2
2
  import { join } from 'path'
3
3
  import {
4
- isUnsentNote,
5
4
  PROJECT_RE,
6
5
  type ReviewAnchor,
7
6
  type ReviewAuthor,
7
+ type ReviewComment,
8
8
  type ReviewProxy,
9
9
  reviewProxySchema,
10
10
  type ReviewThread,
11
11
  reviewThreadsFileSchema,
12
- type ReviewThreadState,
13
12
  } from './model'
14
-
15
- export class ReviewError extends Error {
16
- constructor(message: string, readonly status: 400 | 404 | 409) {
17
- super(message)
18
- }
19
- }
13
+ import { agentReplied, claimed, notesSent, openingState, resolvedAs, ReviewError, sent, userCommented } from './threads'
20
14
 
21
15
  /**
22
16
  * Review threads of each project: `<directory>/<project>/threads.json`, attached screenshots beside it, and the
@@ -37,7 +31,7 @@ export class ReviewStore {
37
31
  const thread: ReviewThread = {
38
32
  id,
39
33
  anchor,
40
- state: send ? 'queued' : 'open',
34
+ state: openingState(send),
41
35
  comments: [{ id: Bun.randomUUIDv7(), author: 'user', body, createdAt }],
42
36
  ...(screenshot === undefined ? {} : { screenshot: this.writeScreenshot(project, id, screenshot) }),
43
37
  createdAt,
@@ -49,31 +43,22 @@ export class ReviewStore {
49
43
 
50
44
  /** A comment from the person reopens a resolved thread; with `send` it goes to the agent. */
51
45
  addUserComment(project: string, threadId: string, body: string, send: boolean): ReviewThread {
52
- return this.update(project, threadId, (thread) => {
53
- const state: ReviewThreadState = send ? 'queued' : thread.state === 'resolved' ? 'open' : thread.state
54
- return { ...this.withComment(thread, 'user', body), state }
55
- })
46
+ return this.update(project, threadId, (thread) => userCommented(thread, this.comment('user', body), send))
56
47
  }
57
48
 
58
49
  send(project: string, threadId: string): ReviewThread {
59
- return this.update(project, threadId, (thread) => {
60
- if (thread.state === 'working') throw new ReviewError('The agent is already working on this thread', 409)
61
- return { ...thread, state: 'queued', updatedAt: this.timestamp() }
62
- })
50
+ return this.update(project, threadId, (thread) => sent(thread, this.timestamp()))
63
51
  }
64
52
 
65
53
  /** Sends every unsent note at once, so the agent picks them up as one batch. */
66
54
  sendNotes(project: string): readonly ReviewThread[] {
67
- const threads = this.list(project)
68
- const updatedAt = this.timestamp()
69
- const sent = threads.filter(isUnsentNote).map((thread): ReviewThread => ({ ...thread, state: 'queued', updatedAt }))
70
- const sentById = new Map(sent.map((thread) => [thread.id, thread]))
71
- this.save(project, threads.map((thread) => sentById.get(thread.id) ?? thread))
72
- return sent
55
+ const result = notesSent(this.list(project), this.timestamp())
56
+ this.save(project, result.threads)
57
+ return result.sent
73
58
  }
74
59
 
75
60
  setResolved(project: string, threadId: string, resolved: boolean): ReviewThread {
76
- return this.update(project, threadId, (thread) => ({ ...thread, state: resolved ? 'resolved' : 'open', updatedAt: this.timestamp() }))
61
+ return this.update(project, threadId, (thread) => resolvedAs(thread, resolved, this.timestamp()))
77
62
  }
78
63
 
79
64
  delete(project: string, threadId: string): void {
@@ -86,18 +71,15 @@ export class ReviewStore {
86
71
 
87
72
  /** Hands every queued thread to the agent: they become `working` and are returned in creation order. */
88
73
  claimQueued(project: string): readonly ReviewThread[] {
89
- const threads = this.list(project)
90
- const claimed = threads.filter((thread) => thread.state === 'queued')
91
- if (claimed.length === 0) return []
92
- const updatedAt = this.timestamp()
93
- const claimedIds = new Set(claimed.map((thread) => thread.id))
94
- this.save(project, threads.map((thread) => (claimedIds.has(thread.id) ? { ...thread, state: 'working', updatedAt } : thread)))
95
- return claimed.map((thread) => ({ ...thread, state: 'working', updatedAt }))
74
+ const result = claimed(this.list(project), this.timestamp())
75
+ if (result.claimed.length === 0) return []
76
+ this.save(project, result.threads)
77
+ return result.claimed
96
78
  }
97
79
 
98
80
  /** The agent's answer. Without `resolve` the thread goes back to the person as `open`. */
99
81
  agentReply(project: string, threadId: string, body: string, resolve: boolean): ReviewThread {
100
- return this.update(project, threadId, (thread) => ({ ...this.withComment(thread, 'agent', body), state: resolve ? 'resolved' : 'open' }))
82
+ return this.update(project, threadId, (thread) => agentReplied(thread, this.comment('agent', body), resolve))
101
83
  }
102
84
 
103
85
  proxyOf(project: string): ReviewProxy | undefined {
@@ -125,9 +107,8 @@ export class ReviewStore {
125
107
  return next
126
108
  }
127
109
 
128
- private withComment(thread: ReviewThread, author: ReviewAuthor, body: string): ReviewThread {
129
- const createdAt = this.timestamp()
130
- return { ...thread, comments: [...thread.comments, { id: Bun.randomUUIDv7(), author, body, createdAt }], updatedAt: createdAt }
110
+ private comment(author: ReviewAuthor, body: string): ReviewComment {
111
+ return { id: Bun.randomUUIDv7(), author, body, createdAt: this.timestamp() }
131
112
  }
132
113
 
133
114
  private writeScreenshot(project: string, threadId: string, png: Uint8Array): string {
@@ -0,0 +1,63 @@
1
+ import type { ReviewComment, ReviewThreadState } from './model'
2
+
3
+ /**
4
+ * The thread lifecycle, shared by the daemon's file store and the share worker's encrypted store. It reads and writes
5
+ * only state, comments and timestamps; the anchor and the screenshot are each store's own, so a comment body here may be
6
+ * plaintext or ciphertext.
7
+ */
8
+
9
+ export class ReviewError extends Error {
10
+ constructor(message: string, readonly status: 400 | 404 | 409) {
11
+ super(message)
12
+ }
13
+ }
14
+
15
+ export interface ThreadCore {
16
+ id: string
17
+ state: ReviewThreadState
18
+ comments: ReviewComment[]
19
+ updatedAt: string
20
+ }
21
+
22
+ /** A note the person saved and has not sent: open, with their own comment last rather than the agent's answer. */
23
+ export function isUnsentNote(thread: ThreadCore): boolean {
24
+ return thread.state === 'open' && thread.comments.at(-1)?.author === 'user'
25
+ }
26
+
27
+ export function openingState(send: boolean): ReviewThreadState {
28
+ return send ? 'queued' : 'open'
29
+ }
30
+
31
+ /** A comment from the person reopens a resolved thread; with `send` it goes to the agent. */
32
+ export function userCommented<T extends ThreadCore>(thread: T, comment: ReviewComment, send: boolean): T {
33
+ const state: ReviewThreadState = send ? 'queued' : thread.state === 'resolved' ? 'open' : thread.state
34
+ return { ...thread, comments: [...thread.comments, comment], state, updatedAt: comment.createdAt }
35
+ }
36
+
37
+ export function sent<T extends ThreadCore>(thread: T, now: string): T {
38
+ if (thread.state === 'working') throw new ReviewError('The agent is already working on this thread', 409)
39
+ return { ...thread, state: 'queued', updatedAt: now }
40
+ }
41
+
42
+ /** Sends every unsent note at once, so the agent picks them up as one batch. */
43
+ export function notesSent<T extends ThreadCore>(threads: readonly T[], now: string): { threads: T[]; sent: T[] } {
44
+ const sentNotes = threads.filter(isUnsentNote).map((thread): T => ({ ...thread, state: 'queued', updatedAt: now }))
45
+ const sentById = new Map(sentNotes.map((thread) => [thread.id, thread]))
46
+ return { threads: threads.map((thread) => sentById.get(thread.id) ?? thread), sent: sentNotes }
47
+ }
48
+
49
+ export function resolvedAs<T extends ThreadCore>(thread: T, resolved: boolean, now: string): T {
50
+ return { ...thread, state: resolved ? 'resolved' : 'open', updatedAt: now }
51
+ }
52
+
53
+ /** Hands every queued thread to the agent: they become `working` and are returned in their original order. */
54
+ export function claimed<T extends ThreadCore>(threads: readonly T[], now: string): { threads: T[]; claimed: T[] } {
55
+ const taken = threads.filter((thread) => thread.state === 'queued').map((thread): T => ({ ...thread, state: 'working', updatedAt: now }))
56
+ const takenById = new Map(taken.map((thread) => [thread.id, thread]))
57
+ return { threads: threads.map((thread) => takenById.get(thread.id) ?? thread), claimed: taken }
58
+ }
59
+
60
+ /** The agent's answer. Without `resolve` the thread goes back to the person as `open`. */
61
+ export function agentReplied<T extends ThreadCore>(thread: T, comment: ReviewComment, resolve: boolean): T {
62
+ return { ...thread, comments: [...thread.comments, comment], state: resolve ? 'resolved' : 'open', updatedAt: comment.createdAt }
63
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-canvas",
3
- "version": "0.9.0-dev.7",
3
+ "version": "0.9.0-dev.8",
4
4
  "description": "Interactive visual canvas for Claude Code — rich annotatable documents in the browser",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -18,10 +18,27 @@
18
18
  "bin",
19
19
  "daemon",
20
20
  "daemon/dist",
21
- "skills"
21
+ "skills",
22
+ "types"
22
23
  ],
23
24
  "exports": {
24
- "./package.json": "./package.json"
25
+ "./package.json": "./package.json",
26
+ "./review/model": {
27
+ "types": "./types/daemon/src/review/model.d.ts",
28
+ "default": "./daemon/src/review/model.ts"
29
+ },
30
+ "./review/remote": {
31
+ "types": "./types/daemon/src/review/remote.d.ts",
32
+ "default": "./daemon/src/review/remote.ts"
33
+ },
34
+ "./review/sealing": {
35
+ "types": "./types/daemon/src/review/sealing.d.ts",
36
+ "default": "./daemon/src/review/sealing.ts"
37
+ },
38
+ "./review/threads": {
39
+ "types": "./types/daemon/src/review/threads.d.ts",
40
+ "default": "./daemon/src/review/threads.ts"
41
+ }
25
42
  },
26
43
  "scripts": {
27
44
  "build": "bun daemon/build.ts",
@@ -30,9 +47,9 @@
30
47
  "test": "bun test"
31
48
  },
32
49
  "dependencies": {
33
- "@fabrika/annotations": "0.9.0-dev.7",
34
- "@fabrika/canvas-kernel": "0.9.0-dev.7",
35
- "@fabrika/daemon-kit": "0.9.0-dev.7",
50
+ "@fabrika/annotations": "0.9.0-dev.8",
51
+ "@fabrika/canvas-kernel": "0.9.0-dev.8",
52
+ "@fabrika/daemon-kit": "0.9.0-dev.8",
36
53
  "@jridgewell/trace-mapping": "^0.3.31",
37
54
  "marked": "^17.0.4",
38
55
  "mermaid-parser-bundle": "^0.1.2",