agent-canvas 0.2.1 → 0.7.0

package/daemon/src/remote-feedback.ts

@@ -1,6 +1,7 @@
-import type { SessionManager, RemoteFeedbackEntry, RemoteAnnotation } from "@fabrika/canvas-kernel/server";
-import { loadShareConfig } from "./share";
-import { importShareKey, decryptString } from "../client/shareCrypto";
+import type { RemoteAnnotation, RemoteFeedbackEntry, SessionManager } from '@fabrika/canvas-kernel/server'
+import { errorMessage } from '../client/errorMessage'
+import { decryptString, importShareKey } from '../client/shareCrypto'
+import { loadShareConfig } from './share'
 
 /**
  * Background polling loop for remote feedback.
@@ -17,212 +18,211 @@ import { importShareKey, decryptString } from "../client/shareCrypto";
  * as soon as the worker comes back.
  */
 
-const POLL_INTERVAL_MS = 5_000;
-const MAX_BACKOFF_MS = 60_000;
+const POLL_INTERVAL_MS = 5_000
+const MAX_BACKOFF_MS = 60_000
 
 /** Wire-format feedback entry as returned by the worker. When the
  *  reviewer submitted from an encrypted share their browser ciphertexted
  *  the secret fields and stamped this with `encryption`; the daemon
  *  decrypts using the key stashed on the local ShareEntry. */
 interface WireFeedbackEntry {
-  id: string;
-  shareId: string;
-  revision: number;
-  submittedAt: string;
-  author: { id: string; name: string };
-  annotations: Array<{
-    id: string;
-    snippet: string;
-    note: string;
-    createdAt: string;
-    filePath?: string;
-    canvasFile?: string;
-    context?: unknown;
-    attachments?: Array<{ url: string; mime?: string }>;
-  }>;
-  generalNote?: string;
-  encryption?: { alg: string; v: number };
+	id: string
+	shareId: string
+	revision: number
+	submittedAt: string
+	author: { id: string; name: string }
+	annotations: Array<{
+		id: string
+		snippet: string
+		note: string
+		createdAt: string
+		filePath?: string
+		canvasFile?: string
+		context?: unknown
+		attachments?: Array<{ url: string; mime?: string }>
+	}>
+	generalNote?: string
+	encryption?: { alg: string; v: number }
 }
 
 interface WorkerFeedbackResponse {
-  entries: WireFeedbackEntry[];
-  /** Server-reported high water mark — echo back in the next `since` param */
-  latestAt?: string;
+	entries: WireFeedbackEntry[]
+	/** Server-reported high water mark — echo back in the next `since` param */
+	latestAt?: string
 }
 
 /** Decrypt an encrypted-wire feedback entry into the plaintext shape used
  *  throughout the rest of the daemon. Throws if any field fails to
  *  decrypt — caller treats that as a transient error so we re-try later. */
 async function decryptFeedbackEntry(entry: WireFeedbackEntry, key: CryptoKey): Promise<RemoteFeedbackEntry> {
-  const annotations: RemoteAnnotation[] = await Promise.all(
-    entry.annotations.map(async (a) => {
-      const out: RemoteAnnotation = {
-        id: a.id,
-        snippet: await decryptString(key, a.snippet),
-        note: await decryptString(key, a.note),
-        createdAt: a.createdAt,
-      };
-      if (a.filePath) out.filePath = await decryptString(key, a.filePath);
-      if (a.canvasFile) out.canvasFile = await decryptString(key, a.canvasFile);
-      if (typeof a.context === "string" && a.context.length > 0) {
-        out.context = JSON.parse(await decryptString(key, a.context));
-      }
-      if (a.attachments) out.attachments = a.attachments;
-      return out;
-    }),
-  );
-
-  return {
-    id: entry.id,
-    shareId: entry.shareId,
-    revision: entry.revision,
-    submittedAt: entry.submittedAt,
-    author: {
-      id: entry.author.id,
-      name: await decryptString(key, entry.author.name),
-    },
-    annotations,
-    ...(entry.generalNote ? { generalNote: await decryptString(key, entry.generalNote) } : {}),
-  };
+	const annotations: RemoteAnnotation[] = await Promise.all(
+		entry.annotations.map(async (a) => {
+			const out: RemoteAnnotation = {
+				id: a.id,
+				snippet: await decryptString(key, a.snippet),
+				note: await decryptString(key, a.note),
+				createdAt: a.createdAt,
+			}
+			if (a.filePath) out.filePath = await decryptString(key, a.filePath)
+			if (a.canvasFile) out.canvasFile = await decryptString(key, a.canvasFile)
+			if (typeof a.context === 'string' && a.context.length > 0) {
+				out.context = JSON.parse(await decryptString(key, a.context))
+			}
+			if (a.attachments) out.attachments = a.attachments
+			return out
+		}),
+	)
+
+	return {
+		id: entry.id,
+		shareId: entry.shareId,
+		revision: entry.revision,
+		submittedAt: entry.submittedAt,
+		author: {
+			id: entry.author.id,
+			name: await decryptString(key, entry.author.name),
+		},
+		annotations,
+		...(entry.generalNote ? { generalNote: await decryptString(key, entry.generalNote) } : {}),
+	}
 }
 
 export function startRemoteFeedbackPoller(
-  sessionManager: SessionManager,
-  broadcastRemoteFeedback: (sessionId: string, revision: number, entries: RemoteFeedbackEntry[]) => void,
-  version: string,
+	sessionManager: SessionManager,
+	broadcastRemoteFeedback: (sessionId: string, revision: number, entries: RemoteFeedbackEntry[]) => void,
+	version: string,
 ): { stop: () => void } {
-  let stopped = false;
-
-  // Per-share CryptoKey cache — `importKey` is async and pure given the
-  // same encoded key, so we memoize it for the lifetime of the poller.
-  const keyCache = new Map<string, Promise<CryptoKey>>();
-  function getKey(shareId: string, encoded: string): Promise<CryptoKey> {
-    let cached = keyCache.get(shareId);
-    if (!cached) {
-      cached = importShareKey(encoded);
-      keyCache.set(shareId, cached);
-    }
-    return cached;
-  }
-
-  // Per-share consecutive error count → exponential backoff so a dead
-  // worker doesn't generate a fire-hose of failed requests.
-  const errorCounts = new Map<string, number>();
-  function backoffFor(shareId: string): number {
-    const errors = errorCounts.get(shareId) || 0;
-    if (errors === 0) return 0;
-    return Math.min(MAX_BACKOFF_MS, POLL_INTERVAL_MS * Math.pow(2, errors - 1));
-  }
-
-  async function pollShare(
-    sessionId: string,
-    share: { shareId: string; lastFeedbackAt?: string; encryptionKey?: string },
-    endpoint: string,
-  ) {
-    try {
-      const since = share.lastFeedbackAt ?? "";
-      const url = `${endpoint}/shares/${share.shareId}/feedback${since ? `?since=${encodeURIComponent(since)}` : ""}`;
-      const res = await fetch(url);
-      if (!res.ok) {
-        if (res.status === 404) {
-          // Share no longer exists on the worker — likely revoked or expired.
-          // Stop trying so we don't hammer it forever.
-          errorCounts.set(share.shareId, 99);
-          return;
-        }
-        throw new Error(`HTTP ${res.status}`);
-      }
-      const data = (await res.json()) as WorkerFeedbackResponse;
-      errorCounts.delete(share.shareId);
-
-      if (!data.entries || data.entries.length === 0) return;
-
-      // Decrypt any entries that came in encrypted. Plaintext entries
-      // (legacy submissions from non-encrypted shares) pass through.
-      const decrypted: RemoteFeedbackEntry[] = [];
-      for (const e of data.entries) {
-        if (e.encryption) {
-          if (!share.encryptionKey) {
-            console.warn(`[remote-feedback] ${share.shareId}: received encrypted feedback but no local key — skipping entry ${e.id}`);
-            continue;
-          }
-          try {
-            const key = await getKey(share.shareId, share.encryptionKey);
-            decrypted.push(await decryptFeedbackEntry(e, key));
-          } catch (err: any) {
-            console.warn(`[remote-feedback] ${share.shareId}: failed to decrypt entry ${e.id}: ${err.message || err}`);
-            continue;
-          }
-        } else {
-          decrypted.push(e as RemoteFeedbackEntry);
-        }
-      }
-
-      if (decrypted.length === 0) return;
-
-      const byRev = new Map<number, RemoteFeedbackEntry[]>();
-      for (const e of decrypted) {
-        if (!byRev.has(e.revision)) byRev.set(e.revision, []);
-        byRev.get(e.revision)!.push(e);
-      }
-
-      for (const [rev, entries] of byRev) {
-        sessionManager.appendRemoteFeedback(sessionId, rev, entries);
-        broadcastRemoteFeedback(sessionId, rev, entries);
-      }
-
-      const latest = data.latestAt
-        ?? data.entries.reduce((acc, e) => (e.submittedAt > acc ? e.submittedAt : acc), share.lastFeedbackAt ?? "");
-      if (latest) {
-        sessionManager.updateShareLastFeedback(sessionId, share.shareId, latest);
-      }
-    } catch (e: any) {
-      errorCounts.set(share.shareId, (errorCounts.get(share.shareId) || 0) + 1);
-      console.warn(`[remote-feedback] ${share.shareId}: ${e.message || e} (will retry with backoff)`);
-    }
-  }
-
-  // Per-share next-poll timestamps so backoffs are independent.
-  const nextPollAt = new Map<string, number>();
-
-  async function pollOnce() {
-    const config = loadShareConfig(version);
-    if (!config) return;
-
-    const sessions = sessionManager.listSessionsWithShares();
-    if (sessions.length === 0) return;
-
-    const now = Date.now();
-    const tasks: Promise<void>[] = [];
-    for (const session of sessions) {
-      for (const share of session.shares ?? []) {
-        const next = nextPollAt.get(share.shareId) || 0;
-        if (now < next) continue;
-        // Skip "permanently dead" shares (after a 404).
-        if ((errorCounts.get(share.shareId) || 0) >= 99) continue;
-        nextPollAt.set(share.shareId, now + Math.max(POLL_INTERVAL_MS, backoffFor(share.shareId)));
-        tasks.push(pollShare(session.id, share, config.endpoint));
-      }
-    }
-    await Promise.all(tasks);
-  }
-
-  async function loop() {
-    while (!stopped) {
-      try {
-        await pollOnce();
-      } catch (e: any) {
-        console.warn(`[remote-feedback] loop error: ${e.message || e}`);
-      }
-      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
-    }
-  }
-
-  loop();
-
-  return {
-    stop: () => {
-      stopped = true;
-    },
-  };
+	let stopped = false
+
+	// Per-share CryptoKey cache — `importKey` is async and pure given the
+	// same encoded key, so we memoize it for the lifetime of the poller.
+	const keyCache = new Map<string, Promise<CryptoKey>>()
+	function getKey(shareId: string, encoded: string): Promise<CryptoKey> {
+		let cached = keyCache.get(shareId)
+		if (!cached) {
+			cached = importShareKey(encoded)
+			keyCache.set(shareId, cached)
+		}
+		return cached
+	}
+
+	// Per-share consecutive error count → exponential backoff so a dead
+	// worker doesn't generate a fire-hose of failed requests.
+	const errorCounts = new Map<string, number>()
+	function backoffFor(shareId: string): number {
+		const errors = errorCounts.get(shareId) || 0
+		if (errors === 0) return 0
+		return Math.min(MAX_BACKOFF_MS, POLL_INTERVAL_MS * Math.pow(2, errors - 1))
+	}
+
+	async function pollShare(
+		sessionId: string,
+		share: { shareId: string; lastFeedbackAt?: string; encryptionKey?: string },
+		endpoint: string,
+	) {
+		try {
+			const since = share.lastFeedbackAt ?? ''
+			const url = `${endpoint}/shares/${share.shareId}/feedback${since ? `?since=${encodeURIComponent(since)}` : ''}`
+			const res = await fetch(url)
+			if (!res.ok) {
+				if (res.status === 404) {
+					// Share no longer exists on the worker — likely revoked or expired.
+					// Stop trying so we don't hammer it forever.
+					errorCounts.set(share.shareId, 99)
+					return
+				}
+				throw new Error(`HTTP ${res.status}`)
+			}
+			const data = (await res.json()) as WorkerFeedbackResponse
+			errorCounts.delete(share.shareId)
+
+			if (!data.entries || data.entries.length === 0) return
+
+			// Decrypt any entries that came in encrypted. Plaintext entries
+			// (legacy submissions from non-encrypted shares) pass through.
+			const decrypted: RemoteFeedbackEntry[] = []
+			for (const e of data.entries) {
+				if (e.encryption) {
+					if (!share.encryptionKey) {
+						console.warn(`[remote-feedback] ${share.shareId}: received encrypted feedback but no local key — skipping entry ${e.id}`)
+						continue
+					}
+					try {
+						const key = await getKey(share.shareId, share.encryptionKey)
+						decrypted.push(await decryptFeedbackEntry(e, key))
+					} catch (err) {
+						console.warn(`[remote-feedback] ${share.shareId}: failed to decrypt entry ${e.id}: ${errorMessage(err)}`)
+					}
+				} else {
+					decrypted.push(e as RemoteFeedbackEntry)
+				}
+			}
+
+			if (decrypted.length === 0) return
+
+			const byRev = new Map<number, RemoteFeedbackEntry[]>()
+			for (const e of decrypted) {
+				if (!byRev.has(e.revision)) byRev.set(e.revision, [])
+				byRev.get(e.revision)!.push(e)
+			}
+
+			for (const [rev, entries] of byRev) {
+				sessionManager.appendRemoteFeedback(sessionId, rev, entries)
+				broadcastRemoteFeedback(sessionId, rev, entries)
+			}
+
+			const latest = data.latestAt
+				?? data.entries.reduce((acc, e) => (e.submittedAt > acc ? e.submittedAt : acc), share.lastFeedbackAt ?? '')
+			if (latest) {
+				sessionManager.updateShareLastFeedback(sessionId, share.shareId, latest)
+			}
+		} catch (e) {
+			errorCounts.set(share.shareId, (errorCounts.get(share.shareId) || 0) + 1)
+			console.warn(`[remote-feedback] ${share.shareId}: ${errorMessage(e)} (will retry with backoff)`)
+		}
+	}
+
+	// Per-share next-poll timestamps so backoffs are independent.
+	const nextPollAt = new Map<string, number>()
+
+	async function pollOnce() {
+		const config = loadShareConfig(version)
+		if (!config) return
+
+		const sessions = sessionManager.listSessionsWithShares()
+		if (sessions.length === 0) return
+
+		const now = Date.now()
+		const tasks: Promise<void>[] = []
+		for (const session of sessions) {
+			for (const share of session.shares ?? []) {
+				const next = nextPollAt.get(share.shareId) || 0
+				if (now < next) continue
+				// Skip "permanently dead" shares (after a 404).
+				if ((errorCounts.get(share.shareId) || 0) >= 99) continue
+				nextPollAt.set(share.shareId, now + Math.max(POLL_INTERVAL_MS, backoffFor(share.shareId)))
+				tasks.push(pollShare(session.id, share, config.endpoint))
+			}
+		}
+		await Promise.all(tasks)
+	}
+
+	async function loop() {
+		while (!stopped) {
+			try {
+				await pollOnce()
+			} catch (e) {
+				console.warn(`[remote-feedback] loop error: ${errorMessage(e)}`)
+			}
+			await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS))
+		}
+	}
+
+	loop()
+
+	return {
+		stop: () => {
+			stopped = true
+		},
+	}
 }

