@pasko70/pibo 1.9.9 → 1.9.10

package/dist/web-annotations/tools.js

@@ -0,0 +1,350 @@
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { WEB_ANNOTATION_STATUSES, } from "./types.js";
+import { createDefaultWebAnnotationStore } from "./store.js";
+import { assertWebAnnotationStatusTransition, sanitizeWebAnnotationText, WEB_ANNOTATION_LIMITS } from "./validation.js";
+export const WEB_ANNOTATION_TOOL_NAMES = [
+    "web_annotations_list",
+    "web_annotations_get",
+    "web_annotations_watch",
+    "web_annotations_acknowledge",
+    "web_annotations_resolve",
+    "web_annotations_dismiss",
+];
+const DEFAULT_LIST_LIMIT = 20;
+const MAX_LIST_LIMIT = 100;
+const DEFAULT_WATCH_TIMEOUT_MS = 5_000;
+const MAX_WATCH_TIMEOUT_MS = 30_000;
+const WATCH_POLL_MS = 250;
+const TEXT_LIMIT = 280;
+const DETAIL_TEXT_LIMIT = WEB_ANNOTATION_LIMITS.text;
+const SOURCE_HINT_LIMIT = 5;
+let defaultStore;
+function getDefaultStore() {
+    defaultStore ??= createDefaultWebAnnotationStore();
+    return defaultStore;
+}
+function normalizeLimit(limit, fallback = DEFAULT_LIST_LIMIT) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return fallback;
+    return Math.max(1, Math.min(Math.floor(limit), MAX_LIST_LIMIT));
+}
+function normalizeTimeout(timeoutMs) {
+    if (timeoutMs === undefined || !Number.isFinite(timeoutMs))
+        return DEFAULT_WATCH_TIMEOUT_MS;
+    return Math.max(0, Math.min(Math.floor(timeoutMs), MAX_WATCH_TIMEOUT_MS));
+}
+function truncate(value, max = TEXT_LIMIT) {
+    return sanitizeWebAnnotationText(value, { max, field: "web annotation tool output" });
+}
+function requireContext(context, params) {
+    const piboSessionId = params.piboSessionId?.trim() || context.piboSessionId?.trim();
+    if (!piboSessionId)
+        throw new Error("Web Annotation tools require a Pibo Session ID from runtime context or piboSessionId input");
+    return {
+        piboSessionId,
+        piboRoomId: context.piboRoomId,
+    };
+}
+function requireAnnotationId(params) {
+    const id = params.annotationId?.trim();
+    if (!id)
+        throw new Error("annotationId is required");
+    return id;
+}
+function sourceHintSummary(annotation) {
+    const hint = annotation.target?.sourceHints?.[0];
+    if (!hint)
+        return undefined;
+    const location = hint.file
+        ? `${hint.file}${hint.line !== undefined ? `:${hint.line}` : ""}${hint.column !== undefined ? `:${hint.column}` : ""}`
+        : hint.id ?? hint.component;
+    return [hint.kind, hint.confidence, location].filter(Boolean).join(" · ");
+}
+function positionSummary(annotation) {
+    const box = annotation.target?.boundingBox;
+    if (box)
+        return `x${box.x} y${box.y} ${box.width}x${box.height}`;
+    const position = annotation.target?.position;
+    return position ? `x${position.x} y${position.y}` : undefined;
+}
+function compactAnnotation(annotation) {
+    return {
+        id: annotation.id,
+        status: annotation.status,
+        targetKind: annotation.targetKind,
+        url: truncate(annotation.url, 200),
+        label: truncate(annotation.target?.label),
+        selector: truncate(annotation.target?.selector),
+        sourceHint: truncate(sourceHintSummary(annotation)),
+        position: positionSummary(annotation),
+        note: truncate(annotation.note),
+        createdAt: annotation.createdAt,
+        updatedAt: annotation.updatedAt,
+    };
+}
+function detailedAnnotation(annotation) {
+    return {
+        ...compactAnnotation(annotation),
+        piboSessionId: annotation.piboSessionId,
+        piboRoomId: annotation.piboRoomId,
+        bindingId: annotation.bindingId,
+        title: truncate(annotation.title),
+        targetId: annotation.targetId,
+        resolvedAt: annotation.resolvedAt,
+        resolvedBy: annotation.resolvedBy,
+        summary: truncate(annotation.summary, DETAIL_TEXT_LIMIT),
+        viewport: annotation.viewport,
+        screenshotRef: annotation.screenshotRef ? {
+            artifactId: annotation.screenshotRef.artifactId,
+            path: truncate(annotation.screenshotRef.path, 300),
+            mimeType: annotation.screenshotRef.mimeType,
+            width: annotation.screenshotRef.width,
+            height: annotation.screenshotRef.height,
+            createdAt: annotation.screenshotRef.createdAt,
+        } : undefined,
+        target: annotation.target ? {
+            kind: annotation.target.kind,
+            label: truncate(annotation.target.label, DETAIL_TEXT_LIMIT),
+            selector: truncate(annotation.target.selector, DETAIL_TEXT_LIMIT),
+            domPath: truncate(annotation.target.domPath, DETAIL_TEXT_LIMIT),
+            fullDomPath: truncate(annotation.target.fullDomPath, DETAIL_TEXT_LIMIT),
+            tagName: truncate(annotation.target.tagName),
+            stableId: truncate(annotation.target.stableId),
+            classSummary: truncate(annotation.target.classSummary, DETAIL_TEXT_LIMIT),
+            text: truncate(annotation.target.text, DETAIL_TEXT_LIMIT),
+            selectedText: truncate(annotation.target.selectedText, DETAIL_TEXT_LIMIT),
+            htmlHint: truncate(annotation.target.htmlHint, DETAIL_TEXT_LIMIT),
+            accessibility: annotation.target.accessibility,
+            boundingBox: annotation.target.boundingBox,
+            position: annotation.target.position,
+            sourceHints: annotation.target.sourceHints?.slice(0, SOURCE_HINT_LIMIT).map((hint) => ({
+                kind: hint.kind,
+                confidence: hint.confidence,
+                id: truncate(hint.id, DETAIL_TEXT_LIMIT),
+                file: truncate(hint.file, DETAIL_TEXT_LIMIT),
+                line: hint.line,
+                column: hint.column,
+                component: truncate(hint.component, DETAIL_TEXT_LIMIT),
+                componentPath: hint.componentPath?.slice(0, SOURCE_HINT_LIMIT).map((part) => truncate(part, 120) ?? ""),
+            })),
+        } : undefined,
+        thread: annotation.thread?.slice(-10).map((message) => ({
+            id: message.id,
+            role: message.role,
+            content: truncate(message.content, DETAIL_TEXT_LIMIT),
+            createdAt: message.createdAt,
+        })),
+    };
+}
+function listFilter(context, params) {
+    return {
+        piboSessionId: context.piboSessionId,
+        status: params.status,
+        limit: normalizeLimit(params.limit),
+    };
+}
+function formatJson(value) {
+    return JSON.stringify(value, null, 2);
+}
+function ok(text, details) {
+    return { content: [{ type: "text", text }], details };
+}
+function fail(message, details) {
+    return {
+        content: [{ type: "text", text: `Web annotations error: ${message}` }],
+        details: details ?? { ok: false, error: message },
+        isError: true,
+    };
+}
+function getAnnotationForLifecycle(store, context, id) {
+    return store.getAnnotation(context.piboSessionId, id);
+}
+function assertLifecycleTransition(annotation, action) {
+    if (annotation.status === "resolved")
+        throw new Error(`Annotation ${annotation.id} is already resolved`);
+    if (annotation.status === "dismissed")
+        throw new Error(`Annotation ${annotation.id} is already dismissed`);
+    const nextStatus = action === "acknowledge" ? "acknowledged" : action === "resolve" ? "resolved" : "dismissed";
+    assertWebAnnotationStatusTransition(annotation.status, nextStatus);
+}
+function createListTool(store, context) {
+    return defineTool({
+        name: "web_annotations_list",
+        label: "Web Annotations List",
+        description: "List bounded web annotations for the current Pibo session or an explicitly authorized session.",
+        promptSnippet: "List web annotations for this Pibo session. Use status and limit to keep output compact.",
+        parameters: Type.Object({
+            piboSessionId: Type.Optional(Type.String({ description: "Optional Pibo Session ID; defaults to current runtime session." })),
+            status: Type.Optional(StringEnum([...WEB_ANNOTATION_STATUSES], { description: "Optional annotation status filter." })),
+            limit: Type.Optional(Type.Number({ description: "Maximum annotations to return; capped." })),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const resolved = requireContext(context, params);
+                const annotations = store.listAnnotations(listFilter(resolved, params)).map(compactAnnotation);
+                return ok(formatJson({ ok: true, piboSessionId: resolved.piboSessionId, annotations }), {
+                    ok: true,
+                    piboSessionId: resolved.piboSessionId,
+                    annotations,
+                });
+            }
+            catch (error) {
+                return fail(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}
+function createGetTool(store, context) {
+    return defineTool({
+        name: "web_annotations_get",
+        label: "Web Annotations Get",
+        description: "Get one authorized web annotation with bounded target metadata.",
+        promptSnippet: "Get one web annotation by id to inspect target metadata, source hints, note, status, and thread summary.",
+        parameters: Type.Object({
+            annotationId: Type.String({ description: "Web annotation id." }),
+            piboSessionId: Type.Optional(Type.String({ description: "Optional Pibo Session ID; defaults to current runtime session." })),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const resolved = requireContext(context, params);
+                const id = requireAnnotationId(params);
+                const annotation = store.getAnnotation(resolved.piboSessionId, id);
+                if (!annotation)
+                    return fail(`Annotation ${id} was not found for this session`, { ok: false, annotationId: id, piboSessionId: resolved.piboSessionId });
+                const detail = detailedAnnotation(annotation);
+                return ok(formatJson({ ok: true, annotation: detail }), { ok: true, annotation: detail });
+            }
+            catch (error) {
+                return fail(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}
+function createLifecycleTool(name, store, context) {
+    const action = name === "web_annotations_acknowledge" ? "acknowledge" : name === "web_annotations_resolve" ? "resolve" : "dismiss";
+    return defineTool({
+        name,
+        label: name.replaceAll("_", " "),
+        description: `${action[0].toUpperCase()}${action.slice(1)} an authorized web annotation.`,
+        promptSnippet: `${action[0].toUpperCase()}${action.slice(1)} a web annotation after inspecting it and deciding the lifecycle update is appropriate.`,
+        parameters: Type.Object({
+            annotationId: Type.String({ description: "Web annotation id." }),
+            piboSessionId: Type.Optional(Type.String({ description: "Optional Pibo Session ID; defaults to current runtime session." })),
+            summary: Type.Optional(Type.String({ description: "Optional work summary. Used by acknowledge/resolve." })),
+            reason: Type.Optional(Type.String({ description: "Optional dismiss reason." })),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const resolved = requireContext(context, params);
+                const id = requireAnnotationId(params);
+                const existing = getAnnotationForLifecycle(store, resolved, id);
+                if (!existing)
+                    return fail(`Annotation ${id} was not found for this session`, { ok: false, annotationId: id, piboSessionId: resolved.piboSessionId });
+                assertLifecycleTransition(existing, action);
+                const updated = action === "acknowledge"
+                    ? store.acknowledgeAnnotation(resolved.piboSessionId, id, params.summary)
+                    : action === "resolve"
+                        ? store.resolveAnnotation(resolved.piboSessionId, id, params.summary, "agent")
+                        : store.dismissAnnotation(resolved.piboSessionId, id, params.reason);
+                if (!updated)
+                    return fail(`Annotation ${id} could not be updated`, { ok: false, annotationId: id });
+                const detail = compactAnnotation(updated);
+                return ok(formatJson({ ok: true, annotation: detail }), { ok: true, annotation: detail });
+            }
+            catch (error) {
+                return fail(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}
+function createWatchTool(store, context) {
+    return defineTool({
+        name: "web_annotations_watch",
+        label: "Web Annotations Watch",
+        description: "Wait briefly for new web annotations in the current or authorized Pibo session.",
+        promptSnippet: "Wait briefly for new web annotations. Keep timeout bounded; use run-control if a longer background wait is needed.",
+        parameters: Type.Object({
+            piboSessionId: Type.Optional(Type.String({ description: "Optional Pibo Session ID; defaults to current runtime session." })),
+            status: Type.Optional(StringEnum([...WEB_ANNOTATION_STATUSES], { description: "Optional annotation status filter." })),
+            afterCreatedAt: Type.Optional(Type.String({ description: "Only return annotations created after this ISO timestamp." })),
+            limit: Type.Optional(Type.Number({ description: "Maximum annotations to return; capped." })),
+            timeoutMs: Type.Optional(Type.Number({ description: "Bounded wait timeout in milliseconds; capped." })),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const resolved = requireContext(context, params);
+                const timeoutMs = normalizeTimeout(params.timeoutMs);
+                const started = Date.now();
+                const afterCreatedAt = params.afterCreatedAt;
+                while (true) {
+                    const annotations = store.listAnnotations(listFilter(resolved, params))
+                        .filter((annotation) => !afterCreatedAt || annotation.createdAt > afterCreatedAt)
+                        .map(compactAnnotation);
+                    if (annotations.length > 0) {
+                        return ok(formatJson({ ok: true, timedOut: false, piboSessionId: resolved.piboSessionId, annotations }), {
+                            ok: true,
+                            timedOut: false,
+                            piboSessionId: resolved.piboSessionId,
+                            annotations,
+                        });
+                    }
+                    if (Date.now() - started >= timeoutMs) {
+                        return ok(formatJson({ ok: true, timedOut: true, piboSessionId: resolved.piboSessionId, annotations: [] }), {
+                            ok: true,
+                            timedOut: true,
+                            piboSessionId: resolved.piboSessionId,
+                            annotations: [],
+                        });
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, Math.min(WATCH_POLL_MS, timeoutMs)));
+                }
+            }
+            catch (error) {
+                return fail(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}
+export function createWebAnnotationToolProfiles(options = {}) {
+    const store = options.store;
+    const createStore = () => store ?? getDefaultStore();
+    return [
+        {
+            name: "web_annotations_list",
+            description: "List bounded web annotations for the current Pibo session.",
+            yieldable: false,
+            createDefinition: (context) => createListTool(createStore(), context),
+        },
+        {
+            name: "web_annotations_get",
+            description: "Get one authorized web annotation with bounded target metadata.",
+            yieldable: false,
+            createDefinition: (context) => createGetTool(createStore(), context),
+        },
+        {
+            name: "web_annotations_watch",
+            description: "Wait briefly for new web annotations in the current Pibo session.",
+            yieldable: true,
+            createDefinition: (context) => createWatchTool(createStore(), context),
+        },
+        {
+            name: "web_annotations_acknowledge",
+            description: "Acknowledge an authorized web annotation.",
+            yieldable: false,
+            createDefinition: (context) => createLifecycleTool("web_annotations_acknowledge", createStore(), context),
+        },
+        {
+            name: "web_annotations_resolve",
+            description: "Resolve an authorized web annotation with an optional summary.",
+            yieldable: false,
+            createDefinition: (context) => createLifecycleTool("web_annotations_resolve", createStore(), context),
+        },
+        {
+            name: "web_annotations_dismiss",
+            description: "Dismiss an authorized web annotation with an optional reason.",
+            yieldable: false,
+            createDefinition: (context) => createLifecycleTool("web_annotations_dismiss", createStore(), context),
+        },
+    ];
+}

package/dist/web-annotations/types.js

@@ -0,0 +1,34 @@
+export const WEB_ANNOTATION_STATUSES = [
+    "open",
+    "attached",
+    "acknowledged",
+    "applying",
+    "needs_review",
+    "resolved",
+    "dismissed",
+    "failed",
+];
+export const WEB_ANNOTATION_TARGET_KINDS = ["element", "text", "region", "visual", "pin"];
+export const WEB_ANNOTATION_BINDING_STATES = ["active", "injected", "error", "closed", "removed"];
+export const WEB_ANNOTATION_SOURCE_HINT_KINDS = [
+    "pibo-id",
+    "pibo-component",
+    "pibo-debug",
+    "pibo-terminal-row",
+    "pibo-shared-card",
+    "pibo-markdown",
+    "test-id",
+    "locatorjs",
+    "react-fiber",
+    "jsx-source",
+    "dom-fallback",
+];
+export function isWebAnnotationStatus(value) {
+    return WEB_ANNOTATION_STATUSES.includes(value);
+}
+export function isWebAnnotationTargetKind(value) {
+    return WEB_ANNOTATION_TARGET_KINDS.includes(value);
+}
+export function isWebAnnotationBindingState(value) {
+    return WEB_ANNOTATION_BINDING_STATES.includes(value);
+}

package/dist/web-annotations/validation.js

@@ -0,0 +1,288 @@
+import { WEB_ANNOTATION_SOURCE_HINT_KINDS, isWebAnnotationBindingState, isWebAnnotationStatus, isWebAnnotationTargetKind, } from "./types.js";
+export const WEB_ANNOTATION_LIMITS = {
+    id: 160,
+    piboSessionId: 160,
+    piboRoomId: 160,
+    url: 2_000,
+    title: 200,
+    note: 2_000,
+    summary: 2_000,
+    bindingToken: 240,
+    selector: 1_000,
+    domPath: 1_500,
+    fullDomPath: 2_500,
+    tagName: 80,
+    stableId: 240,
+    classSummary: 500,
+    text: 1_000,
+    selectedText: 1_000,
+    htmlHint: 1_000,
+    accessibilityText: 400,
+    sourceHints: 10,
+    sourceHintRawKeys: 30,
+    sourceHintRawArray: 20,
+    sourceHintRawDepth: 4,
+    sourceHintRawString: 500,
+    sourceHintComponentPath: 10,
+    sourceHintText: 500,
+    screenshotRefText: 500,
+    threadMessages: 100,
+    threadMessage: 2_000,
+    attachments: 5,
+};
+const CONTROL_CHARS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
+const SECRET_PATTERNS = [
+    [/\bsk-[A-Za-z0-9_-]{16,}\b/g, "[REDACTED_SECRET]"],
+    [/\bgh[pousr]_[A-Za-z0-9_]{16,}\b/g, "[REDACTED_SECRET]"],
+    [/\bxox[baprs]-[A-Za-z0-9-]{16,}\b/g, "[REDACTED_SECRET]"],
+    [/\b(?:api[_-]?key|token|secret|password)\s*[:=]\s*['\"]?[^\s'\"&<>]{8,}/gi, (match) => {
+            const separator = match.includes("=") ? "=" : ":";
+            return `${match.slice(0, match.indexOf(separator) + 1)}[REDACTED_SECRET]`;
+        }],
+];
+export function redactWebAnnotationSecrets(value) {
+    let redacted = value;
+    for (const [pattern, replacement] of SECRET_PATTERNS) {
+        redacted = typeof replacement === "function"
+            ? redacted.replace(pattern, replacement)
+            : redacted.replace(pattern, replacement);
+    }
+    return redacted;
+}
+export function sanitizeWebAnnotationText(value, options) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error(`${options.field ?? "field"} must be a string`);
+    let text = value.replace(CONTROL_CHARS, "");
+    if (options.redactSecrets !== false)
+        text = redactWebAnnotationSecrets(text);
+    if (options.collapseWhitespace !== false)
+        text = text.replace(/\s+/g, " ");
+    if (options.trim !== false)
+        text = text.trim();
+    if (text.length > options.max)
+        return `${text.slice(0, Math.max(0, options.max - 1))}…`;
+    return text;
+}
+export function requireWebAnnotationText(value, options) {
+    const text = sanitizeWebAnnotationText(value, options) ?? "";
+    if (!text)
+        throw new Error(`${options.field ?? "field"} is required`);
+    return text;
+}
+export function normalizeWebAnnotationLimit(limit, defaultLimit, maxLimit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return defaultLimit;
+    return Math.max(1, Math.min(Math.floor(limit), maxLimit));
+}
+export function normalizeWebAnnotationBindingInput(input) {
+    const normalized = {
+        ...input,
+        id: sanitizeWebAnnotationText(input.id, { max: WEB_ANNOTATION_LIMITS.id, field: "id", redactSecrets: false }),
+        piboSessionId: requireWebAnnotationText(input.piboSessionId, { max: WEB_ANNOTATION_LIMITS.piboSessionId, field: "piboSessionId", redactSecrets: false }),
+        piboRoomId: sanitizeWebAnnotationText(input.piboRoomId, { max: WEB_ANNOTATION_LIMITS.piboRoomId, field: "piboRoomId", redactSecrets: false }),
+        url: requireWebAnnotationText(input.url, { max: WEB_ANNOTATION_LIMITS.url, field: "url", redactSecrets: false }),
+        title: sanitizeWebAnnotationText(input.title, { max: WEB_ANNOTATION_LIMITS.title, field: "title" }),
+        metadata: normalizeWebAnnotationJsonObject(input.metadata, "metadata"),
+    };
+    if (input.state !== undefined && !isWebAnnotationBindingState(input.state))
+        throw new Error(`Invalid binding state: ${input.state}`);
+    return normalized;
+}
+export function normalizeWebAnnotationBindingPatch(patch) {
+    if (patch.state !== undefined && !isWebAnnotationBindingState(patch.state))
+        throw new Error(`Invalid binding state: ${patch.state}`);
+    return {
+        ...patch,
+        title: sanitizeWebAnnotationText(patch.title, { max: WEB_ANNOTATION_LIMITS.title, field: "title" }),
+        targetId: patch.targetId === null ? null : sanitizeWebAnnotationText(patch.targetId, { max: WEB_ANNOTATION_LIMITS.id, field: "targetId", redactSecrets: false }),
+        error: patch.error === null ? null : sanitizeWebAnnotationText(patch.error, { max: WEB_ANNOTATION_LIMITS.summary, field: "error" }),
+        metadata: normalizeWebAnnotationJsonObject(patch.metadata, "metadata"),
+    };
+}
+export function normalizeWebAnnotationCreateInput(input) {
+    if (input.status !== undefined && !isWebAnnotationStatus(input.status))
+        throw new Error(`Invalid annotation status: ${input.status}`);
+    if (!isWebAnnotationTargetKind(input.targetKind))
+        throw new Error(`Invalid annotation target kind: ${input.targetKind}`);
+    return {
+        ...input,
+        id: sanitizeWebAnnotationText(input.id, { max: WEB_ANNOTATION_LIMITS.id, field: "id", redactSecrets: false }),
+        piboSessionId: requireWebAnnotationText(input.piboSessionId, { max: WEB_ANNOTATION_LIMITS.piboSessionId, field: "piboSessionId", redactSecrets: false }),
+        piboRoomId: sanitizeWebAnnotationText(input.piboRoomId, { max: WEB_ANNOTATION_LIMITS.piboRoomId, field: "piboRoomId", redactSecrets: false }),
+        bindingId: sanitizeWebAnnotationText(input.bindingId, { max: WEB_ANNOTATION_LIMITS.id, field: "bindingId", redactSecrets: false }),
+        note: requireWebAnnotationText(input.note, { max: WEB_ANNOTATION_LIMITS.note, field: "note" }),
+        url: requireWebAnnotationText(input.url, { max: WEB_ANNOTATION_LIMITS.url, field: "url", redactSecrets: false }),
+        title: sanitizeWebAnnotationText(input.title, { max: WEB_ANNOTATION_LIMITS.title, field: "title" }),
+        targetId: sanitizeWebAnnotationText(input.targetId, { max: WEB_ANNOTATION_LIMITS.id, field: "targetId", redactSecrets: false }),
+        viewport: normalizeWebAnnotationViewport(input.viewport),
+        target: normalizeWebAnnotationTarget(input.target, input.targetKind),
+        screenshotRef: normalizeWebAnnotationScreenshotRef(input.screenshotRef),
+        metadata: normalizeWebAnnotationJsonObject(input.metadata, "metadata"),
+    };
+}
+export function normalizeWebAnnotationPatchInput(patch) {
+    if (patch.status !== undefined && !isWebAnnotationStatus(patch.status))
+        throw new Error(`Invalid annotation status: ${patch.status}`);
+    if (patch.resolvedBy !== undefined && patch.resolvedBy !== null && patch.resolvedBy !== "human" && patch.resolvedBy !== "agent") {
+        throw new Error("resolvedBy must be human, agent, or null");
+    }
+    return {
+        ...patch,
+        summary: patch.summary === null ? null : sanitizeWebAnnotationText(patch.summary, { max: WEB_ANNOTATION_LIMITS.summary, field: "summary" }),
+        metadata: normalizeWebAnnotationJsonObject(patch.metadata, "metadata"),
+    };
+}
+export function assertWebAnnotationStatusTransition(current, next) {
+    if (!next || next === current)
+        return;
+    if (current === "resolved")
+        throw new Error("resolved annotations cannot transition to another status");
+    if (current === "dismissed")
+        throw new Error("dismissed annotations cannot transition to another status");
+    if (current === "applying" && next === "dismissed")
+        throw new Error("applying annotations cannot be dismissed");
+}
+export function normalizeWebAnnotationThreadMessageInput(input) {
+    if (input.role !== "human" && input.role !== "agent")
+        throw new Error("role must be human or agent");
+    return {
+        ...input,
+        annotationId: requireWebAnnotationText(input.annotationId, { max: WEB_ANNOTATION_LIMITS.id, field: "annotationId", redactSecrets: false }),
+        piboSessionId: requireWebAnnotationText(input.piboSessionId, { max: WEB_ANNOTATION_LIMITS.piboSessionId, field: "piboSessionId", redactSecrets: false }),
+        content: requireWebAnnotationText(input.content, { max: WEB_ANNOTATION_LIMITS.threadMessage, field: "content" }),
+        id: sanitizeWebAnnotationText(input.id, { max: WEB_ANNOTATION_LIMITS.id, field: "id", redactSecrets: false }),
+    };
+}
+export function normalizeWebAnnotationViewport(value) {
+    if (!value || typeof value.width !== "number" || typeof value.height !== "number")
+        throw new Error("viewport width and height are required");
+    return {
+        width: boundedNumber(value.width, 0, 20_000, "viewport.width"),
+        height: boundedNumber(value.height, 0, 20_000, "viewport.height"),
+        devicePixelRatio: value.devicePixelRatio === undefined ? undefined : boundedNumber(value.devicePixelRatio, 0.1, 10, "viewport.devicePixelRatio"),
+    };
+}
+export function normalizeWebAnnotationTarget(value, targetKind) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("target must be an object");
+    return {
+        kind: targetKind,
+        label: sanitizeWebAnnotationText(value.label, { max: WEB_ANNOTATION_LIMITS.text, field: "target.label" }),
+        selector: sanitizeWebAnnotationText(value.selector, { max: WEB_ANNOTATION_LIMITS.selector, field: "target.selector" }),
+        domPath: sanitizeWebAnnotationText(value.domPath, { max: WEB_ANNOTATION_LIMITS.domPath, field: "target.domPath" }),
+        fullDomPath: sanitizeWebAnnotationText(value.fullDomPath, { max: WEB_ANNOTATION_LIMITS.fullDomPath, field: "target.fullDomPath" }),
+        tagName: sanitizeWebAnnotationText(value.tagName, { max: WEB_ANNOTATION_LIMITS.tagName, field: "target.tagName", redactSecrets: false }),
+        stableId: sanitizeWebAnnotationText(value.stableId, { max: WEB_ANNOTATION_LIMITS.stableId, field: "target.stableId" }),
+        classSummary: sanitizeWebAnnotationText(value.classSummary, { max: WEB_ANNOTATION_LIMITS.classSummary, field: "target.classSummary" }),
+        text: sanitizeWebAnnotationText(value.text, { max: WEB_ANNOTATION_LIMITS.text, field: "target.text" }),
+        selectedText: sanitizeWebAnnotationText(value.selectedText, { max: WEB_ANNOTATION_LIMITS.selectedText, field: "target.selectedText" }),
+        htmlHint: sanitizeWebAnnotationText(value.htmlHint, { max: WEB_ANNOTATION_LIMITS.htmlHint, field: "target.htmlHint" }),
+        accessibility: normalizeAccessibilityHint(value.accessibility),
+        boundingBox: value.boundingBox ? {
+            x: boundedNumber(value.boundingBox.x, -100_000, 100_000, "target.boundingBox.x"),
+            y: boundedNumber(value.boundingBox.y, -100_000, 100_000, "target.boundingBox.y"),
+            width: boundedNumber(value.boundingBox.width, 0, 100_000, "target.boundingBox.width"),
+            height: boundedNumber(value.boundingBox.height, 0, 100_000, "target.boundingBox.height"),
+        } : undefined,
+        position: value.position ? {
+            x: boundedNumber(value.position.x, -100_000, 100_000, "target.position.x"),
+            y: boundedNumber(value.position.y, -100_000, 100_000, "target.position.y"),
+        } : undefined,
+        sourceHints: normalizeSourceHints(value.sourceHints),
+    };
+}
+export function normalizeWebAnnotationScreenshotRef(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("screenshotRef must be an object");
+    return {
+        artifactId: sanitizeWebAnnotationText(value.artifactId, { max: WEB_ANNOTATION_LIMITS.screenshotRefText, field: "screenshotRef.artifactId", redactSecrets: false }),
+        path: sanitizeWebAnnotationText(value.path, { max: WEB_ANNOTATION_LIMITS.screenshotRefText, field: "screenshotRef.path", redactSecrets: false }),
+        mimeType: sanitizeWebAnnotationText(value.mimeType, { max: 120, field: "screenshotRef.mimeType", redactSecrets: false }),
+        width: value.width === undefined ? undefined : boundedNumber(value.width, 0, 50_000, "screenshotRef.width"),
+        height: value.height === undefined ? undefined : boundedNumber(value.height, 0, 50_000, "screenshotRef.height"),
+        createdAt: sanitizeWebAnnotationText(value.createdAt, { max: 80, field: "screenshotRef.createdAt", redactSecrets: false }),
+    };
+}
+export function normalizeWebAnnotationJsonObject(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${field} must be an object`);
+    return normalizeJsonObject(value, 0);
+}
+function normalizeAccessibilityHint(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("target.accessibility must be an object");
+    return {
+        role: sanitizeWebAnnotationText(value.role, { max: WEB_ANNOTATION_LIMITS.accessibilityText, field: "target.accessibility.role" }),
+        name: sanitizeWebAnnotationText(value.name, { max: WEB_ANNOTATION_LIMITS.accessibilityText, field: "target.accessibility.name" }),
+        ariaLabel: sanitizeWebAnnotationText(value.ariaLabel, { max: WEB_ANNOTATION_LIMITS.accessibilityText, field: "target.accessibility.ariaLabel" }),
+        focusable: typeof value.focusable === "boolean" ? value.focusable : undefined,
+        description: sanitizeWebAnnotationText(value.description, { max: WEB_ANNOTATION_LIMITS.accessibilityText, field: "target.accessibility.description" }),
+    };
+}
+function normalizeSourceHints(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error("target.sourceHints must be an array");
+    return value.slice(0, WEB_ANNOTATION_LIMITS.sourceHints).map((hint) => {
+        if (!hint || typeof hint !== "object" || Array.isArray(hint))
+            throw new Error("target.sourceHints entries must be objects");
+        if (!WEB_ANNOTATION_SOURCE_HINT_KINDS.includes(hint.kind))
+            throw new Error(`Invalid source hint kind: ${hint.kind}`);
+        if (hint.confidence !== "high" && hint.confidence !== "medium" && hint.confidence !== "low")
+            throw new Error("Invalid source hint confidence");
+        return {
+            kind: hint.kind,
+            confidence: hint.confidence,
+            id: sanitizeWebAnnotationText(hint.id, { max: WEB_ANNOTATION_LIMITS.sourceHintText, field: "sourceHint.id" }),
+            file: sanitizeWebAnnotationText(hint.file, { max: WEB_ANNOTATION_LIMITS.sourceHintText, field: "sourceHint.file" }),
+            line: hint.line === undefined ? undefined : boundedNumber(hint.line, 0, 1_000_000, "sourceHint.line"),
+            column: hint.column === undefined ? undefined : boundedNumber(hint.column, 0, 1_000_000, "sourceHint.column"),
+            component: sanitizeWebAnnotationText(hint.component, { max: WEB_ANNOTATION_LIMITS.sourceHintText, field: "sourceHint.component" }),
+            componentPath: hint.componentPath?.slice(0, WEB_ANNOTATION_LIMITS.sourceHintComponentPath).map((part) => sanitizeWebAnnotationText(part, { max: 120, field: "sourceHint.componentPath" }) ?? ""),
+            raw: normalizeWebAnnotationJsonObject(hint.raw, "sourceHint.raw"),
+        };
+    });
+}
+function normalizeJsonValue(value, depth) {
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "string")
+        return sanitizeWebAnnotationText(value, { max: WEB_ANNOTATION_LIMITS.sourceHintRawString, field: "json" }) ?? "";
+    if (Array.isArray(value)) {
+        if (depth >= WEB_ANNOTATION_LIMITS.sourceHintRawDepth)
+            return [];
+        return value.slice(0, WEB_ANNOTATION_LIMITS.sourceHintRawArray).map((item) => normalizeJsonValue(item, depth + 1));
+    }
+    if (typeof value === "object") {
+        if (depth >= WEB_ANNOTATION_LIMITS.sourceHintRawDepth)
+            return {};
+        return normalizeJsonObject(value, depth + 1);
+    }
+    return null;
+}
+function normalizeJsonObject(value, depth) {
+    const output = {};
+    for (const [key, rawValue] of Object.entries(value).slice(0, WEB_ANNOTATION_LIMITS.sourceHintRawKeys)) {
+        const normalizedKey = sanitizeWebAnnotationText(key, { max: 120, field: "json key" }) ?? "key";
+        output[normalizedKey] = normalizeJsonValue(rawValue, depth);
+    }
+    return output;
+}
+function boundedNumber(value, min, max, field) {
+    if (!Number.isFinite(value))
+        throw new Error(`${field} must be a finite number`);
+    return Math.max(min, Math.min(max, value));
+}