agent-canvas 0.2.1 → 0.6.0

package/daemon/src/review/proxy.ts

@@ -0,0 +1,177 @@
+import type { ReviewStore } from './store'
+
+/** One browser socket proxied to the application, e.g. its dev server's hot reload. */
+interface ProxySocketData {
+	upstream: WebSocket
+	/** Frames the application sent before the browser's socket opened. */
+	early: Array<string | ArrayBuffer>
+	browser: Bun.ServerWebSocket<ProxySocketData> | null
+}
+
+type ProxyServer = Bun.Server<ProxySocketData>
+
+interface RunningProxy {
+	target: string
+	server: ProxyServer
+}
+
+/** Puts the widget's tag before `</body>`, or at the end of a document without one. */
+export function withWidget(html: string, tag: string): string {
+	const bodyEnd = html.toLowerCase().lastIndexOf('</body>')
+	return bodyEnd === -1 ? `${html}${tag}` : `${html.slice(0, bodyEnd)}${tag}${html.slice(bodyEnd)}`
+}
+
+function connectUpstream(url: URL, protocols: string[]): Promise<WebSocket> {
+	return new Promise((resolve, reject) => {
+		const socket = new WebSocket(url, protocols)
+		socket.binaryType = 'arraybuffer'
+		socket.onopen = () => resolve(socket)
+		socket.onerror = () => reject(new Error(`WebSocket ${url} failed`))
+	})
+}
+
+/**
+ * Review proxies: each project's application, served on a port of its own with the review widget added to every HTML
+ * page, so a reviewer opens a URL instead of editing the application. The proxy's origin is a loopback one, which the
+ * review routes accept; it forwards to applications on this machine only.
+ */
+export class ReviewProxies {
+	private readonly running = new Map<string, RunningProxy>()
+
+	constructor(private readonly store: ReviewStore, private readonly widgetScript: string) {}
+
+	/** Serves the project's application at `target` and returns where the reviewer opens it, `target`'s path kept. */
+	open(project: string, target: string): string {
+		const targetUrl = new URL(target)
+		const current = this.running.get(project)
+		if (current === undefined || current.target !== targetUrl.origin) {
+			const port = current?.server.port ?? this.store.proxyOf(project)?.port
+			current?.server.stop(true)
+			this.listen(project, targetUrl.origin, port)
+		}
+		const proxy = this.running.get(project)
+		if (proxy === undefined) throw new Error(`Review proxy for ${project} did not start`)
+		return `http://localhost:${proxy.server.port}${targetUrl.pathname}${targetUrl.search}${targetUrl.hash}`
+	}
+
+	/** Serves every proxy a previous daemon served, on the same ports. */
+	restore(): void {
+		for (const project of this.store.proxiedProjects()) {
+			try {
+				const proxy = this.store.proxyOf(project)
+				if (proxy !== undefined) this.listen(project, proxy.target, proxy.port)
+			} catch (error) {
+				console.error(`Review proxy for ${project} not restored: ${error instanceof Error ? error.message : String(error)}`)
+			}
+		}
+	}
+
+	stop(): void {
+		for (const proxy of this.running.values()) proxy.server.stop(true)
+		this.running.clear()
+	}
+
+	private listen(project: string, target: string, port: number | undefined): void {
+		let server: ProxyServer
+		try {
+			server = this.serve(project, target, port ?? 0)
+		} catch (error) {
+			if (port === undefined) throw error
+			// The previous port is taken; the reviewer opens the new URL the CLI prints.
+			server = this.serve(project, target, 0)
+		}
+		this.running.set(project, { target, server })
+		this.store.saveProxy(project, { target, port: server.port ?? 0 })
+	}
+
+	private serve(project: string, target: string, port: number): ProxyServer {
+		const widgetTag = `<script src="${this.widgetScript}" data-project="${project}"></script>`
+		return Bun.serve<ProxySocketData>({
+			port,
+			hostname: 'localhost',
+			fetch: async (req, server) => {
+				const url = new URL(req.url)
+				const upstreamUrl = new URL(`${url.pathname}${url.search}`, target)
+				if (req.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
+					upstreamUrl.protocol = upstreamUrl.protocol === 'https:' ? 'wss:' : 'ws:'
+					return await this.upgrade(req, server, upstreamUrl)
+				}
+				return await forward(req, upstreamUrl, url.origin, widgetTag)
+			},
+			websocket: {
+				open(socket) {
+					socket.data.browser = socket
+					for (const frame of socket.data.early) socket.send(frame)
+					socket.data.early = []
+					if (socket.data.upstream.readyState !== WebSocket.OPEN) socket.close()
+				},
+				message(socket, message) {
+					if (socket.data.upstream.readyState === WebSocket.OPEN) socket.data.upstream.send(message)
+				},
+				close(socket) {
+					socket.data.upstream.close()
+				},
+			},
+		})
+	}
+
+	/** Connects to the application first, so the browser gets the subprotocol the application chose. */
+	private async upgrade(req: Request, server: ProxyServer, upstreamUrl: URL): Promise<Response | undefined> {
+		const protocols = (req.headers.get('Sec-WebSocket-Protocol') ?? '').split(',').map((protocol) => protocol.trim()).filter((protocol) =>
+			protocol !== ''
+		)
+		let upstream: WebSocket
+		try {
+			upstream = await connectUpstream(upstreamUrl, protocols)
+		} catch {
+			return new Response('agent-canvas review: the application refused the WebSocket', { status: 502 })
+		}
+		const data: ProxySocketData = { upstream, early: [], browser: null }
+		upstream.onmessage = (event) => {
+			if (typeof event.data !== 'string' && !(event.data instanceof ArrayBuffer)) return
+			if (data.browser === null) data.early.push(event.data)
+			else data.browser.send(event.data)
+		}
+		upstream.onclose = () => data.browser?.close()
+		// Bun rejects an empty `headers` object, so a socket without a subprotocol (Bun's own hot reload) passes none.
+		const upgraded = upstream.protocol === ''
+			? server.upgrade(req, { data })
+			: server.upgrade(req, { data, headers: { 'Sec-WebSocket-Protocol': upstream.protocol } })
+		if (upgraded) return undefined
+		upstream.close()
+		return new Response('WebSocket upgrade failed', { status: 400 })
+	}
+}
+
+async function forward(req: Request, upstreamUrl: URL, proxyOrigin: string, widgetTag: string): Promise<Response> {
+	const headers = new Headers(req.headers)
+	headers.delete('Host')
+	// Uncompressed, so an HTML page can take the widget's tag.
+	headers.set('Accept-Encoding', 'identity')
+	if (headers.get('Origin') === proxyOrigin) headers.set('Origin', upstreamUrl.origin)
+	let upstream: Response
+	try {
+		upstream = await fetch(upstreamUrl, {
+			method: req.method,
+			headers,
+			body: req.method === 'GET' || req.method === 'HEAD' ? null : req.body,
+			redirect: 'manual',
+		})
+	} catch {
+		return new Response(`agent-canvas review: ${upstreamUrl.origin} does not answer. Is the application running?`, {
+			status: 502,
+			headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+		})
+	}
+
+	const responseHeaders = new Headers(upstream.headers)
+	// fetch hands over a decoded body, whatever the application sent.
+	responseHeaders.delete('Content-Encoding')
+	responseHeaders.delete('Content-Length')
+	const location = responseHeaders.get('Location')
+	if (location?.startsWith(upstreamUrl.origin)) responseHeaders.set('Location', `${proxyOrigin}${location.slice(upstreamUrl.origin.length)}`)
+
+	const init = { status: upstream.status, statusText: upstream.statusText, headers: responseHeaders }
+	if (req.method === 'HEAD' || !(responseHeaders.get('Content-Type') ?? '').startsWith('text/html')) return new Response(upstream.body, init)
+	return new Response(withWidget(await upstream.text(), widgetTag), init)
+}

