pk-annotator 0.6.1 → 0.7.0

package/dist/{pka-overlay-thread-store-DOxLXsAv.mjs → pka-overlay-thread-store-X3FM2ev_.mjs}

@@ -1 +1 @@
-import{f as e,h as t,m as n,n as r,p as i}from"./overlay.mjs";import{M as a,O as o,P as s,_ as c,c as l,d as u,j as d,n as f,u as p,y as m}from"./pka-overlay-channel-D5Ghnvgb.mjs";import{t as h}from"./pka-overlay-store-eSg4Q7Sz.mjs";const g=d({id:c,prompt:a(),createdAt:m,elements:o().int().nonnegative()});function _(){let e=sessionStorage.getItem(r);if(e===null)return{sent:[],discarded:null};let t=[],n=null,i;try{i=JSON.parse(e)}catch(e){n=`it is not JSON (${e instanceof Error?e.message:String(e)})`}if(n===null&&!Array.isArray(i)&&(n=`it is not a list`),Array.isArray(i))for(let[e,r]of i.entries()){let i=g.safeParse(r);i.success?t.push(i.data):n??=`entry ${e+1}: ${s(i.error)}`}if(n===null)return{sent:t,discarded:null};let a=`Discarded unreadable History entries in sessionStorage ${r}; ${n}`;return console.error(`[pk-annotator] ${a}`),sessionStorage.setItem(r,JSON.stringify(t)),{sent:t,discarded:a}}function v(a){let o=h({..._(),states:/* @__PURE__ */ new Map,entries:/* @__PURE__ */ new Map,unread:!1}),s=e=>o.get().sent.some(t=>t.id===e),c=o.get().sent.map(e=>e.id),d=/* @__PURE__ */ new Set,m=()=>{d=new Set(c.splice(0,200)),d.size>0&&t(a,f.sync,{ids:[...d]})},g=[n(a,f.state,l,t=>{if(!s(t.id))return;let n=o.get().states.get(t.id)?.status;o.set({states:new Map(o.get().states).set(t.id,t.state)}),(t.state.status===`resolved`||t.state.status===`dismissed`)&&n!==t.state.status&&e()}),n(a,f.thread,u,({id:t,entry:n})=>{if(!s(t))return;let{entries:r,unread:i}=o.get();o.set({entries:new Map(r).set(t,[...r.get(t)??[],n]),unread:i||n.from===`agent`}),n.from===`agent`&&e()}),n(a,f.synced,p,e=>{let t=new Map(o.get().states),n=new Map(o.get().entries);for(let r of e.annotations)t.set(r.id,r.state),n.set(r.id,r.thread);let i=new Set(e.annotations.map(e=>e.id)),a=o.get().sent.filter(e=>!d.has(e.id)||i.has(e.id));sessionStorage.setItem(r,JSON.stringify(a)),o.set({sent:a,states:t,entries:n}),m()})],v=o.subscribe(()=>{let{sent:e,states:t}=o.get();i(e.some(e=>t.get(e.id)?.status===`acknowledged`))});return m(),{...o,added(e){let t=[e,...o.get().sent.filter(t=>t.id!==e.id)];sessionStorage.setItem(r,JSON.stringify(t)),o.set({sent:t,states:new Map(o.get().states).set(e.id,{status:`pending`,history:[{status:`pending`,at:e.createdAt}]})})},disconnect(){for(let e of g)e();v(),i(!1)}}}export{v as connectThread};
+import{_ as e,g as t,h as n,n as r,v as i}from"./overlay.mjs";import{M as a,O as o,P as s,_ as c,c as l,d as u,j as d,n as f,u as p,y as m}from"./pka-overlay-channel-C6qfFolf.mjs";import{t as h}from"./pka-overlay-store-eSg4Q7Sz.mjs";const g=d({id:c,prompt:a(),createdAt:m,elements:o().int().nonnegative()});function _(){let e=sessionStorage.getItem(r);if(e===null)return{sent:[],discarded:null};let t=[],n=null,i;try{i=JSON.parse(e)}catch(e){n=`it is not JSON (${e instanceof Error?e.message:String(e)})`}if(n===null&&!Array.isArray(i)&&(n=`it is not a list`),Array.isArray(i))for(let[e,r]of i.entries()){let i=g.safeParse(r);i.success?t.push(i.data):n??=`entry ${e+1}: ${s(i.error)}`}if(n===null)return{sent:t,discarded:null};let a=`Discarded unreadable History entries in sessionStorage ${r}; ${n}`;return console.error(`[pk-annotator] ${a}`),sessionStorage.setItem(r,JSON.stringify(t)),{sent:t,discarded:a}}function v(a){let o=h({..._(),states:/* @__PURE__ */ new Map,entries:/* @__PURE__ */ new Map,unread:!1}),s=e=>o.get().sent.some(t=>t.id===e),c=o.get().sent.map(e=>e.id),d=/* @__PURE__ */ new Set,m=()=>{d=new Set(c.splice(0,200)),d.size>0&&i(a,f.sync,{ids:[...d]})},g=[e(a,f.state,l,e=>{if(!s(e.id))return;let t=o.get().states.get(e.id)?.status;o.set({states:new Map(o.get().states).set(e.id,e.state)}),(e.state.status===`resolved`||e.state.status===`dismissed`)&&t!==e.state.status&&n()}),e(a,f.thread,u,({id:e,entry:t})=>{if(!s(e))return;let{entries:r,unread:i}=o.get();o.set({entries:new Map(r).set(e,[...r.get(e)??[],t]),unread:i||t.from===`agent`}),t.from===`agent`&&n()}),e(a,f.synced,p,e=>{let t=new Map(o.get().states),n=new Map(o.get().entries);for(let r of e.annotations)t.set(r.id,r.state),n.set(r.id,r.thread);let i=new Set(e.annotations.map(e=>e.id)),a=o.get().sent.filter(e=>!d.has(e.id)||i.has(e.id));sessionStorage.setItem(r,JSON.stringify(a)),o.set({sent:a,states:t,entries:n}),m()})],v=o.subscribe(()=>{let{sent:e,states:n}=o.get();t(e.some(e=>n.get(e.id)?.status===`acknowledged`))});return m(),{...o,added(e){let t=[e,...o.get().sent.filter(t=>t.id!==e.id)];sessionStorage.setItem(r,JSON.stringify(t)),o.set({sent:t,states:new Map(o.get().states).set(e.id,{status:`pending`,history:[{status:`pending`,at:e.createdAt}]})})},disconnect(){for(let e of g)e();v(),t(!1)}}}export{v as connectThread};

