pk-annotator 0.6.0

package/dist/recording-CpEDddkZ.mjs

@@ -0,0 +1,1644 @@
+import { randomBytes } from "node:crypto";
+import { constants, readFileSync, readlinkSync, watch } from "node:fs";
+import { link, lstat, mkdir, open, readdir, realpath, rename, rm, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { hostname } from "node:os";
+//#region src/shared/schema.ts
+const ID_PATTERN = /^[a-z0-9-]{8,40}$/;
+const Id = z.string().regex(ID_PATTERN, "id must match ^[a-z0-9-]{8,40}$");
+const RelativePath = z.string().max(200).regex(/^(?!.*(?:^|\/)\.{1,2}(?:\/|$))[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/, "path must be relative to the annotation directory, without . or .. segments");
+const Timestamp = z.iso.datetime({ offset: true });
+const Viewport = z.strictObject({
+	w: z.number().int().positive(),
+	h: z.number().int().positive(),
+	dpr: z.number().positive(),
+	scrollX: z.number(),
+	scrollY: z.number()
+});
+const Box = z.strictObject({
+	x: z.number(),
+	y: z.number(),
+	w: z.number().nonnegative(),
+	h: z.number().nonnegative()
+});
+const Selector = z.strictObject({
+	role: z.string().optional(),
+	name: z.string().optional(),
+	testId: z.string().optional(),
+	css: z.string()
+});
+const ElementRef = z.strictObject({
+	n: z.number().int().positive(),
+	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()),
+	selector: Selector,
+	html: z.string(),
+	box: Box,
+	crop: RelativePath.optional(),
+	text: z.string().optional(),
+	nearbyText: z.string().optional()
+});
+const AttachmentKind = z.enum([
+	"recording",
+	"errors",
+	"network",
+	"perf",
+	"frame",
+	"video"
+]);
+const Attachment = z.strictObject({
+	kind: AttachmentKind,
+	path: RelativePath,
+	summary: z.string()
+});
+const Annotation = z.strictObject({
+	id: Id,
+	createdAt: Timestamp,
+	url: z.string(),
+	route: z.string(),
+	viewport: Viewport,
+	prompt: z.string(),
+	elements: z.array(ElementRef),
+	attachments: z.array(Attachment)
+});
+const AnnotationDraft = Annotation.omit({
+	id: true,
+	createdAt: true
+});
+const Status = z.enum([
+	"pending",
+	"acknowledged",
+	"resolved",
+	"dismissed"
+]);
+const StatusEvent = z.strictObject({
+	status: Status,
+	at: Timestamp,
+	by: z.string().optional(),
+	note: z.string().optional()
+});
+const State = z.strictObject({
+	status: Status,
+	history: z.array(StatusEvent).min(1)
+});
+/**
+* The claiming process. A pid means something only inside its PID namespace, so `namespace`
+* names that namespace on its host; `startTime` (Linux) tells a reused pid apart.
+*/
+const ClaimProcess = z.strictObject({
+	pid: z.number().int().positive(),
+	namespace: z.string().min(1).max(200),
+	startTime: z.string().regex(/^\d+$/).optional()
+});
+const Claim = z.strictObject({
+	by: z.string().min(1),
+	at: Timestamp,
+	process: ClaimProcess.optional()
+});
+const ThreadEntry = z.strictObject({
+	at: Timestamp,
+	from: z.enum(["agent", "human"]),
+	text: z.string().min(1)
+});
+const ErrorGroupStatus = z.enum([
+	"open",
+	"sent",
+	"cleared"
+]);
+const ErrorGroup = z.strictObject({
+	fingerprint: z.string().min(1).max(200),
+	message: z.string(),
+	type: z.string(),
+	count: z.number().int().positive(),
+	firstSeen: Timestamp,
+	lastSeen: Timestamp,
+	lastSeq: z.number().int().nonnegative(),
+	topFrame: z.string().regex(/^.+:\d+$/, "topFrame must be file:line").optional(),
+	stack: z.string(),
+	status: ErrorGroupStatus
+});
+const LiveErrorsSnapshot = z.strictObject({
+	updatedAt: Timestamp,
+	groups: z.array(ErrorGroup)
+});
+//#endregion
+//#region src/store/store.ts
+const STORE_SUBDIR = path.join("_interim", "annotations");
+const DEFAULT_SIZE_CAP_BYTES = 524288e3;
+const PRUNE_AGE_MS = 6048e5;
+const STAGING_PREFIX = ".creating-";
+const STAGING_AGE_MS = 864e5;
+const CREATE_EXCLUSIVE = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW;
+/** An error whose message is meant for the person or agent that called the operation. */
+var PkaError = class extends Error {
+	name = "PkaError";
+};
+/** The annotation directory does not exist, for example because prune removed it. */
+var MissingAnnotationError = class extends PkaError {
+	name = "MissingAnnotationError";
+};
+function isErrno(cause, code) {
+	return cause instanceof Error && "code" in cause && cause.code === code;
+}
+async function storeUnder(root) {
+	const dir = path.resolve(root, STORE_SUBDIR);
+	try {
+		if (!(await stat(dir)).isDirectory()) throw new PkaError(`${dir} exists but is not a directory`);
+	} catch (thrown) {
+		if (isErrno(thrown, "ENOENT")) return void 0;
+		throw thrown;
+	}
+	return realpath(dir);
+}
+/**
+* Finds the annotation store without creating anything: the explicit root,
+* then CLAUDE_PROJECT_DIR, then the nearest ancestor of cwd that has one.
+*/
+async function findStore(sources) {
+	if (sources.explicit !== void 0) {
+		const store = await storeUnder(sources.explicit);
+		if (store === void 0) throw new PkaError(`No annotation store at ${path.resolve(sources.explicit, STORE_SUBDIR)}. Start the app's Vite dev server with the pk-annotator plugin once to create it, or pass a different --root.`);
+		return store;
+	}
+	if (sources.claudeProjectDir !== void 0) {
+		const store = await storeUnder(sources.claudeProjectDir);
+		if (store !== void 0) return store;
+	}
+	for (let dir = path.resolve(sources.cwd);; dir = path.dirname(dir)) {
+		const store = await storeUnder(dir);
+		if (store !== void 0) return store;
+		if (path.dirname(dir) === dir) break;
+	}
+	const checked = [...new Set([sources.claudeProjectDir, sources.cwd].filter((dir) => dir !== void 0).map((dir) => path.resolve(dir)))];
+	throw new PkaError(`No ${STORE_SUBDIR} found in ${checked.join(" or ")} or any parent directory. Start the app's Vite dev server with the pk-annotator plugin once to create it, or pass --root <project> (or PKA_ROOT).`);
+}
+/** Creates the store under a project root. Only the Vite plugin calls this. */
+async function createStore(projectRoot) {
+	const dir = path.resolve(projectRoot, STORE_SUBDIR);
+	await mkdir(path.join(dir, "live"), { recursive: true });
+	return realpath(dir);
+}
+/** A sortable id: base-36 milliseconds, then random hex. */
+function newId(now) {
+	return `${now.toString(36).padStart(9, "0")}-${randomBytes(4).toString("hex")}`;
+}
+function checkId(id) {
+	if (!ID_PATTERN.test(id)) throw new PkaError(`Invalid annotation id ${JSON.stringify(id)}: ids match ^[a-z0-9-]{8,40}$. List annotations to get a valid id.`);
+	return id;
+}
+function resolveInside(base, ...segments) {
+	const target = path.resolve(base, ...segments);
+	const relative = path.relative(base, target);
+	if (relative === "" || relative.split(path.sep)[0] === ".." || path.isAbsolute(relative)) throw new PkaError(`Path ${segments.join("/")} resolves outside ${base}`);
+	return target;
+}
+/** Refuses a symlink anywhere between the store and the target. Missing components end the walk. */
+async function refuseSymlinks(store, target) {
+	let current = store;
+	for (const segment of path.relative(store, target).split(path.sep)) {
+		current = path.join(current, segment);
+		try {
+			if ((await lstat(current)).isSymbolicLink()) throw new PkaError(`Refusing symlink in the annotation store: ${current}`);
+		} catch (thrown) {
+			if (isErrno(thrown, "ENOENT")) return;
+			throw thrown;
+		}
+	}
+}
+function annotationFiles(store, id) {
+	const dir = resolveInside(store, checkId(id));
+	return {
+		dir,
+		annotation: resolveInside(dir, "annotation.json"),
+		state: resolveInside(dir, "state.json"),
+		claim: resolveInside(dir, "claim.json"),
+		thread: resolveInside(dir, "thread.jsonl")
+	};
+}
+function liveErrorsFile(store) {
+	return resolveInside(store, "live", "errors.json");
+}
+function processAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (cause) {
+		return !isErrno(cause, "ESRCH");
+	}
+}
+/** Field 22 of /proc/<pid>/stat, clock ticks after boot. The command name before it may hold spaces and parentheses. */
+function linuxStartTime(pid) {
+	const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+	const field = stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19];
+	if (field === void 0 || !/^\d+$/.test(field)) throw new Error(`Unexpected /proc/${pid}/stat: ${stat}`);
+	return field;
+}
+let ownNamespace;
+/**
+* Names this process's PID namespace on its host. Every Linux host gives its initial
+* namespace the same inode, so the boot id tells hosts (and boots) apart.
+*/
+function pidNamespace() {
+	ownNamespace ??= process.platform === "linux" ? `linux:${readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()}:${readlinkSync("/proc/self/ns/pid")}` : `${process.platform}:${hostname()}`;
+	return ownNamespace;
+}
+let ownProcess;
+/** This process, as recorded in a claim or lock so another process can tell when it has exited. */
+function thisProcess() {
+	if (ownProcess === void 0) {
+		ownProcess = {
+			pid: process.pid,
+			namespace: pidNamespace()
+		};
+		if (process.platform === "linux") ownProcess.startTime = linuxStartTime("self");
+	}
+	return ownProcess;
+}
+/**
+* True only when this process can tell that `owner` has exited: it names a process in this
+* PID namespace, and that pid is gone or now belongs to a process started later. A process
+* from another namespace is never judged.
+*/
+function processExited(owner) {
+	if (owner.namespace !== pidNamespace()) return false;
+	if (owner.startTime !== void 0) try {
+		return linuxStartTime(owner.pid) !== owner.startTime;
+	} catch (cause) {
+		if (![
+			"ENOENT",
+			"ESRCH",
+			"EACCES",
+			"EPERM"
+		].some((code) => isErrno(cause, code))) throw cause;
+	}
+	return !processAlive(owner.pid);
+}
+/** Throws a PkaError naming the next step when the annotation directory is absent. */
+async function requireAnnotation(store, id) {
+	const files = annotationFiles(store, id);
+	try {
+		const info = await lstat(files.dir);
+		if (info.isSymbolicLink()) throw new PkaError(`Refusing symlink in the annotation store: ${files.dir}`);
+		if (!info.isDirectory()) throw new PkaError(`${files.dir} is not a directory`);
+	} catch (thrown) {
+		if (isErrno(thrown, "ENOENT")) throw new MissingAnnotationError(`No annotation ${id}. List annotations to see the ids that exist.`);
+		throw thrown;
+	}
+	return files;
+}
+async function readText(store, file) {
+	await refuseSymlinks(store, file);
+	const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+	try {
+		return await handle.readFile("utf8");
+	} finally {
+		await handle.close();
+	}
+}
+function parseWith(schema, text, where) {
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch (thrown) {
+		throw new PkaError(`Invalid JSON in ${where}`, { cause: thrown });
+	}
+	const parsed = schema.safeParse(data);
+	if (!parsed.success) throw new PkaError(`Invalid data in ${where}:\n${z.prettifyError(parsed.error)}`);
+	return parsed.data;
+}
+async function readJson(store, file, schema) {
+	return parseWith(schema, await readText(store, file), file);
+}
+/** Reads a JSON-lines file; an absent file has no entries. */
+async function readJsonLines(store, file, schema) {
+	let text;
+	try {
+		text = await readText(store, file);
+	} catch (thrown) {
+		if (isErrno(thrown, "ENOENT")) return [];
+		throw thrown;
+	}
+	return text.split("\n").flatMap((line, index) => line.trim() === "" ? [] : [parseWith(schema, line, `${file}:${index + 1}`)]);
+}
+async function writeExclusive(file, data) {
+	const handle = await open(file, CREATE_EXCLUSIVE, 420);
+	try {
+		await handle.writeFile(data);
+	} finally {
+		await handle.close();
+	}
+}
+function temporaryName(file) {
+	return `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+}
+/** Writes through a temporary file and a rename, so readers see the old or the new content. */
+async function writeJsonAtomic(store, file, value) {
+	await refuseSymlinks(store, path.dirname(file));
+	const temporary = temporaryName(file);
+	try {
+		await writeExclusive(temporary, `${JSON.stringify(value, null, 2)}\n`);
+		await rename(temporary, file);
+	} catch (thrown) {
+		await rm(temporary, { force: true });
+		throw thrown;
+	}
+}
+async function appendJsonLine(store, file, value) {
+	await refuseSymlinks(store, file);
+	const handle = await open(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 420);
+	try {
+		await handle.write(`${JSON.stringify(value)}\n`);
+	} finally {
+		await handle.close();
+	}
+}
+/**
+* Claims an annotation. The claim is written to a temporary file opened with
+* O_EXCL | O_NOFOLLOW and then hard-linked into place, so exactly one caller
+* wins and a loser never reads a half-written claim. A claim that disappears
+* before the loser reads it was removed by replaceClaim, so the link is retried.
+*/
+async function createClaim(store, id, claim) {
+	const files = await requireAnnotation(store, id);
+	const temporary = temporaryName(files.claim);
+	await writeExclusive(temporary, `${JSON.stringify(claim)}\n`);
+	try {
+		for (;;) {
+			try {
+				await link(temporary, files.claim);
+				return {
+					won: true,
+					claim
+				};
+			} catch (thrown) {
+				if (!isErrno(thrown, "EEXIST")) throw thrown;
+			}
+			try {
+				return {
+					won: false,
+					claim: await readJson(store, files.claim, Claim)
+				};
+			} catch (thrown) {
+				if (!isErrno(thrown, "ENOENT")) throw thrown;
+			}
+		}
+	} finally {
+		await unlink(temporary);
+	}
+}
+/** Replaces claim.json with `claim` in one rename, so it never goes missing. Hold the annotation lock. */
+async function writeClaim(store, id, claim) {
+	const files = await requireAnnotation(store, id);
+	await refuseSymlinks(store, files.claim);
+	const temporary = temporaryName(files.claim);
+	try {
+		await writeExclusive(temporary, `${JSON.stringify(claim)}\n`);
+		await rename(temporary, files.claim);
+	} catch (thrown) {
+		await rm(temporary, { force: true });
+		throw thrown;
+	}
+}
+/** How long a caller waits for a lock whose owner is still running before it reports it. */
+const LOCK_WAIT_MS = 1e4;
+const LockOwner = z.strictObject({
+	token: z.string().regex(/^[0-9a-f]{16}$/),
+	process: ClaimProcess
+});
+async function readLockOwner(store, lock) {
+	try {
+		return await readJson(store, lock, LockOwner);
+	} catch (thrown) {
+		if (isErrno(thrown, "ENOENT")) return void 0;
+		throw thrown;
+	}
+}
+function lockChange(lock, deadline) {
+	const name = path.basename(lock);
+	const watcher = watch(path.dirname(lock));
+	let failure;
+	let finish = () => {};
+	const settled = new Promise((resolve) => {
+		finish = resolve;
+	});
+	watcher.on("change", (_event, changedName) => {
+		if (changedName === null || changedName === name) finish();
+	});
+	watcher.on("error", (cause) => {
+		failure = cause;
+		finish();
+	});
+	const timer = setTimeout(finish, Math.max(0, deadline - Date.now()));
+	return {
+		async changed() {
+			await settled;
+			if (failure !== void 0) throw failure;
+		},
+		close() {
+			watcher.close();
+			clearTimeout(timer);
+		}
+	};
+}
+/**
+* Takes the lock file `lock` and returns its token. The owner record is complete before the
+* link makes it visible. A lock whose owner has exited is broken. A caller waits for a lock
+* whose owner runs, or cannot be judged from this PID namespace, by watching for its removal
+* until `deadline`; it then checks the owner once more and reports a lock that is still held,
+* never removing it. A killed owner writes nothing, so a caller already waiting finds it
+* dead only at the deadline.
+*/
+async function acquireLock(store, lock, deadline) {
+	const token = randomBytes(8).toString("hex");
+	const temporary = temporaryName(lock);
+	await writeExclusive(temporary, `${JSON.stringify({
+		token,
+		process: thisProcess()
+	})}\n`);
+	try {
+		for (;;) {
+			const wake = lockChange(lock, deadline);
+			try {
+				try {
+					await link(temporary, lock);
+					return token;
+				} catch (thrown) {
+					if (!isErrno(thrown, "EEXIST")) throw thrown;
+				}
+				const owner = await readLockOwner(store, lock);
+				if (owner === void 0) continue;
+				if (processExited(owner.process)) {
+					await breakLock(store, lock, owner, deadline);
+					continue;
+				}
+				if (Date.now() >= deadline) throw new PkaError(`${lock} is held by process ${owner.process.pid} (${owner.process.namespace}); retry later. A process in another PID namespace cannot be checked from here: remove the file only after that process has exited.`);
+				await wake.changed();
+			} finally {
+				wake.close();
+			}
+		}
+	} finally {
+		await unlink(temporary);
+	}
+}
+/**
+* Removes `lock` if it still names the exited owner `dead`. Breakers of one owner take turns
+* through a lock of their own, so while one rereads and removes `lock`, no other caller can
+* remove it: a breaker that read `dead` long ago finds the newer lock and leaves it.
+*/
+async function breakLock(store, lock, dead, deadline) {
+	await withLock(store, `${lock}.${dead.token}.break`, deadline, async () => {
+		if ((await readLockOwner(store, lock))?.token === dead.token) await unlink(lock);
+	});
+}
+async function withLock(store, lock, deadline, act) {
+	const token = await acquireLock(store, lock, deadline);
+	let result;
+	try {
+		result = await act();
+	} catch (thrown) {
+		await releaseLock(store, lock, token);
+		throw thrown;
+	}
+	await releaseLock(store, lock, token);
+	return result;
+}
+async function releaseLock(store, lock, token) {
+	const owner = await readLockOwner(store, lock);
+	if (owner === void 0) return;
+	if (owner.token !== token) throw new Error(`${lock} was replaced by process ${owner.process.pid} while held`);
+	await rm(lock, { force: true });
+}
+/**
+* Runs `act` while this caller alone holds the annotation's state.lock, so status, claim,
+* reply, and attachment writes from separate processes never interleave. Read the state that
+* `act` decides on inside it. A crashed holder's lock is removed only once its process is
+* known to have exited.
+*/
+async function withAnnotationLock(store, id, act) {
+	const files = await requireAnnotation(store, id);
+	return withLock(store, resolveInside(files.dir, "state.lock"), Date.now() + LOCK_WAIT_MS, () => act(files));
+}
+async function readClaim(store, id) {
+	const files = annotationFiles(store, id);
+	try {
+		return await readJson(store, files.claim, Claim);
+	} catch (thrown) {
+		if (isErrno(thrown, "ENOENT")) return void 0;
+		throw thrown;
+	}
+}
+/** Annotation ids in the store, oldest first. Symlinks and other names are skipped. */
+async function listIds(store) {
+	return (await readdir(store, { withFileTypes: true })).filter((entry) => entry.isDirectory() && ID_PATTERN.test(entry.name)).map((entry) => entry.name).sort();
+}
+/**
+* Writes a complete annotation directory in a staging directory and renames it
+* into place. With `staged`, that directory already holds the listed capture
+* files and becomes the annotation directory; otherwise a new one is made.
+*/
+async function writeAnnotationDir(store, id, files, staged) {
+	const dir = annotationFiles(store, id).dir;
+	const staging = resolveInside(store, staged?.dir ?? `${STAGING_PREFIX}${id}`);
+	try {
+		if (staged === void 0) await mkdir(staging);
+		else for (const relative of staged.paths) {
+			const file = resolveInside(staging, relative);
+			await refuseSymlinks(store, file);
+			if (!(await lstat(file)).isFile()) throw new PkaError(`Staged capture file ${relative} is not a regular file`);
+		}
+		for (const file of files) {
+			const target = resolveInside(staging, file.path);
+			await mkdir(path.dirname(target), { recursive: true });
+			await writeExclusive(target, file.data);
+		}
+		await rename(staging, dir);
+	} catch (thrown) {
+		await rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw thrown;
+	}
+	return dir;
+}
+/**
+* Adds files to an existing annotation directory without overwriting any:
+* each is written to a temporary file and hard-linked into place. If one
+* fails, the files already placed are removed. Returns the placed paths.
+*/
+async function placeNewFiles(store, dir, files) {
+	const placed = [];
+	try {
+		for (const file of files) {
+			const target = resolveInside(dir, file.path);
+			await refuseSymlinks(store, path.dirname(target));
+			await mkdir(path.dirname(target), { recursive: true });
+			const temporary = temporaryName(target);
+			try {
+				await writeExclusive(temporary, file.data);
+				await link(temporary, target);
+			} catch (thrown) {
+				if (isErrno(thrown, "EEXIST")) throw new PkaError(`${file.path} already exists in ${dir}`);
+				throw thrown;
+			} finally {
+				await rm(temporary, { force: true });
+			}
+			placed.push(target);
+		}
+	} catch (thrown) {
+		await Promise.all(placed.map((target) => rm(target, { force: true })));
+		throw thrown;
+	}
+	return placed;
+}
+/**
+* Removes resolved and dismissed annotations whose last status change is
+* older than seven days, and staging directories left by a crashed writer.
+*/
+async function prune$1(store, now) {
+	const removed = [];
+	for (const entry of await readdir(store, { withFileTypes: true })) {
+		if (entry.isDirectory() && entry.name.startsWith(STAGING_PREFIX)) {
+			const staging = resolveInside(store, entry.name);
+			if (now - (await lstat(staging)).mtimeMs > STAGING_AGE_MS) {
+				await rm(staging, {
+					recursive: true,
+					force: true
+				});
+				removed.push(entry.name);
+			}
+			continue;
+		}
+		if (!entry.isDirectory() || !ID_PATTERN.test(entry.name)) continue;
+		const files = annotationFiles(store, entry.name);
+		const state = await readJson(store, files.state, State);
+		const last = state.history.at(-1);
+		if (last === void 0) throw new PkaError(`${files.state} has an empty history`);
+		if ((state.status === "resolved" || state.status === "dismissed") && now - Date.parse(last.at) > PRUNE_AGE_MS) {
+			await rm(files.dir, {
+				recursive: true,
+				force: true
+			});
+			removed.push(entry.name);
+		}
+	}
+	return removed;
+}
+/** Total size of regular files in the store; the plugin refuses new video when it is over the cap. */
+async function checkStoreSize(store, capBytes = DEFAULT_SIZE_CAP_BYTES) {
+	let bytes = 0;
+	for (const entry of await readdir(store, {
+		withFileTypes: true,
+		recursive: true
+	})) if (entry.isFile()) bytes += (await lstat(path.join(entry.parentPath, entry.name))).size;
+	return {
+		bytes,
+		capBytes,
+		overCap: bytes > capBytes
+	};
+}
+//#endregion
+//#region src/shared/agent.ts
+/** Presence files of running pka-mcp sessions, relative to the store. */
+const AGENTS_DIR = ["live", "agents"];
+const AgentPresence = z.strictObject({
+	name: z.string().min(1).max(200),
+	version: z.string().max(200),
+	pid: z.number().int().positive(),
+	connectedAt: Timestamp
+});
+//#endregion
+//#region src/ops/presence.ts
+function agentsDir(store) {
+	return resolveInside(store, ...AGENTS_DIR);
+}
+/**
+* True only when this process can tell that the claimant's process has exited; see
+* processExited. A claim without a process (the CLI) is never judged.
+*/
+function claimantExited(claim) {
+	return claim.process !== void 0 && processExited(claim.process);
+}
+/** Reads the presence files and removes those whose process has exited. */
+async function liveAgents(store) {
+	const dir = agentsDir(store);
+	let names;
+	try {
+		names = await readdir(dir);
+	} catch (cause) {
+		if (isErrno(cause, "ENOENT")) return {
+			agents: [],
+			invalid: []
+		};
+		throw cause;
+	}
+	const result = {
+		agents: [],
+		invalid: []
+	};
+	for (const name of names) {
+		if (!name.endsWith(".json")) continue;
+		const file = resolveInside(dir, name);
+		let presence;
+		try {
+			presence = await readJson(store, file, AgentPresence);
+		} catch (cause) {
+			if (isErrno(cause, "ENOENT")) continue;
+			if (!(cause instanceof PkaError)) throw cause;
+			result.invalid.push({
+				file,
+				reason: cause.message
+			});
+			continue;
+		}
+		if (processAlive(presence.pid)) result.agents.push(presence);
+		else await rm(file, { force: true });
+	}
+	result.agents.sort((a, b) => Date.parse(b.connectedAt) - Date.parse(a.connectedAt));
+	return result;
+}
+//#endregion
+//#region src/ops/views.ts
+const Detail = z.enum(["concise", "full"]);
+const CAP = {
+	short: 300,
+	label: 500,
+	text: 1e3,
+	html: 4e3,
+	stack: 8e3,
+	owners: 12
+};
+/**
+* UTF-8 bytes of a concise annotation or list page, so it stays well under Claude Code's
+* 10k-token warning. detail full has no budget.
+*/
+const CONCISE_BYTES = 2e4;
+function jsonBytes(value) {
+	return Buffer.byteLength(JSON.stringify(value));
+}
+const CONTROL = /(?![\t\n])\p{Cc}/gu;
+const BIDI = /\p{Bidi_Control}/gu;
+/** Strips control and bidirectional-override characters from page-derived text and caps its length. */
+function pageText(value, max) {
+	return capped(value.replace(CONTROL, "").replace(BIDI, ""), max);
+}
+function capped(value, max) {
+	if (value.length <= max) return value;
+	return `${value.slice(0, max)}… [${value.length - max} more characters]`;
+}
+function optionalPageText(value, max) {
+	return value === void 0 ? void 0 : pageText(value, max);
+}
+const ElementView = z.strictObject({
+	n: z.number(),
+	source: z.string().optional(),
+	usedAt: z.string().optional(),
+	owners: z.array(z.string()),
+	selector: z.strictObject({
+		role: z.string().optional(),
+		name: z.string().optional(),
+		testId: z.string().optional(),
+		css: z.string()
+	}),
+	crop: z.string().optional(),
+	text: z.string().optional(),
+	nearbyText: z.string().optional(),
+	html: z.string().optional(),
+	box: Box.optional()
+});
+const AnnotationView = z.strictObject({
+	id: Id,
+	createdAt: Timestamp,
+	status: Status,
+	claimedBy: z.string().optional(),
+	dir: z.string().describe("Absolute annotation directory; attachment and crop paths are relative to it"),
+	url: z.string(),
+	route: z.string(),
+	viewport: Viewport.optional(),
+	prompt: z.string().describe("The human's request"),
+	elements: z.array(ElementView),
+	attachments: z.array(z.strictObject({
+		kind: AttachmentKind,
+		path: z.string(),
+		summary: z.string().optional()
+	})),
+	threadCount: z.number(),
+	omitted: z.strictObject({
+		elements: z.number(),
+		attachments: z.number(),
+		promptCharacters: z.number(),
+		note: z.string()
+	}).optional().describe("Elements and attachments left out of a concise response"),
+	history: z.array(StatusEvent).optional(),
+	thread: z.array(ThreadEntry).optional()
+});
+const ListItem = z.strictObject({
+	id: Id,
+	createdAt: Timestamp,
+	status: Status,
+	claimedBy: z.string().optional(),
+	route: z.string(),
+	prompt: z.string(),
+	elementCount: z.number(),
+	attachmentCount: z.number()
+});
+const ErrorGroupView = z.strictObject({
+	fingerprint: z.string(),
+	type: z.string(),
+	message: z.string(),
+	count: z.number(),
+	lastSeen: Timestamp,
+	topFrame: z.string().optional(),
+	status: ErrorGroupStatus,
+	firstSeen: Timestamp.optional(),
+	lastSeq: z.number().optional(),
+	stack: z.string().optional()
+});
+function elementView(element, detail) {
+	const full = detail === "full";
+	const view = {
+		n: element.n,
+		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)),
+		selector: {
+			role: optionalPageText(element.selector.role, CAP.short),
+			name: optionalPageText(element.selector.name, CAP.short),
+			testId: optionalPageText(element.selector.testId, CAP.short),
+			css: pageText(element.selector.css, CAP.label)
+		},
+		crop: element.crop,
+		text: optionalPageText(element.text, full ? CAP.text : CAP.short)
+	};
+	if (full) {
+		view.nearbyText = optionalPageText(element.nearbyText, CAP.text);
+		view.html = pageText(element.html, CAP.html);
+		view.box = element.box;
+	}
+	return view;
+}
+function annotationView(record, detail) {
+	const { annotation, state } = record;
+	const full = detail === "full";
+	const view = {
+		id: annotation.id,
+		createdAt: annotation.createdAt,
+		status: state.status,
+		claimedBy: record.claim === void 0 || full ? record.claim?.by : capped(record.claim.by, CAP.short),
+		dir: record.dir,
+		url: pageText(annotation.url, CAP.label),
+		route: pageText(annotation.route, CAP.label),
+		prompt: annotation.prompt,
+		elements: annotation.elements.map((element) => elementView(element, detail)),
+		attachments: annotation.attachments.map((attachment) => ({
+			kind: attachment.kind,
+			path: attachment.path,
+			summary: pageText(attachment.summary, full ? CAP.text : CAP.short)
+		})),
+		threadCount: record.thread.length
+	};
+	if (full) {
+		view.viewport = annotation.viewport;
+		view.history = state.history;
+		view.thread = record.thread;
+		return view;
+	}
+	return withinBudget(view);
+}
+/** Most of CONCISE_BYTES that the human's prompt may take, so its elements still fit. */
+const PROMPT_BYTES = 1e4;
+/** The longest leading part of `prompt` whose JSON string fits PROMPT_BYTES. */
+function promptPrefix(prompt) {
+	let length = Math.min(prompt.length, PROMPT_BYTES);
+	for (;;) {
+		if (/[\uD800-\uDBFF]/.test(prompt.charAt(length - 1))) length -= 1;
+		const bytes = Buffer.byteLength(JSON.stringify(prompt.slice(0, length)));
+		if (bytes <= PROMPT_BYTES) return prompt.slice(0, length);
+		length = Math.floor(length * PROMPT_BYTES / bytes);
+	}
+}
+/**
+* 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.
+*/
+function withinBudget(view) {
+	const { elements, attachments } = view;
+	const prompt = promptPrefix(view.prompt);
+	const promptCharacters = view.prompt.length - prompt.length;
+	const omitted = (keptElements, keptAttachments) => ({
+		elements: elements.length - keptElements,
+		attachments: attachments.length - keptAttachments,
+		promptCharacters,
+		note: OMITTED_NOTE
+	});
+	let used = jsonBytes({
+		...view,
+		prompt,
+		elements: [],
+		attachments: [],
+		omitted: omitted(0, 0)
+	});
+	const fit = (items) => {
+		const kept = [];
+		for (const item of items) {
+			const bytes = jsonBytes(item) + 1;
+			if (used + bytes > 2e4) break;
+			used += bytes;
+			kept.push(item);
+		}
+		return kept;
+	};
+	const keptElements = fit(elements);
+	const keptAttachments = fit(attachments);
+	const result = promptCharacters === 0 && keptElements.length === elements.length && keptAttachments.length === attachments.length ? view : {
+		...view,
+		prompt,
+		elements: keptElements,
+		attachments: keptAttachments,
+		omitted: omitted(keptElements.length, keptAttachments.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.`);
+	return result;
+}
+const OMITTED_NOTE = "Left out to keep this response small. get_annotation (pka get) with detail full returns all of them.";
+function listItem(record) {
+	const { annotation } = record;
+	return {
+		id: annotation.id,
+		createdAt: annotation.createdAt,
+		status: record.state.status,
+		claimedBy: record.claim === void 0 ? void 0 : capped(record.claim.by, CAP.short),
+		route: pageText(annotation.route, CAP.label),
+		prompt: annotation.prompt.length > CAP.short ? `${annotation.prompt.slice(0, CAP.short)}…` : annotation.prompt,
+		elementCount: annotation.elements.length,
+		attachmentCount: annotation.attachments.length
+	};
+}
+function errorGroupView(group, detail) {
+	const full = detail === "full";
+	const view = {
+		fingerprint: pageText(group.fingerprint, CAP.short),
+		type: pageText(group.type, CAP.short),
+		message: pageText(group.message, full ? CAP.text : CAP.short),
+		count: group.count,
+		lastSeen: group.lastSeen,
+		topFrame: optionalPageText(group.topFrame, CAP.label),
+		status: group.status
+	};
+	if (full) {
+		view.firstSeen = group.firstSeen;
+		view.lastSeq = group.lastSeq;
+		view.stack = pageText(group.stack, CAP.stack);
+	}
+	return view;
+}
+//#endregion
+//#region src/ops/ops.ts
+const PROGRESS_INTERVAL_MS = 15e3;
+/** A claim this old on a still-pending annotation lost its claimant between the claim and the state write. */
+const ORPHANED_CLAIM_MS = 6e4;
+const MAX_ERROR_GROUPS = 200;
+/** Annotations read at once by a scan; libuv runs four file system calls in parallel by default. */
+const SCAN_BATCH = 16;
+const detailField = Detail.default("concise").describe("concise (default) keeps the response small; full adds HTML, boxes, nearby text, summaries, history, and the thread");
+const limitField = z.number().int().min(1).max(100).default(20);
+const ListInput = z.strictObject({
+	status: z.enum([...Status.options, "all"]).default("pending").describe("Filter by status; pending by default"),
+	limit: limitField,
+	cursor: Id.optional().describe("nextCursor from the previous page"),
+	detail: detailField
+});
+const GetInput = z.strictObject({
+	id: Id,
+	detail: detailField
+});
+const SetStatusInput = z.strictObject({
+	id: Id,
+	status: z.enum([
+		"acknowledged",
+		"resolved",
+		"dismissed"
+	]),
+	note: z.string().min(1).max(2e3).optional().describe("What was done, or why it was dismissed")
+});
+const ReplyInput = z.strictObject({
+	id: Id,
+	text: z.string().min(1).max(1e4)
+});
+const ErrorsInput = z.strictObject({
+	since: Timestamp.optional().describe("Only groups seen at or after this ISO time"),
+	limit: limitField,
+	detail: detailField
+});
+z.strictObject({
+	items: z.array(z.union([ListItem, AnnotationView])),
+	nextCursor: Id.optional()
+});
+z.strictObject({ annotation: AnnotationView });
+z.strictObject({
+	timedOut: z.boolean(),
+	annotation: AnnotationView.optional()
+});
+z.strictObject({
+	id: Id,
+	status: Status,
+	changed: z.boolean(),
+	claimedBy: z.string().optional()
+});
+z.strictObject({
+	id: Id,
+	entry: ThreadEntry
+});
+z.strictObject({
+	updatedAt: Timestamp.nullable().describe("null when the dev server has not recorded errors yet"),
+	total: z.number().describe("Open groups that matched before the limit"),
+	groups: z.array(ErrorGroupView)
+});
+/** Reads one annotation with its state, claim, and thread. The Vite plugin uses it to push changes. */
+async function loadAnnotation(store, id) {
+	const files = await requireAnnotation(store, id);
+	const [annotation, state, claim, thread] = await Promise.all([
+		readJson(store, files.annotation, Annotation),
+		readJson(store, files.state, State),
+		readClaim(store, id),
+		readJsonLines(store, files.thread, ThreadEntry)
+	]);
+	if (annotation.id !== id) throw new PkaError(`${files.annotation} has id ${annotation.id}, expected ${id}`);
+	return {
+		dir: files.dir,
+		annotation,
+		state,
+		claim,
+		thread
+	};
+}
+/**
+* Reads the parts of an annotation that change after it is written: its state and reply
+* thread. The Vite plugin uses it to push changes without rereading annotation.json.
+*/
+async function loadAnnotationUpdates(store, id) {
+	const files = await requireAnnotation(store, id);
+	const [state, thread] = await Promise.all([readJson(store, files.state, State), readJsonLines(store, files.thread, ThreadEntry)]);
+	return {
+		dir: files.dir,
+		state,
+		thread
+	};
+}
+/** Like loadAnnotation, but an annotation removed between listing and reading (prune, rm) is absent. */
+async function loadListed(store, id) {
+	try {
+		return await loadAnnotation(store, id);
+	} catch (thrown) {
+		if (thrown instanceof MissingAnnotationError || isErrno(thrown, "ENOENT")) return void 0;
+		throw thrown;
+	}
+}
+/** An annotation removed after listing (prune, rm) has no state. */
+async function readListedState(store, id) {
+	try {
+		return await readJson(store, annotationFiles(store, id).state, State);
+	} catch (thrown) {
+		if (isErrno(thrown, "ENOENT")) return void 0;
+		throw thrown;
+	}
+}
+/**
+* Returns up to `want` of `ids` that `matches` accepts, in order. Ids are checked in
+* batches, so a store of resolved annotations costs one small state read per id.
+*/
+async function firstMatching(ids, want, matches) {
+	const found = [];
+	for (let start = 0; start < ids.length && found.length < want; start += SCAN_BATCH) {
+		const batch = ids.slice(start, start + SCAN_BATCH);
+		const accepted = await Promise.all(batch.map(matches));
+		found.push(...batch.filter((_, index) => accepted[index]));
+	}
+	return found.slice(0, want);
+}
+async function list(store, input) {
+	const ids = (await listIds(store)).filter((id) => input.cursor === void 0 || id > input.cursor);
+	const { status } = input;
+	const matched = status === "all" ? ids.slice(0, input.limit + 1) : await firstMatching(ids, input.limit + 1, async (id) => (await readListedState(store, id))?.status === status);
+	const page = matched.slice(0, input.limit);
+	const items = [];
+	let bytes = jsonBytes({
+		items: [],
+		nextCursor: page.at(-1)
+	});
+	for (let start = 0; start < page.length; start += SCAN_BATCH) {
+		const records = await Promise.all(page.slice(start, start + SCAN_BATCH).map((id) => loadListed(store, id)));
+		for (const record of records) {
+			if (record === void 0 || status !== "all" && record.state.status !== status) continue;
+			if (input.detail === "full") {
+				items.push(annotationView(record, "full"));
+				continue;
+			}
+			const item = listItem(record);
+			bytes += jsonBytes(item) + 1;
+			const last = items.at(-1);
+			if (last !== void 0 && bytes > 2e4) return {
+				items,
+				nextCursor: last.id
+			};
+			items.push(item);
+		}
+	}
+	return {
+		items,
+		nextCursor: matched.length > input.limit ? page.at(-1) : void 0
+	};
+}
+async function get(store, input) {
+	return { annotation: annotationView(await loadAnnotation(store, input.id), input.detail) };
+}
+/**
+* An open annotation's claim is orphaned when its claimant's process has exited, or, when
+* that cannot be told, when it is old and the annotation is still pending.
+*/
+function isOrphaned(state, claim, now) {
+	if (isClosed(state.status)) return false;
+	if (claimantExited(claim)) return true;
+	return state.status === "pending" && now - Date.parse(claim.at) > ORPHANED_CLAIM_MS;
+}
+function isOffered(state, claim) {
+	if (claim === void 0) return state.status === "pending";
+	return isOrphaned(state, claim, Date.now());
+}
+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)) {
+		const record = await loadListed(store, id);
+		if (record !== void 0 && isOffered(record.state, record.claim)) return record;
+	}
+}
+/**
+* Returns the oldest offered annotation (pending and unclaimed, or open with an orphaned
+* claim) at once if there is one.
+* Otherwise holds one fs.watch on the store until one appears, the timeout
+* elapses, or the signal aborts. The watcher and timers are released on every
+* outcome.
+*/
+function wait(store, options) {
+	const { signal } = options;
+	signal?.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const started = Date.now();
+		let settled = false;
+		let scanning = false;
+		let rescan = false;
+		const watcher = watch(store, { persistent: true }, (_event, name) => {
+			if (name === null || ID_PATTERN.test(name)) scan();
+		});
+		const timeout = options.timeoutMs === void 0 ? void 0 : setTimeout(() => settle({ timedOut: true }, void 0), options.timeoutMs);
+		const { onProgress } = options;
+		const progress = onProgress === void 0 ? void 0 : setInterval(() => onProgress(Date.now() - started), PROGRESS_INTERVAL_MS);
+		const onAbort = () => settle(void 0, signal?.reason);
+		signal?.addEventListener("abort", onAbort, { once: true });
+		watcher.on("error", (cause) => settle(void 0, cause));
+		function settle(result, cause) {
+			if (settled) return;
+			settled = true;
+			watcher.close();
+			clearTimeout(timeout);
+			clearInterval(progress);
+			signal?.removeEventListener("abort", onAbort);
+			if (result === void 0) reject(cause);
+			else resolve(result);
+		}
+		async function scan() {
+			if (scanning) {
+				rescan = true;
+				return;
+			}
+			scanning = true;
+			try {
+				do {
+					rescan = false;
+					const record = await oldestOffered(store, options.skip);
+					if (settled) return;
+					if (record !== void 0) {
+						settle({
+							timedOut: false,
+							annotation: annotationView(record, "concise")
+						}, void 0);
+						return;
+					}
+				} while (rescan && !settled);
+			} catch (cause) {
+				settle(void 0, cause);
+			} finally {
+				scanning = false;
+			}
+		}
+		scan();
+	});
+}
+function isClosed(status) {
+	return status === "resolved" || status === "dismissed";
+}
+function closedError(id, status) {
+	return new PkaError(`Annotation ${id} is ${status}; reply before set_status ${status}.`);
+}
+function claimedError(id, claim) {
+	return new PkaError(claimantExited(claim) ? `Annotation ${id} was claimed by ${claim.by} at ${claim.at}, whose session has exited. Call set_status acknowledged to take it over, then retry.` : `Annotation ${id} was claimed by ${claim.by} at ${claim.at}. Pick another pending annotation.`);
+}
+function requireClaimant(id, claim, by) {
+	if (claim !== void 0 && claim.by !== by) throw claimedError(id, claim);
+}
+/**
+* `owner` identifies a long-lived claimant's process, so its claim can be taken over once it
+* exits. The decision and the write happen under the annotation lock, so a competing change
+* from another process is either seen here or sees this one.
+*/
+async function setStatus(store, input, by, owner) {
+	return withAnnotationLock(store, input.id, async (files) => {
+		const state = await readJson(store, files.state, State);
+		if (isClosed(state.status)) {
+			if (state.status === input.status) return {
+				id: input.id,
+				status: state.status,
+				changed: false
+			};
+			throw closedError(input.id, state.status);
+		}
+		let claim = await readClaim(store, input.id);
+		const at = (/* @__PURE__ */ new Date()).toISOString();
+		if (input.status === "acknowledged") {
+			const mine = owner === void 0 ? {
+				by,
+				at
+			} : {
+				by,
+				at,
+				process: owner
+			};
+			let tookOver = false;
+			if (claim === void 0) {
+				if (state.status !== "pending") throw new PkaError(`Annotation ${input.id} is ${state.status}. Pick another pending annotation.`);
+				claim = (await createClaim(store, input.id, mine)).claim;
+			} else if (claim.by !== by && isOrphaned(state, claim, Date.parse(at))) {
+				await writeClaim(store, input.id, mine);
+				claim = mine;
+				tookOver = true;
+			}
+			requireClaimant(input.id, claim, by);
+			if (state.status !== "pending" && !tookOver) return {
+				id: input.id,
+				status: state.status,
+				changed: false,
+				claimedBy: by
+			};
+		} else requireClaimant(input.id, claim, by);
+		const event = {
+			status: input.status,
+			at,
+			by
+		};
+		if (input.note !== void 0) event.note = input.note;
+		await writeJsonAtomic(store, files.state, {
+			status: input.status,
+			history: [...state.history, event]
+		});
+		return {
+			id: input.id,
+			status: input.status,
+			changed: true,
+			claimedBy: input.status === "acknowledged" ? by : void 0
+		};
+	});
+}
+async function reply(store, input, by) {
+	return withAnnotationLock(store, input.id, async (files) => {
+		const state = await readJson(store, files.state, State);
+		if (isClosed(state.status)) throw closedError(input.id, state.status);
+		requireClaimant(input.id, await readClaim(store, input.id), by);
+		const entry = {
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			from: "agent",
+			text: input.text
+		};
+		await appendJsonLine(store, files.thread, entry);
+		return {
+			id: input.id,
+			entry
+		};
+	});
+}
+async function readErrors(store) {
+	try {
+		return await readJson(store, liveErrorsFile(store), LiveErrorsSnapshot);
+	} catch (thrown) {
+		if (isErrno(thrown, "ENOENT")) return void 0;
+		throw thrown;
+	}
+}
+async function errors(store, input) {
+	const snapshot = await readErrors(store);
+	if (snapshot === void 0) return {
+		updatedAt: null,
+		total: 0,
+		groups: []
+	};
+	const since = input.since === void 0 ? void 0 : Date.parse(input.since);
+	const open = snapshot.groups.filter((group) => group.status === "open" && (since === void 0 || Date.parse(group.lastSeen) >= since)).sort((a, b) => Date.parse(b.lastSeen) - Date.parse(a.lastSeen));
+	return {
+		updatedAt: snapshot.updatedAt,
+		total: open.length,
+		groups: open.slice(0, input.limit).map((group) => errorGroupView(group, input.detail))
+	};
+}
+/** Merges new or changed groups into live/errors.json by fingerprint. Used by the Vite plugin. */
+async function upsertErrorGroups(store, groups) {
+	const merged = new Map(((await readErrors(store))?.groups ?? []).map((group) => [group.fingerprint, group]));
+	for (const group of groups) merged.set(group.fingerprint, group);
+	const snapshot = {
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		groups: [...merged.values()].sort((a, b) => Date.parse(b.lastSeen) - Date.parse(a.lastSeen)).slice(0, MAX_ERROR_GROUPS)
+	};
+	await writeJsonAtomic(store, liveErrorsFile(store), snapshot);
+	return snapshot;
+}
+/**
+* Checks the capture files an annotation declares: each under capture/, listed
+* once, and every attachment and crop path among them.
+*/
+function checkCaptureFiles(draft, paths) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const file of paths) {
+		if (!file.startsWith("capture/")) throw new PkaError(`Capture file ${file} must be under capture/`);
+		if (seen.has(file)) throw new PkaError(`Capture file ${file} is listed twice`);
+		seen.add(file);
+	}
+	const missing = [...draft.attachments.map((attachment) => attachment.path), ...draft.elements.flatMap((element) => element.crop === void 0 ? [] : [element.crop])].filter((reference) => !seen.has(reference));
+	if (missing.length > 0) throw new PkaError(`Annotation references files that were not sent: ${missing.join(", ")}`);
+}
+/**
+* Writes a new pending annotation. Capture files are staged on disk by the
+* Vite plugin and move into place with the annotation in one directory rename.
+*/
+async function create(store, draft, staged) {
+	checkCaptureFiles(draft, staged?.paths ?? []);
+	const now = /* @__PURE__ */ new Date();
+	const id = newId(now.getTime());
+	const annotation = Annotation.parse({
+		id,
+		createdAt: now.toISOString(),
+		...draft
+	});
+	const state = {
+		status: "pending",
+		history: [{
+			status: "pending",
+			at: now.toISOString()
+		}]
+	};
+	await writeAnnotationDir(store, id, [{
+		path: "annotation.json",
+		data: `${JSON.stringify(annotation, null, 2)}\n`
+	}, {
+		path: "state.json",
+		data: `${JSON.stringify(state, null, 2)}\n`
+	}], staged);
+	return { id };
+}
+async function checkAttachTarget(store, files, id, by) {
+	const state = await readJson(store, files.state, State);
+	if (isClosed(state.status)) throw closedError(id, state.status);
+	requireClaimant(id, await readClaim(store, id), by);
+}
+/**
+* Fails as attach would when the annotation is missing, closed, or claimed by another
+* claimant, without writing. Check before expensive work; attach checks again because the
+* annotation can change in between.
+*/
+async function validateAttachTarget(store, id, by) {
+	await checkAttachTarget(store, await requireAnnotation(store, id), id, by);
+}
+/**
+* Adds files to an existing annotation's capture/ directory and lists them in
+* annotation.json. An agent write: resolved and dismissed annotations refuse
+* it. Existing files are never overwritten; on any failure no new file stays
+* behind and annotation.json is unchanged.
+*/
+async function attach(store, id, files, by) {
+	const added = files.map((file) => {
+		const parsed = Attachment.safeParse({
+			kind: file.kind,
+			path: file.path,
+			summary: file.summary
+		});
+		if (!parsed.success) throw new PkaError(`Invalid attachment ${file.path}:\n${z.prettifyError(parsed.error)}`);
+		return parsed.data;
+	});
+	return withAnnotationLock(store, id, async (paths) => {
+		await checkAttachTarget(store, paths, id, by);
+		const annotation = await readJson(store, paths.annotation, Annotation);
+		checkCaptureFiles({
+			...annotation,
+			elements: [],
+			attachments: added
+		}, added.map((attachment) => attachment.path));
+		const listed = new Set(annotation.attachments.map((attachment) => attachment.path));
+		const relisted = added.filter((attachment) => listed.has(attachment.path));
+		if (relisted.length > 0) throw new PkaError(`Annotation ${id} already lists ${relisted.map((a) => a.path).join(", ")}`);
+		const placed = await placeNewFiles(store, paths.dir, files.map((file) => ({
+			path: file.path,
+			data: file.data
+		})));
+		const next = {
+			...annotation,
+			attachments: [...annotation.attachments, ...added]
+		};
+		try {
+			await writeJsonAtomic(store, paths.annotation, next);
+		} catch (thrown) {
+			await Promise.all(placed.map((file) => rm(file, { force: true })));
+			throw thrown;
+		}
+		return {
+			id,
+			attachments: next.attachments
+		};
+	});
+}
+async function prune(store) {
+	return { removed: await prune$1(store, Date.now()) };
+}
+//#endregion
+//#region src/shared/timeline.ts
+const Seq$1 = z.number().int().nonnegative();
+const ConsoleEntry = z.strictObject({
+	kind: z.literal("console"),
+	seq: Seq$1,
+	at: Timestamp,
+	level: z.enum([
+		"log",
+		"info",
+		"warn",
+		"error",
+		"debug"
+	]),
+	args: z.array(z.json())
+});
+const ErrorSource = z.enum([
+	"window",
+	"resource",
+	"rejection",
+	"console",
+	"react-caught",
+	"react-uncaught",
+	"react-recoverable"
+]);
+const ErrorEntry = z.strictObject({
+	kind: z.literal("error"),
+	seq: Seq$1,
+	at: Timestamp,
+	source: ErrorSource,
+	fingerprint: z.string().min(1).max(200),
+	type: z.string(),
+	message: z.string(),
+	stack: z.string().optional(),
+	componentStack: z.string().optional(),
+	ownerStack: z.string().optional(),
+	resource: z.strictObject({
+		tag: z.string(),
+		url: z.string()
+	}).optional()
+});
+const ServerTiming = z.strictObject({
+	name: z.string(),
+	duration: z.number(),
+	description: z.string()
+});
+const RequestEntry = z.strictObject({
+	kind: z.literal("request"),
+	seq: Seq$1,
+	at: Timestamp,
+	performanceMs: z.number().nonnegative().optional(),
+	initiator: z.enum(["fetch", "xhr"]),
+	method: z.string(),
+	url: z.string(),
+	state: z.enum([
+		"pending",
+		"open",
+		"done",
+		"failed",
+		"aborted"
+	]),
+	status: z.number().int().nonnegative().optional(),
+	error: z.string().optional(),
+	durationMs: z.number().nonnegative().optional(),
+	requestSize: z.number().int().nonnegative().optional(),
+	responseSize: z.number().int().nonnegative().optional(),
+	transferSize: z.number().int().nonnegative().optional(),
+	responseType: z.string().optional(),
+	contentType: z.string().optional(),
+	stream: z.boolean(),
+	serverFn: z.boolean(),
+	traceparent: z.string().optional(),
+	requestHeaders: z.record(z.string(), z.string()),
+	responseHeaders: z.record(z.string(), z.string()),
+	requestBody: z.string().optional(),
+	responseBody: z.string().optional(),
+	serverTiming: z.array(ServerTiming).optional()
+});
+const ActionTarget = z.strictObject({
+	tag: z.string(),
+	id: z.string().optional(),
+	testId: z.string().optional(),
+	src: z.string().optional(),
+	role: z.string().optional(),
+	text: z.string().optional(),
+	label: z.string().optional()
+});
+const ActionEntry = z.strictObject({
+	kind: z.literal("action"),
+	seq: Seq$1,
+	at: Timestamp,
+	performanceMs: z.number().nonnegative().optional(),
+	durationMs: z.number().nonnegative().optional(),
+	type: z.enum([
+		"click",
+		"input",
+		"change",
+		"submit",
+		"keydown"
+	]),
+	key: z.enum(["Enter", "Escape"]).optional(),
+	target: ActionTarget
+});
+const NavigationEntry = z.strictObject({
+	kind: z.literal("navigation"),
+	seq: Seq$1,
+	at: Timestamp,
+	type: z.enum([
+		"load",
+		"push",
+		"replace",
+		"reload",
+		"traverse"
+	]),
+	from: z.string().optional(),
+	to: z.string()
+});
+const TimelineEntry = z.discriminatedUnion("kind", [
+	ConsoleEntry,
+	ErrorEntry,
+	RequestEntry,
+	ActionEntry,
+	NavigationEntry
+]);
+//#endregion
+//#region src/shared/recording.ts
+const Seq = z.number().int().nonnegative();
+const Count = z.number().int().nonnegative();
+const RecordingFrame = z.strictObject({
+	path: RelativePath,
+	seq: Seq,
+	at: Timestamp
+});
+const RecordingVideo = z.union([z.strictObject({
+	path: RelativePath,
+	mimeType: z.string(),
+	bytes: Count,
+	startedAt: Timestamp,
+	endedAt: Timestamp,
+	restrictedTo: z.literal("body"),
+	truncated: z.boolean()
+}), z.strictObject({
+	path: z.null(),
+	reason: z.string()
+})]);
+const RecordingManifestDraft = z.strictObject({
+	url: z.string(),
+	endUrl: z.string(),
+	viewport: Viewport,
+	startedAt: Timestamp,
+	endedAt: Timestamp,
+	seq: z.strictObject({
+		first: Seq,
+		last: Seq
+	}).nullable(),
+	entries: z.strictObject({
+		recorded: Count,
+		limit: Count,
+		dropped: Count
+	}),
+	bodies: z.strictObject({
+		limitBytes: Count,
+		dropped: Count
+	}),
+	frames: z.strictObject({
+		items: z.array(RecordingFrame),
+		limit: Count,
+		dropped: Count,
+		failed: Count
+	}),
+	video: RecordingVideo,
+	region: Box.nullable().optional(),
+	gif: z.strictObject({
+		path: RelativePath,
+		width: Count,
+		height: Count,
+		frames: Count,
+		durationMs: Count,
+		truncated: z.boolean()
+	}).optional(),
+	redaction: z.strictObject({
+		inputs: z.literal("values never recorded; masked in keyframes"),
+		headers: z.literal("credential headers dropped"),
+		urlParams: z.literal("credential-like values replaced with REDACTED"),
+		bodies: z.array(z.string()),
+		storage: z.literal("not read"),
+		video: z.literal("not redacted; shows what the tab showed, typed values included")
+	})
+});
+const RecordingManifest = RecordingManifestDraft.extend({ gitSha: z.string().regex(/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/).nullable() });
+const RecordingErrors = z.strictObject({ groups: z.array(ErrorGroup) });
+const Header = z.strictObject({
+	name: z.string(),
+	value: z.string()
+});
+RequestEntry.pick({
+	seq: true,
+	state: true,
+	initiator: true,
+	error: true,
+	stream: true,
+	serverFn: true,
+	traceparent: true,
+	serverTiming: true
+}).extend({
+	startedDateTime: Timestamp,
+	time: z.number().nonnegative().nullable(),
+	request: z.strictObject({
+		method: z.string(),
+		url: z.string(),
+		headers: z.array(Header),
+		bodySize: z.number().int().min(-1),
+		postData: z.strictObject({
+			mimeType: z.string(),
+			text: z.string()
+		}).optional()
+	}),
+	response: z.strictObject({
+		status: Count,
+		headers: z.array(Header),
+		content: z.strictObject({
+			size: z.number().int().min(-1),
+			mimeType: z.string(),
+			text: z.string().optional()
+		}),
+		transferSize: z.number().int().min(-1)
+	})
+});
+//#endregion
+export { createStore as A, Id as B, agentsDir as C, MissingAnnotationError as D, DEFAULT_SIZE_CAP_BYTES as E, readJsonLines as F, State as H, resolveInside as I, AnnotationDraft as L, isErrno as M, listIds as N, PkaError as O, readJson as P, ErrorGroup as R, wait as S, AgentPresence as T, ThreadEntry as U, RelativePath as V, Timestamp as W, prune as _, ErrorsInput as a, upsertErrorGroups as b, ReplyInput as c, checkCaptureFiles as d, create as f, loadAnnotationUpdates as g, list as h, TimelineEntry as i, findStore as j, checkStoreSize as k, SetStatusInput as l, get as m, RecordingManifest as n, GetInput as o, errors as p, RecordingManifestDraft as r, ListInput as s, RecordingErrors as t, attach as u, reply as v, liveAgents as w, validateAttachTarget as x, setStatus as y, ID_PATTERN as z };