package/daemon/src/review/server.ts

@@ -0,0 +1,199 @@
+import { type ChannelSocket, createNotificationChannel, dispatch, jsonResponse, type Route } from '@fabrika/daemon-kit'
+import type { z } from 'zod'
+import { renderReviewRequests } from './markdown'
+import {
+	addCommentBodySchema,
+	agentReplyBodySchema,
+	createThreadBodySchema,
+	isLoopbackOrigin,
+	openProxyBodySchema,
+	PROJECT_RE,
+	type ReviewBrowserFrame,
+	type ReviewWaitFrame,
+} from './model'
+import type { ReviewProxies } from './proxy'
+import { ReviewError, type ReviewStore } from './store'
+
+export interface ReviewSocketData {
+	type: 'review'
+	role: 'browser' | 'wait'
+	project: string
+}
+
+export interface ReviewSocket extends ChannelSocket {
+	data: ReviewSocketData
+}
+
+function corsHeaders(origin: string): Record<string, string> {
+	return {
+		'Access-Control-Allow-Origin': origin,
+		'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
+		'Access-Control-Allow-Headers': 'Content-Type',
+		Vary: 'Origin',
+	}
+}
+
+async function parseBody<T extends z.ZodTypeAny>(req: Request, schema: T): Promise<z.infer<T>> {
+	let body: unknown
+	try {
+		body = await req.json()
+	} catch {
+		throw new ReviewError('Body must be JSON', 400)
+	}
+	const parsed = schema.safeParse(body)
+	if (!parsed.success) throw new ReviewError(parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '), 400)
+	return parsed.data
+}
+
+function projectOf(match: URLPatternResult): string {
+	const project = match.pathname.groups['project'] ?? ''
+	if (!PROJECT_RE.test(project)) throw new ReviewError(`Invalid project name ${project}`, 400)
+	return project
+}
+
+function threadIdOf(match: URLPatternResult): string {
+	return match.pathname.groups['thread'] ?? ''
+}
+
+type Audience = 'browser' | 'agent'
+
+/** Review mode: threads a person leaves on a running application through the injected widget, and their delivery to the agent. */
+export function createReviewServer(store: ReviewStore, proxies: ReviewProxies) {
+	const channel = createNotificationChannel<ReviewSocket>({
+		roleOf: (socket) => socket.data.role,
+		topicOf: (socket) => socket.data.project,
+		presenceFrame: (watching): ReviewBrowserFrame => ({ type: 'agent-status', watching }),
+	})
+
+	function publish(project: string): void {
+		const frame: ReviewBrowserFrame = { type: 'threads', threads: store.list(project) }
+		channel.broadcast(project, frame)
+	}
+
+	function notifyAgent(project: string): void {
+		const frame: ReviewWaitFrame = { type: 'queued' }
+		channel.relayToWaiters(project, frame)
+	}
+
+	/**
+	 * Browser routes answer only loopback origins. Agent routes refuse any request a browser makes: browsers send
+	 * `Origin` on every cross-origin request, the CLI sends none.
+	 */
+	function route(
+		method: Route['method'],
+		pathname: string,
+		audience: Audience,
+		handle: (req: Request, match: URLPatternResult) => Promise<unknown>,
+	): Route {
+		return {
+			method,
+			pattern: new URLPattern({ pathname }),
+			handler: async (req, _url, match) => {
+				const origin = req.headers.get('Origin')
+				if (audience === 'agent' && origin !== null) return jsonResponse({ error: 'Agent endpoints do not accept browser requests' }, 403)
+				if (origin !== null && !isLoopbackOrigin(origin)) return jsonResponse({ error: 'Origin not allowed' }, 403)
+				let response: Response
+				try {
+					response = jsonResponse(await handle(req, match))
+				} catch (error) {
+					if (!(error instanceof ReviewError)) throw error
+					response = jsonResponse({ error: error.message }, error.status)
+				}
+				if (origin !== null) { for (const [name, value] of Object.entries(corsHeaders(origin))) response.headers.set(name, value) }
+				return response
+			},
+		}
+	}
+
+	const routes: Route[] = [
+		route('GET', '/api/review/:project/threads', 'browser', async (_req, match) => ({ threads: store.list(projectOf(match)) })),
+		route('POST', '/api/review/:project/threads', 'browser', async (req, match) => {
+			const project = projectOf(match)
+			const body = await parseBody(req, createThreadBodySchema)
+			const thread = store.create(project, body.anchor, body.body, body.send, body.screenshot)
+			publish(project)
+			if (body.send) notifyAgent(project)
+			return { thread }
+		}),
+		route('POST', '/api/review/:project/threads/:thread/comments', 'browser', async (req, match) => {
+			const project = projectOf(match)
+			const body = await parseBody(req, addCommentBodySchema)
+			const thread = store.addUserComment(project, threadIdOf(match), body.body, body.send)
+			publish(project)
+			if (body.send) notifyAgent(project)
+			return { thread }
+		}),
+		route('POST', '/api/review/:project/threads/:thread/send', 'browser', async (_req, match) => {
+			const project = projectOf(match)
+			const thread = store.send(project, threadIdOf(match))
+			publish(project)
+			notifyAgent(project)
+			return { thread }
+		}),
+		route('POST', '/api/review/:project/threads/:thread/resolve', 'browser', async (_req, match) => {
+			const project = projectOf(match)
+			const thread = store.setResolved(project, threadIdOf(match), true)
+			publish(project)
+			return { thread }
+		}),
+		route('POST', '/api/review/:project/threads/:thread/reopen', 'browser', async (_req, match) => {
+			const project = projectOf(match)
+			const thread = store.setResolved(project, threadIdOf(match), false)
+			publish(project)
+			return { thread }
+		}),
+		route('DELETE', '/api/review/:project/threads/:thread', 'browser', async (_req, match) => {
+			const project = projectOf(match)
+			store.delete(project, threadIdOf(match))
+			publish(project)
+			return { ok: true }
+		}),
+		route('POST', '/api/review/:project/claim', 'agent', async (_req, match) => {
+			const project = projectOf(match)
+			const threads = store.claimQueued(project)
+			if (threads.length === 0) return { found: false }
+			publish(project)
+			return { found: true, markdown: renderReviewRequests(project, threads) }
+		}),
+		route('POST', '/api/review/:project/proxy', 'agent', async (req, match) => {
+			const body = await parseBody(req, openProxyBodySchema)
+			return { url: proxies.open(projectOf(match), body.target) }
+		}),
+		route('POST', '/api/review/:project/threads/:thread/reply', 'agent', async (req, match) => {
+			const project = projectOf(match)
+			const body = await parseBody(req, agentReplyBodySchema)
+			const thread = store.agentReply(project, threadIdOf(match), body.body, body.resolve)
+			publish(project)
+			return { thread }
+		}),
+	]
+
+	return {
+		channel,
+		/** Answers the request when it is review mode's: CORS preflight, a route, or a WebSocket upgrade. */
+		fetch(
+			req: Request,
+			url: URL,
+			server: { upgrade(req: Request, options: { data: ReviewSocketData }): boolean },
+		): Response | Promise<Response> | 'upgraded' | null {
+			const socketMatch = url.pathname.match(/^\/ws\/review(-wait)?\/([^/]+)$/)
+			if (socketMatch !== null) {
+				const origin = req.headers.get('Origin')
+				const project = socketMatch[2] ?? ''
+				const role = socketMatch[1] === undefined ? 'browser' : 'wait'
+				if (!PROJECT_RE.test(project)) return jsonResponse({ error: 'Invalid project name' }, 400)
+				if (role === 'browser' ? origin === null || !isLoopbackOrigin(origin) : origin !== null) return jsonResponse({ error: 'Origin not allowed' }, 403)
+				return server.upgrade(req, { data: { type: 'review', role, project } }) ? 'upgraded' : new Response('WebSocket upgrade failed', { status: 400 })
+			}
+			if (!url.pathname.startsWith('/api/review/')) return null
+			if (req.method === 'OPTIONS') {
+				const origin = req.headers.get('Origin')
+				if (origin === null || !isLoopbackOrigin(origin)) return new Response(null, { status: 403 })
+				return new Response(null, { status: 204, headers: corsHeaders(origin) })
+			}
+			return dispatch(routes, req, url)
+		},
+	}
+}
+
+export type ReviewServer = ReturnType<typeof createReviewServer>

package/daemon/src/review/store.ts

@@ -0,0 +1,151 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import {
+	PROJECT_RE,
+	type ReviewAnchor,
+	type ReviewAuthor,
+	type ReviewProxy,
+	reviewProxySchema,
+	type ReviewThread,
+	reviewThreadsFileSchema,
+	type ReviewThreadState,
+} from './model'
+
+export class ReviewError extends Error {
+	constructor(message: string, readonly status: 400 | 404 | 409) {
+		super(message)
+	}
+}
+
+/**
+ * Review threads of each project: `<directory>/<project>/threads.json`, attached screenshots beside it, and the
+ * project's review proxy in `proxy.json`.
+ */
+export class ReviewStore {
+	constructor(private readonly directory: string, private readonly now: () => Date = () => new Date()) {}
+
+	list(project: string): readonly ReviewThread[] {
+		const path = join(this.projectDirectory(project), 'threads.json')
+		if (!existsSync(path)) return []
+		return reviewThreadsFileSchema.parse(JSON.parse(readFileSync(path, 'utf-8'))).threads
+	}
+
+	create(project: string, anchor: ReviewAnchor, body: string, send: boolean, screenshot?: Uint8Array): ReviewThread {
+		const createdAt = this.timestamp()
+		const id = Bun.randomUUIDv7()
+		const thread: ReviewThread = {
+			id,
+			anchor,
+			state: send ? 'queued' : 'open',
+			comments: [{ id: Bun.randomUUIDv7(), author: 'user', body, createdAt }],
+			...(screenshot === undefined ? {} : { screenshot: this.writeScreenshot(project, id, screenshot) }),
+			createdAt,
+			updatedAt: createdAt,
+		}
+		this.save(project, [...this.list(project), thread])
+		return thread
+	}
+
+	/** A comment from the person reopens a resolved thread; with `send` it goes to the agent. */
+	addUserComment(project: string, threadId: string, body: string, send: boolean): ReviewThread {
+		return this.update(project, threadId, (thread) => {
+			const state: ReviewThreadState = send ? 'queued' : thread.state === 'resolved' ? 'open' : thread.state
+			return { ...this.withComment(thread, 'user', body), state }
+		})
+	}
+
+	send(project: string, threadId: string): ReviewThread {
+		return this.update(project, threadId, (thread) => {
+			if (thread.state === 'working') throw new ReviewError('The agent is already working on this thread', 409)
+			return { ...thread, state: 'queued', updatedAt: this.timestamp() }
+		})
+	}
+
+	setResolved(project: string, threadId: string, resolved: boolean): ReviewThread {
+		return this.update(project, threadId, (thread) => ({ ...thread, state: resolved ? 'resolved' : 'open', updatedAt: this.timestamp() }))
+	}
+
+	delete(project: string, threadId: string): void {
+		const threads = this.list(project)
+		const thread = threads.find((candidate) => candidate.id === threadId)
+		if (thread === undefined) throw new ReviewError(`No thread ${threadId}`, 404)
+		this.save(project, threads.filter((candidate) => candidate.id !== threadId))
+		if (thread.screenshot !== undefined) rmSync(thread.screenshot, { force: true })
+	}
+
+	/** Hands every queued thread to the agent: they become `working` and are returned in creation order. */
+	claimQueued(project: string): readonly ReviewThread[] {
+		const threads = this.list(project)
+		const claimed = threads.filter((thread) => thread.state === 'queued')
+		if (claimed.length === 0) return []
+		const updatedAt = this.timestamp()
+		const claimedIds = new Set(claimed.map((thread) => thread.id))
+		this.save(project, threads.map((thread) => (claimedIds.has(thread.id) ? { ...thread, state: 'working', updatedAt } : thread)))
+		return claimed.map((thread) => ({ ...thread, state: 'working', updatedAt }))
+	}
+
+	/** The agent's answer. Without `resolve` the thread goes back to the person as `open`. */
+	agentReply(project: string, threadId: string, body: string, resolve: boolean): ReviewThread {
+		return this.update(project, threadId, (thread) => ({ ...this.withComment(thread, 'agent', body), state: resolve ? 'resolved' : 'open' }))
+	}
+
+	proxyOf(project: string): ReviewProxy | undefined {
+		const path = join(this.projectDirectory(project), 'proxy.json')
+		if (!existsSync(path)) return undefined
+		return reviewProxySchema.parse(JSON.parse(readFileSync(path, 'utf-8')))
+	}
+
+	saveProxy(project: string, proxy: ReviewProxy): void {
+		this.writeJson(project, 'proxy.json', proxy)
+	}
+
+	/** Projects that have a review proxy, for a starting daemon to serve again. */
+	proxiedProjects(): string[] {
+		if (!existsSync(this.directory)) return []
+		return readdirSync(this.directory).filter((name) => PROJECT_RE.test(name) && existsSync(join(this.directory, name, 'proxy.json')))
+	}
+
+	private update(project: string, threadId: string, change: (thread: ReviewThread) => ReviewThread): ReviewThread {
+		const threads = this.list(project)
+		const current = threads.find((thread) => thread.id === threadId)
+		if (current === undefined) throw new ReviewError(`No thread ${threadId}`, 404)
+		const next = change(current)
+		this.save(project, threads.map((thread) => (thread.id === threadId ? next : thread)))
+		return next
+	}
+
+	private withComment(thread: ReviewThread, author: ReviewAuthor, body: string): ReviewThread {
+		const createdAt = this.timestamp()
+		return { ...thread, comments: [...thread.comments, { id: Bun.randomUUIDv7(), author, body, createdAt }], updatedAt: createdAt }
+	}
+
+	private writeScreenshot(project: string, threadId: string, png: Uint8Array): string {
+		const directory = join(this.projectDirectory(project), 'screenshots')
+		mkdirSync(directory, { recursive: true })
+		const path = join(directory, `${threadId}.png`)
+		writeFileSync(path, png)
+		return path
+	}
+
+	private save(project: string, threads: readonly ReviewThread[]): void {
+		this.writeJson(project, 'threads.json', { threads })
+	}
+
+	private writeJson(project: string, file: string, value: unknown): void {
+		const directory = this.projectDirectory(project)
+		mkdirSync(directory, { recursive: true })
+		const path = join(directory, file)
+		const temporary = `${path}.${process.pid}.tmp`
+		writeFileSync(temporary, `${JSON.stringify(value, null, '\t')}\n`)
+		renameSync(temporary, path)
+	}
+
+	private projectDirectory(project: string): string {
+		if (!PROJECT_RE.test(project)) throw new ReviewError(`Invalid project name ${project}`, 400)
+		return join(this.directory, project)
+	}
+
+	private timestamp(): string {
+		return this.now().toISOString()
+	}
+}