package/dist/pka-overlay-untracked-fetch-Dj1et-Fv.mjs

@@ -0,0 +1 @@
+import{y as e}from"./overlay.mjs";function t(t,n){return e().fetch(t,n)}export{t};

package/dist/pka.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { B as Id, F as readJsonLines, I as resolveInside, M as isErrno, O as PkaError, P as readJson, S as wait, W as Timestamp, _ as prune, a as ErrorsInput, c as ReplyInput, h as list, i as TimelineEntry, j as findStore, l as SetStatusInput, m as get, n as RecordingManifest, o as GetInput, p as errors, s as ListInput, u as attach, v as reply, x as validateAttachTarget, y as setStatus, z as ID_PATTERN } from "./recording-CpEDddkZ.mjs";
+import { B as Id, F as readJsonLines, I as resolveInside, M as isErrno, O as PkaError, P as readJson, S as wait, W as Timestamp, _ as prune, a as ErrorsInput, c as ReplyInput, h as list, i as TimelineEntry, j as findStore, l as SetStatusInput, m as get, n as RecordingManifest, o as GetInput, p as errors, s as ListInput, u as attach, v as reply, x as validateAttachTarget, y as setStatus, z as ID_PATTERN } from "./recording-82fajWWq.mjs";
 import { createRequire } from "node:module";
 import { createWriteStream } from "node:fs";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
@@ -1423,6 +1423,7 @@ function printAnnotation(view) {
 		line(`  [${element.n}] ${element.source ?? "(no source)"}${element.usedAt === void 0 ? "" : ` usedAt ${element.usedAt}`}  ${element.owners.join(" > ")}  ${label || element.selector.css}`);
 	}
 	for (const attachment of view.attachments) line(`  ${attachment.kind}: ${attachment.path}${attachment.summary ? `  ${attachment.summary}` : ""}`);