package/daemon/src/review/markdown.ts

@@ -0,0 +1,52 @@
+import type { ReviewAnchor, ReviewThread } from './model'
+
+function fence(language: string, text: string): string {
+	const longest = Math.max(2, ...[...text.matchAll(/`+/g)].map((match) => match[0].length))
+	const marker = '`'.repeat(longest + 1)
+	return `${marker}${language}\n${text}\n${marker}`
+}
+
+function describeAnchor(anchor: ReviewAnchor, screenshot: string | undefined): string[] {
+	const lines = [`- Page: ${anchor.url}`]
+	if (anchor.context !== undefined) lines.push(`- Where: ${anchor.context}`)
+	const accessible = [anchor.role, anchor.name === undefined ? undefined : `"${anchor.name}"`].filter((part) => part !== undefined).join(' ')
+	if (accessible !== '') lines.push(`- Element: ${accessible}`)
+	if (anchor.selector !== '') lines.push(`- Selector: \`${anchor.selector}\``)
+	if (anchor.components !== undefined && anchor.components.length > 0) lines.push(`- Components: ${anchor.components.join(' › ')}`)
+	if (anchor.sources !== undefined && anchor.sources.length > 0) {
+		lines.push('- Source, innermost first:')
+		for (const source of anchor.sources) lines.push(`  - ${source.label}: \`${source.file}:${source.line}:${source.column}\``)
+	}
+	if (anchor.quote !== undefined) {
+		lines.push(`- Selected text: …${anchor.quote.before}**${anchor.quote.exact}**${anchor.quote.after}…`)
+	} else if (anchor.text !== undefined && anchor.text !== '') {
+		lines.push(`- Text: "${anchor.text}"`)
+	}
+	if (screenshot !== undefined) lines.push(`- Screenshot, the element outlined in red: \`${screenshot}\` (read the file to see it)`)
+	if (anchor.html !== undefined) lines.push('- Markup, trimmed:', '', fence('html', anchor.html))
+	return lines
+}
+
+function quoteBody(body: string): string {
+	return body.split('\n').map((line) => `> ${line}`).join('\n')
+}
+
+/** The requests a waiting agent receives: each thread with its place in the page, its conversation and how to answer. */
+export function renderReviewRequests(project: string, threads: readonly ReviewThread[]): string {
+	const sections = threads.map((thread, index) => {
+		const conversation = thread.comments.map((comment) => `**${comment.author === 'user' ? 'Reviewer' : 'You'}:**\n${quoteBody(comment.body)}`)
+		return [`## ${index + 1}. Thread ${thread.id}`, '', ...describeAnchor(thread.anchor, thread.screenshot), '', ...conversation].join('\n')
+	})
+	return [
+		`# Review requests for ${project}`,
+		'',
+		`The reviewer sent ${threads.length === 1 ? 'one thread' : `${threads.length} threads`} from the running application.`,
+		'Make the change each thread asks for, then answer it so the reviewer sees what happened:',
+		'',
+		`    bunx agent-canvas review reply <thread-id> "<what you changed>" --resolve --project ${project}`,
+		'',
+		'Leave out `--resolve` when you ask a question back instead.',
+		'',
+		...sections.flatMap((section) => [section, '']),
+	].join('\n')
+}

package/daemon/src/review/model.ts

@@ -0,0 +1,132 @@
+import { z } from 'zod'
+
+/**
+ * Review threads: comments a person leaves on a running application. A thread is a note until the person sends it
+ * to the agent; the agent picks it up, answers and may resolve it.
+ */
+
+export const PROJECT_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+
+/**
+ * Loopback origins only: a page on any other origin must not be able to put a request in front of the agent.
+ * The application under review runs on its own dev server, so its port is not the daemon's.
+ */
+export function isLoopbackOrigin(origin: string): boolean {
+	let url: URL
+	try {
+		url = new URL(origin)
+	} catch {
+		return false
+	}
+	if (url.protocol !== 'http:' && url.protocol !== 'https:') return false
+	return url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]' || url.hostname.endsWith('.localhost')
+}
+
+const shortText = z.string().max(500)
+
+export const MAX_HTML = 4000
+
+/** A position in the application's source, resolved from a development stack through the page's source maps. */
+export const reviewSourceSchema = z.object({
+	/** What was created there, e.g. `<a> in ProductListCell` or `<ProductListCell> in DataGrid`. */
+	label: shortText,
+	file: z.string().max(1000),
+	line: z.number().int().positive(),
+	column: z.number().int().nonnegative(),
+})
+export type ReviewSource = z.infer<typeof reviewSourceSchema>
+
+/** Where in the page a thread points. Every field is best effort; the agent reads them, the widget re-finds the element. */
+export const reviewAnchorSchema = z.object({
+	/** The page's URL when the thread was created, hash routes included. */
+	url: z.string().min(1).max(2000),
+	/** CSS path from the nearest element with an id, or from `body`. */
+	selector: z.string().max(2000),
+	/** ARIA role and accessible name, as the agent would target the element in a browser. */
+	role: shortText.optional(),
+	name: shortText.optional(),
+	/** The element's visible text, shortened. */
+	text: shortText.optional(),
+	/** Owner components from the outermost to the element, read off React's development fibers. */
+	components: z.array(z.string().max(200)).max(20).optional(),
+	/** Source positions of the element and its nearest owner components, innermost first. */
+	sources: z.array(reviewSourceSchema).max(10).optional(),
+	/** The landmarks around the element: page heading, section, dialog. */
+	context: shortText.optional(),
+	/** The element's markup, trimmed: deep subtrees, long lists and long texts are cut. */
+	html: z.string().max(MAX_HTML).optional(),
+	/** A text selection inside the element, with its surroundings. */
+	quote: z.object({ exact: z.string().min(1).max(2000), before: shortText, after: shortText }).optional(),
+})
+export type ReviewAnchor = z.infer<typeof reviewAnchorSchema>
+
+export const reviewAuthorSchema = z.enum(['user', 'agent'])
+export type ReviewAuthor = z.infer<typeof reviewAuthorSchema>
+
+export const reviewCommentSchema = z.object({
+	id: z.string(),
+	author: reviewAuthorSchema,
+	body: z.string().min(1).max(20_000),
+	createdAt: z.string(),
+})
+export type ReviewComment = z.infer<typeof reviewCommentSchema>
+
+/**
+ * - `open`: a note, or an answered thread waiting on the person.
+ * - `queued`: sent to the agent, not picked up yet.
+ * - `working`: delivered to the agent.
+ * - `resolved`: the agent or the person closed it.
+ */
+export const reviewThreadStateSchema = z.enum(['open', 'queued', 'working', 'resolved'])
+export type ReviewThreadState = z.infer<typeof reviewThreadStateSchema>
+
+export const reviewThreadSchema = z.object({
+	id: z.string(),
+	anchor: reviewAnchorSchema,
+	state: reviewThreadStateSchema,
+	comments: z.array(reviewCommentSchema).min(1),
+	/** Absolute path of a PNG of the element the reviewer attached, stored by the daemon. */
+	screenshot: z.string().optional(),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+})
+export type ReviewThread = z.infer<typeof reviewThreadSchema>
+
+export const reviewThreadsFileSchema = z.object({ threads: z.array(reviewThreadSchema) })
+
+const commentBody = z.string().trim().min(1).max(20_000)
+
+const PNG_DATA_URL = 'data:image/png;base64,'
+
+/** A PNG the widget rendered from the element, as a data URL; at most about 6 MB decoded. */
+export const screenshotDataUrlSchema = z.string().startsWith(PNG_DATA_URL).max(8_000_000)
+	.transform((url) => Uint8Array.from(atob(url.slice(PNG_DATA_URL.length)), (char) => char.charCodeAt(0)))
+
+export const createThreadBodySchema = z.object({
+	anchor: reviewAnchorSchema,
+	body: commentBody,
+	send: z.boolean(),
+	screenshot: screenshotDataUrlSchema.optional(),
+})
+export const addCommentBodySchema = z.object({ body: commentBody, send: z.boolean() })
+export const agentReplyBodySchema = z.object({ body: commentBody, resolve: z.boolean() })
+
+/** An application on this machine: the review proxy forwards to its origin and refuses any other host. */
+const loopbackUrlSchema = z.string().url().refine((url) => isLoopbackOrigin(url), 'must be an http(s) URL on localhost')
+
+/** The CLI's request to open an application for review through the daemon's proxy. */
+export const openProxyBodySchema = z.object({ target: loopbackUrlSchema })
+
+/** A project's review proxy, kept so a restarted daemon serves it on the same port: the reviewer's tab keeps working. */
+export const reviewProxySchema = z.object({ target: loopbackUrlSchema, port: z.number().int().min(1).max(65_535) })
+export type ReviewProxy = z.infer<typeof reviewProxySchema>
+
+/** Frames the daemon sends to browsers on a project's topic. */
+export type ReviewBrowserFrame =
+	| { type: 'threads'; threads: readonly ReviewThread[] }
+	| { type: 'agent-status'; watching: boolean }
+
+/** The frame a waiting CLI receives when the person sends threads; it reads them back through the claim endpoint. */
+export interface ReviewWaitFrame {
+	type: 'queued'
+}