+	for (const mark of view.marks ?? []) line(`  mark ${mark.n}: ${mark.url}`);
 	for (const entry of view.thread ?? []) line(`  ${entry.at} ${entry.from}: ${entry.text}`);
 	if (view.omitted !== void 0) line(view.omitted.note);
 }

package/dist/{recording-CpEDddkZ.mjs → recording-82fajWWq.mjs}

@@ -30,6 +30,7 @@ const Selector = z.strictObject({
 });
 const ElementRef = z.strictObject({
 	n: z.number().int().positive(),
+	url: z.string().optional(),
 	source: z.string().regex(/^.+:\d+:\d+$/, "source must be file:line:col").optional(),
 	usedAt: z.string().regex(/^.+:\d+:\d+$/, "usedAt must be file:line:col").optional(),
 	owners: z.array(z.string()),
@@ -53,6 +54,11 @@ const Attachment = z.strictObject({
 	path: RelativePath,
 	summary: z.string()
 });
+const MarkPage = z.strictObject({
+	n: z.number().int().positive(),
+	url: z.string(),
+	route: z.string()
+});
 const Annotation = z.strictObject({
 	id: Id,
 	createdAt: Timestamp,
@@ -61,7 +67,8 @@ const Annotation = z.strictObject({
 	viewport: Viewport,
 	prompt: z.string(),
 	elements: z.array(ElementRef),
-	attachments: z.array(Attachment)
+	attachments: z.array(Attachment),
+	marks: z.array(MarkPage).optional()
 });
 const AnnotationDraft = Annotation.omit({
 	id: true,
@@ -734,6 +741,7 @@ function optionalPageText(value, max) {
 }
 const ElementView = z.strictObject({
 	n: z.number(),
+	url: z.string().optional().describe("The page the element was picked on"),
 	source: z.string().optional(),
 	usedAt: z.string().optional(),
 	owners: z.array(z.string()),
@@ -749,6 +757,11 @@ const ElementView = z.strictObject({
 	html: z.string().optional(),
 	box: Box.optional()
 });
+const MarkView = z.strictObject({
+	n: z.number().describe("Matches the \"## Mark n\" section of the prompt"),
+	url: z.string(),
+	route: z.string()
+});
 const AnnotationView = z.strictObject({
 	id: Id,
 	createdAt: Timestamp,
@@ -765,13 +778,15 @@ const AnnotationView = z.strictObject({
 		path: z.string(),
 		summary: z.string().optional()
 	})),
+	marks: z.array(MarkView).optional().describe("The page each saved mark of a batch was made on"),
 	threadCount: z.number(),
 	omitted: z.strictObject({
 		elements: z.number(),
 		attachments: z.number(),
+		marks: z.number(),
 		promptCharacters: z.number(),
 		note: z.string()
-	}).optional().describe("Elements and attachments left out of a concise response"),
+	}).optional().describe("Elements, attachments, and mark pages left out of a concise response"),
 	history: z.array(StatusEvent).optional(),
 	thread: z.array(ThreadEntry).optional()
 });
@@ -801,6 +816,7 @@ function elementView(element, detail) {
 	const full = detail === "full";
 	const view = {
 		n: element.n,
+		url: optionalPageText(element.url, CAP.label),
 		source: optionalPageText(element.source, CAP.label),
 		usedAt: optionalPageText(element.usedAt, CAP.label),
 		owners: element.owners.slice(0, CAP.owners).map((owner) => pageText(owner, CAP.short)),
@@ -840,6 +856,11 @@ function annotationView(record, detail) {
 		})),
 		threadCount: record.thread.length
 	};
+	if (annotation.marks !== void 0) view.marks = annotation.marks.map((mark) => ({
+		n: mark.n,
+		url: pageText(mark.url, CAP.label),
+		route: pageText(mark.route, CAP.label)
+	}));
 	if (full) {
 		view.viewport = annotation.viewport;
 		view.history = state.history;
@@ -861,16 +882,19 @@ function promptPrefix(prompt) {
 	}
 }
 /**
-* Caps the prompt, then keeps the leading elements and attachments that fit CONCISE_BYTES, so
-* `[element n]` and `[attachment n]` keep their numbers, and says how much was left out.
+* Caps the prompt, then keeps the leading elements, attachments, and mark pages that fit
+* CONCISE_BYTES, so `[element n]`, `[attachment n]`, and `## Mark n` keep their numbers, and
+* says how much was left out.
 */
 function withinBudget(view) {
 	const { elements, attachments } = view;
+	const marks = view.marks ?? [];
 	const prompt = promptPrefix(view.prompt);
 	const promptCharacters = view.prompt.length - prompt.length;
-	const omitted = (keptElements, keptAttachments) => ({
+	const omitted = (keptElements, keptAttachments, keptMarks) => ({
 		elements: elements.length - keptElements,
 		attachments: attachments.length - keptAttachments,
+		marks: marks.length - keptMarks,
 		promptCharacters,
 		note: OMITTED_NOTE
 	});
@@ -879,7 +903,8 @@ function withinBudget(view) {
 		prompt,
 		elements: [],
 		attachments: [],
-		omitted: omitted(0, 0)
+		...view.marks !== void 0 && { marks: [] },
+		omitted: omitted(0, 0, 0)
 	});
 	const fit = (items) => {
 		const kept = [];
@@ -893,14 +918,16 @@ function withinBudget(view) {
 	};
 	const keptElements = fit(elements);
 	const keptAttachments = fit(attachments);
-	const result = promptCharacters === 0 && keptElements.length === elements.length && keptAttachments.length === attachments.length ? view : {
+	const keptMarks = fit(marks);
+	const result = promptCharacters === 0 && keptElements.length === elements.length && keptAttachments.length === attachments.length && keptMarks.length === marks.length ? view : {
 		...view,
 		prompt,
 		elements: keptElements,
 		attachments: keptAttachments,
-		omitted: omitted(keptElements.length, keptAttachments.length)
+		...view.marks !== void 0 && { marks: keptMarks },
+		omitted: omitted(keptElements.length, keptAttachments.length, keptMarks.length)
 	};
-	if (jsonBytes(result) > 2e4) throw new PkaError(`The concise view of annotation ${view.id} is over ${CONCISE_BYTES} bytes without its elements and attachments; request detail full.`);
+	if (jsonBytes(result) > 2e4) throw new PkaError(`The concise view of annotation ${view.id} is over ${CONCISE_BYTES} bytes without its elements, attachments, and mark pages; request detail full.`);
 	return result;
 }
 const OMITTED_NOTE = "Left out to keep this response small. get_annotation (pka get) with detail full returns all of them.";
@@ -1108,13 +1135,13 @@ function isOffered(state, claim) {
 	if (claim === void 0) return state.status === "pending";
 	return isOrphaned(state, claim, Date.now());
 }
+async function isOfferedId(store, id) {
+	const state = await readListedState(store, id);
+	return state !== void 0 && !isClosed(state.status) && isOffered(state, await readClaim(store, id));
+}
 async function oldestOffered(store, skip) {
 	const ids = (await listIds(store)).filter((id) => !skip.has(id));
-	const offered = async (id) => {
-		const state = await readListedState(store, id);
-		return state !== void 0 && !isClosed(state.status) && isOffered(state, await readClaim(store, id));
-	};
-	for (let start = 0; start < ids.length; start += SCAN_BATCH) for (const id of await firstMatching(ids.slice(start, start + SCAN_BATCH), SCAN_BATCH, offered)) {
+	for (let start = 0; start < ids.length; start += SCAN_BATCH) for (const id of await firstMatching(ids.slice(start, start + SCAN_BATCH), SCAN_BATCH, (id) => isOfferedId(store, id))) {
 		const record = await loadListed(store, id);
 		if (record !== void 0 && isOffered(record.state, record.claim)) return record;
 	}

package/dist/vite.mjs

@@ -1,7 +1,8 @@
-import { A as createStore, B as Id, C as agentsDir, D as MissingAnnotationError, H as State, I as resolveInside, L as AnnotationDraft, M as isErrno, N as listIds, O as PkaError, R as ErrorGroup, T as AgentPresence, U as ThreadEntry, V as RelativePath, b as upsertErrorGroups, d as checkCaptureFiles, f as create, g as loadAnnotationUpdates, k as checkStoreSize, r as RecordingManifestDraft, t as RecordingErrors, w as liveAgents, z as ID_PATTERN } from "./recording-CpEDddkZ.mjs";
+import { A as createStore, B as Id, C as agentsDir, D as MissingAnnotationError, H as State, I as resolveInside, L as AnnotationDraft, M as isErrno, N as listIds, O as PkaError, R as ErrorGroup, T as AgentPresence, U as ThreadEntry, V as RelativePath, b as upsertErrorGroups, d as checkCaptureFiles, f as create, g as loadAnnotationUpdates, k as checkStoreSize, r as RecordingManifestDraft, t as RecordingErrors, w as liveAgents, z as ID_PATTERN } from "./recording-82fajWWq.mjs";
+import { createRequire } from "node:module";
 import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { constants, watch } from "node:fs";
+import { constants, readFileSync, watch } from "node:fs";
 import { lstat, mkdir, open, readFile, readdir, realpath, rm, stat } from "node:fs/promises";
 import path, { posix } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -27,7 +28,10 @@ const CHANNEL = {
 	presence: "pka:presence",
 	agent: "pka:agent",
 	setup: "pka:setup",
-	setupInfo: "pka:setup-info"
+	setupInfo: "pka:setup-info",
+	update: "pka:update",
+	installUpdate: "pka:install-update",
+	updateResult: "pka:update-result"
 };
 const MAX_CHUNK_BYTES = 524288;
 const CreateMessage = z.strictObject({
@@ -52,6 +56,11 @@ const SymbolicateMessage = z.strictObject({
 });
 const PresenceMessage = z.strictObject({});
 const SetupMessage = z.strictObject({ requestId: Id });
+const Version = z.string().regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/);
+const InstallUpdateMessage = z.strictObject({
+	requestId: Id,
+	version: Version
+});
 z.strictObject({
 	requestId: Id,
 	id: Id,
@@ -97,6 +106,18 @@ z.strictObject({
 	}).nullable(),
 	cause: z.enum(["presence", "change"])
 });
+z.strictObject({
+	current: Version,
+	latest: Version
+});
+z.discriminatedUnion("outcome", [z.strictObject({
+	requestId: Id,
+	outcome: z.enum(["restart", "restart-manually"])
+}), z.strictObject({
+	requestId: Id,
+	outcome: z.literal("failed"),
+	message: z.string()
+})]);
 //#endregion
 //#region src/vite/source.ts
 const ATTRIBUTE = "data-pka-src";
@@ -226,6 +247,213 @@ async function symbolicate(environment, workspaceRoot, stack) {
 	};
 }
 //#endregion
+//#region src/vite/update.ts
+const execFileAsync$1 = promisify(execFile);
+const REGISTRY_LATEST = "https://registry.npmjs.org/pk-annotator/latest";
+const CHECK_TTL_MS = 36e5;
+const INSTALL_TIMEOUT_MS = 3e5;
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+const REGISTRY_SPEC = /^([~^]?)\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["bun.lock", "bun"],
+	["bun.lockb", "bun"],
+	["yarn.lock", "yarn"],
+	["package-lock.json", "npm"]
+];
+const Manifest = z.object({
+	dependencies: z.record(z.string(), z.string()).optional(),
+	devDependencies: z.record(z.string(), z.string()).optional(),
+	packageManager: z.string().optional()
+});
+const Published = z.object({ version: z.string().regex(SEMVER) });
+/** This module's own package.json; a self-reference resolves through its real path. */
+const OWN_MANIFEST = createRequire(import.meta.url).resolve("pk-annotator/package.json");
+const RUNNING = Published.parse(JSON.parse(readFileSync(OWN_MANIFEST, "utf8"))).version;
+function parseVersion(version) {
+	const match = SEMVER.exec(version);
+	if (match === null) throw new Error(`Not a semantic version: ${version}`);
+	return {
+		core: [
+			Number(match[1]),
+			Number(match[2]),
+			Number(match[3])
+		],
+		pre: match[4]
+	};
+}
+/** Whether `candidate` is a later release than `current`; a prerelease never outranks its release. */
+function isNewer(candidate, current) {
+	const next = parseVersion(candidate);
+	const now = parseVersion(current);
+	for (const [index, part] of next.core.entries()) {
+		const other = now.core[index];
+		if (part !== other) return part > other;
+	}
+	return next.pre === void 0 && now.pre !== void 0;
+}
+function installCommand(install, version) {
+	const dev = {
+		pnpm: "--save-dev",
+		npm: "--save-dev",
+		yarn: "--dev",
+		bun: "--dev"
+	}[install.manager];
+	const exact = {
+		pnpm: "--save-exact",
+		npm: "--save-exact",
+		yarn: "--exact",
+		bun: "--exact"
+	}[install.manager];
+	return [
+		install.manager,
+		install.manager === "npm" ? "install" : "add",
+		...install.dev ? [dev] : [],
+		...install.exact ? [exact] : [],
+		`pk-annotator@${version}`
+	];
+}
+async function readManifest(dir) {
+	const file = path.join(dir, "package.json");
+	const text = await readFile(file, "utf8").catch((cause) => {
+		if (isErrno(cause, "ENOENT")) return void 0;
+		throw cause;
+	});
+	if (text === void 0) return void 0;
+	const parsed = Manifest.safeParse(JSON.parse(text));
+	if (!parsed.success) throw new Error(`${file} is not a valid package.json: ${parsed.error.message}`);
+	return parsed.data;
+}
+async function exists(file) {
+	return stat(file).then(() => true, (cause) => {
+		if (isErrno(cause, "ENOENT")) return false;
+		throw cause;
+	});
+}
+/**
+* The manifest that declares pk-annotator, from the Vite root up to the workspace root, and
+* the workspace's package manager. Null when the dependency is not a registry version, for
+* example this repository's fixture or a workspace link.
+*/
+async function findInstall(viteRoot, workspaceRoot) {
+	if (!OWN_MANIFEST.split(path.sep).includes("node_modules")) return null;
+	let declared;
+	for (let dir = path.resolve(viteRoot);; dir = path.dirname(dir)) {
+		const manifest = await readManifest(dir);
+		const dev = manifest?.devDependencies?.["pk-annotator"];
+		const spec = dev ?? manifest?.dependencies?.["pk-annotator"];
+		if (spec !== void 0) {
+			const match = REGISTRY_SPEC.exec(spec);
+			if (match === null) return null;
+			declared = {
+				dir,
+				dev: dev !== void 0,
+				exact: match[1] === ""
+			};
+			break;
+		}
+		if (dir === path.resolve(workspaceRoot) || dir === path.dirname(dir)) return null;
+	}
+	const field = (await readManifest(workspaceRoot))?.packageManager?.split("@")[0];
+	if (field === "pnpm" || field === "npm" || field === "yarn" || field === "bun") return {
+		...declared,
+		manager: field
+	};
+	for (const [lockfile, manager] of LOCKFILES) if (await exists(path.join(workspaceRoot, lockfile))) return {
+		...declared,
+		manager
+	};
+	return null;
+}
+/** The real path of the pk-annotator manifest that `dir` resolves, read fresh from disk. */
+async function resolveInstalled(dir) {
+	for (let from = dir;; from = path.dirname(from)) {
+		const found = await realpath(path.join(from, "node_modules/pk-annotator/package.json")).catch((cause) => {
+			if (isErrno(cause, "ENOENT")) return void 0;
+			throw cause;
+		});
+		if (found !== void 0) return found;
+		if (from === path.dirname(from)) throw new Error(`${dir} resolves no pk-annotator`);
+	}
+}
+/**
+* Checks npm for a newer pk-annotator when a page mounts, at most once an hour, and installs
+* it on request with the workspace's package manager. Nothing runs between those events.
+*/
+function createUpdater(viteRoot, workspaceRoot, warn) {
+	let install;
+	let checked;
+	let installing = false;
+	let staleWarned = false;
+	async function latest() {
+		if (checked === void 0 || Date.now() - checked.at > CHECK_TTL_MS) {
+			const request = fetch(REGISTRY_LATEST, { signal: AbortSignal.timeout(1e4) }).then(async (response) => {
+				if (!response.ok) throw new Error(`${REGISTRY_LATEST} answered ${response.status}`);
+				return Published.parse(await response.json()).version;
+			}).catch((cause) => {
+				warn(`update check failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+				return null;
+			});
+			checked = {
+				at: Date.now(),
+				latest: request
+			};
+		}
+		return checked.latest;
+	}
+	return {
+		/** The update to offer, or null when the installed version is current or not managed by version. */
+		async check() {
+			install ??= findInstall(viteRoot, workspaceRoot);
+			if (await install === null) return null;
+			const onDisk = Published.parse(JSON.parse(await readFile(OWN_MANIFEST, "utf8"))).version;
+			if (onDisk !== RUNNING) {
+				if (!staleWarned) {
+					staleWarned = true;
+					warn(`${onDisk} is installed but ${RUNNING} is running; restart the dev server`);
+				}
+				return null;
+			}
+			const version = await latest();
+			return version !== null && isNewer(version, RUNNING) ? {
+				current: RUNNING,
+				latest: version
+			} : null;
+		},
+		/**
+		* Installs `version`, which must be the release the last check offered. "restart" means a
+		* dev server restart loads it; "restart-manually" means the package was replaced in place,
+		* where Node keeps the old plugin module until the process restarts.
+		*/
+		async install(version) {
+			const target = await install;
+			if (target === void 0 || target === null) throw new Error("This workspace does not install pk-annotator from the npm registry");
+			if (checked === void 0 || await checked.latest !== version) throw new Error(`${version} is not the release last offered`);
+			if (installing) throw new Error("An update is already installing");
+			installing = true;
+			try {
+				const [command, ...args] = installCommand(target, version);
+				try {
+					await execFileAsync$1(command, args, {
+						cwd: target.dir,
+						timeout: INSTALL_TIMEOUT_MS
+					});
+				} catch (cause) {
+					const stderr = cause instanceof Error && "stderr" in cause ? String(cause.stderr).trim() : "";
+					const detail = stderr === "" ? String(cause) : stderr.slice(-600);
+					throw new Error(`${[command, ...args].join(" ")} failed in ${target.dir}: ${detail}`, { cause });
+				}
+				const resolved = await resolveInstalled(target.dir);
+				const installed = Published.parse(JSON.parse(await readFile(resolved, "utf8"))).version;
+				if (installed !== version) throw new Error(`Installed ${version}, but ${target.dir} resolves pk-annotator ${installed}`);
+				return resolved === OWN_MANIFEST ? "restart-manually" : "restart";
+			} finally {
+				installing = false;
+			}
+		}
+	};
+}
+//#endregion
 //#region src/vite/index.ts
 const AnnotatorOptions = z.strictObject({
 	bodies: z.array(z.string().startsWith("/")).optional(),
@@ -544,6 +772,27 @@ async function serve(server, maxStoreBytes, storeRoot) {
 		};
 		client.send(CHANNEL.setupInfo, reply);
 	});
+	const updater = createUpdater(server.config.root, workspaceRoot, warn);
+	listen(CHANNEL.installUpdate, InstallUpdateMessage, async (message, client) => {
+		let result;
+		try {
+			const outcome = await updater.install(message.version);
+			result = {
+				requestId: message.requestId,
+				outcome
+			};
+		} catch (cause) {
+			error(`update to ${message.version} failed: ${describeError(cause)}`);
+			result = {
+				requestId: message.requestId,
+				outcome: "failed",
+				message: describeError(cause)
+			};
+		}
+		client.send(CHANNEL.updateResult, result);
+		if (result.outcome === "restart-manually") warn(`updated to ${message.version}; restart the dev server to load it`);
+		if (result.outcome === "restart") await server.restart();
+	});
 	listen(CHANNEL.sync, SyncMessage, async (message, client) => {
 		const synced = { annotations: [] };
 		for (const id of message.ids) try {
@@ -592,6 +841,9 @@ async function serve(server, maxStoreBytes, storeRoot) {
 		agentQueue = agentQueue.then(async () => pushAgent(await readAgent())).catch((cause) => error(`reading agent presence failed: ${describeError(cause)}`));
 	}
 	listen(CHANNEL.presence, PresenceMessage, async (_message, client) => {
+		updater.check().then((offer) => {
+			if (offer !== null) client.send(CHANNEL.update, offer);
+		}, (cause) => error(`update check failed: ${describeError(cause)}`));
 		const answered = agentQueue.then(async () => {
 			const agent = await readAgent();
 			pushAgent(agent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pk-annotator",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Dev-only browser annotation overlay for Vite apps that sends picked elements, captures, and prompts to Claude Code and Codex through an MCP server.",
   "keywords": [
     "annotation",