@shawnowen/comet-mcp 2.3.0 → 2.4.1

package/dist/discovery/description-template.d.ts

@@ -0,0 +1,40 @@
+/**
+ * description-template.ts
+ * R10 description template renderer (Spec 042, T031).
+ *
+ * Produces consistent, searchable descriptions for virtual MCP tool entries.
+ * Format: "<verb> <object> [<modifier>]. Source: <layer>. Safety: <class>. [multi-agent clause for CAUTION]"
+ *
+ * Constraints (from spec):
+ *   - Min 24 chars, max 400 chars
+ *   - CAUTION entries MUST include the cross-session warning phrase
+ */
+import type { SafetyClass, SourceLayer } from "./capability-entry.js";
+export declare const CAUTION_MULTI_AGENT_CLAUSE: string;
+export interface DescriptionOptions {
+    /** Short verb phrase: e.g. "Capture a screenshot" */
+    verbPhrase: string;
+    /** Optional modifier appended after verbPhrase: e.g. "in this agent's tab" */
+    modifier?: string;
+    /** Source layer — appended as "Source: <layer>." */
+    sourceLayer: SourceLayer;
+    /** Safety class — appended as "Safety: <class>." */
+    safety: SafetyClass;
+}
+/**
+ * Render the R10 description for a capability entry.
+ * Returns a string between MIN_LENGTH and MAX_LENGTH characters.
+ * Throws if the rendered string is outside those bounds.
+ */
+export declare function renderDescription(opts: DescriptionOptions): string;
+/**
+ * Safe version — returns the string if valid, or an error-annotated fallback.
+ * Used when the verbPhrase is untrusted (e.g. from plugin YAML frontmatter).
+ */
+export declare function renderDescriptionSafe(opts: DescriptionOptions, fallback?: string): string;
+/**
+ * Render a CAUTION description with the mandatory multi-agent clause.
+ * Convenience wrapper for T033.
+ */
+export declare function renderCautionDescription(verbPhrase: string, sourceLayer: SourceLayer, modifier?: string): string;
+//# sourceMappingURL=description-template.d.ts.map

package/dist/discovery/description-template.js

@@ -0,0 +1,61 @@
+/**
+ * description-template.ts
+ * R10 description template renderer (Spec 042, T031).
+ *
+ * Produces consistent, searchable descriptions for virtual MCP tool entries.
+ * Format: "<verb> <object> [<modifier>]. Source: <layer>. Safety: <class>. [multi-agent clause for CAUTION]"
+ *
+ * Constraints (from spec):
+ *   - Min 24 chars, max 400 chars
+ *   - CAUTION entries MUST include the cross-session warning phrase
+ */
+// Canonical cross-session warning for CAUTION tools.
+// Must appear verbatim in every CAUTION entry description (tested in T029).
+export const CAUTION_MULTI_AGENT_CLAUSE = "CAUTION: may have cross-session side effects — only use on your own session and tab group. " +
+    "Never close or modify browser resources you did not create.";
+const MIN_LENGTH = 24;
+const MAX_LENGTH = 400;
+/**
+ * Render the R10 description for a capability entry.
+ * Returns a string between MIN_LENGTH and MAX_LENGTH characters.
+ * Throws if the rendered string is outside those bounds.
+ */
+export function renderDescription(opts) {
+    const { verbPhrase, modifier, sourceLayer, safety } = opts;
+    let text = verbPhrase.trimEnd();
+    if (modifier)
+        text += " " + modifier.trim();
+    text += ". ";
+    text += `Source: ${sourceLayer}. Safety: ${safety}.`;
+    if (safety === "CAUTION") {
+        text += " " + CAUTION_MULTI_AGENT_CLAUSE;
+    }
+    if (text.length < MIN_LENGTH) {
+        throw new RangeError(`Description too short (${text.length} < ${MIN_LENGTH}): "${text}"`);
+    }
+    if (text.length > MAX_LENGTH) {
+        throw new RangeError(`Description too long (${text.length} > ${MAX_LENGTH}): "${text.slice(0, 80)}…"`);
+    }
+    return text;
+}
+/**
+ * Safe version — returns the string if valid, or an error-annotated fallback.
+ * Used when the verbPhrase is untrusted (e.g. from plugin YAML frontmatter).
+ */
+export function renderDescriptionSafe(opts, fallback) {
+    try {
+        return renderDescription(opts);
+    }
+    catch {
+        const fb = fallback ?? `${opts.verbPhrase}. Source: ${opts.sourceLayer}. Safety: ${opts.safety}.`;
+        return fb.slice(0, MAX_LENGTH);
+    }
+}
+/**
+ * Render a CAUTION description with the mandatory multi-agent clause.
+ * Convenience wrapper for T033.
+ */
+export function renderCautionDescription(verbPhrase, sourceLayer, modifier) {
+    return renderDescription({ verbPhrase, modifier, sourceLayer, safety: "CAUTION" });
+}
+//# sourceMappingURL=description-template.js.map

package/dist/discovery/golden-queries.fixture.d.ts

@@ -0,0 +1,22 @@
+/**
+ * golden-queries.fixture.ts
+ * Hand-picked golden query set for US1 ToolSearch ranking tests (Spec 042, T025).
+ *
+ * Each entry describes a natural-language query an agent might issue plus the
+ * canonical tool name expected to appear in the top 5 ToolSearch results.
+ *
+ * Coverage targets: SC-002 (≥ 95% top-5 hit rate = 19/20 queries must hit).
+ * At least one query per safety class and per major capability area.
+ */
+export interface GoldenQuery {
+    /** Natural language query the agent would type into ToolSearch */
+    query: string;
+    /** canonicalId of the entry that must appear in the top-5 results */
+    expectedCanonicalId: string;
+    /** Expected tool name for direct assertion */
+    expectedToolName: string;
+    /** Human note explaining why this query should resolve to this tool */
+    note: string;
+}
+export declare const GOLDEN_QUERIES: GoldenQuery[];
+//# sourceMappingURL=golden-queries.fixture.d.ts.map

package/dist/discovery/golden-queries.fixture.js

@@ -0,0 +1,137 @@
+/**
+ * golden-queries.fixture.ts
+ * Hand-picked golden query set for US1 ToolSearch ranking tests (Spec 042, T025).
+ *
+ * Each entry describes a natural-language query an agent might issue plus the
+ * canonical tool name expected to appear in the top 5 ToolSearch results.
+ *
+ * Coverage targets: SC-002 (≥ 95% top-5 hit rate = 19/20 queries must hit).
+ * At least one query per safety class and per major capability area.
+ */
+export const GOLDEN_QUERIES = [
+    // ── Observation / SAFE tools ─────────────────────────────────────────────
+    {
+        query: "observe browser status",
+        expectedCanonicalId: "comet-observe",
+        expectedToolName: "comet_observe",
+        note: "Primary observation tool — should rank #1 for status queries",
+    },
+    {
+        query: "health check browser extension",
+        expectedCanonicalId: "comet-observe",
+        expectedToolName: "comet_observe",
+        note: "Health check is a sub-action of comet_observe",
+    },
+    {
+        query: "peek at another agent tab",
+        expectedCanonicalId: "comet-peek",
+        expectedToolName: "comet_peek",
+        note: "Cross-agent read-only inspection without affecting the tab",
+    },
+    {
+        query: "inspect tab screenshot cross agent",
+        expectedCanonicalId: "comet-peek",
+        expectedToolName: "comet_peek",
+        note: "comet_peek action=screenshot for another agent's tab",
+    },
+    {
+        query: "list all tab groups",
+        expectedCanonicalId: "comet-tab-groups",
+        expectedToolName: "comet_tab_groups",
+        note: "Tab group management including list action",
+    },
+    {
+        query: "equabot task thread running agents",
+        expectedCanonicalId: "comet-task-status",
+        expectedToolName: "comet_task_status",
+        note: "SAFE status overview tool for orchestrator agents",
+    },
+    // ── Session tools (SESSION class) ────────────────────────────────────────
+    {
+        query: "connect to Comet browser start session",
+        expectedCanonicalId: "comet-connect",
+        expectedToolName: "comet_connect",
+        note: "Entry-point for all browser work — must rank first for connect queries",
+    },
+    {
+        query: "take a screenshot of current page",
+        expectedCanonicalId: "comet-screenshot",
+        expectedToolName: "comet_screenshot",
+        note: "Explicit screenshot request in the session context",
+    },
+    {
+        query: "full page screenshot dark mode",
+        expectedCanonicalId: "comet-screenshot",
+        expectedToolName: "comet_screenshot",
+        note: "Natural-language screenshot variant — must appear in top 5",
+    },
+    {
+        query: "navigate to url open page",
+        expectedCanonicalId: "comet-navigate",
+        expectedToolName: "comet_navigate",
+        note: "Explicit navigate request",
+    },
+    {
+        query: "read page content extract text markdown",
+        expectedCanonicalId: "comet-read-page",
+        expectedToolName: "comet_read_page",
+        note: "Content extraction from the current tab",
+    },
+    {
+        query: "click button fill form interact",
+        expectedCanonicalId: "comet-interact",
+        expectedToolName: "comet_interact",
+        note: "DOM interaction — click/type/fill queries",
+    },
+    {
+        query: "ask perplexity research question ai",
+        expectedCanonicalId: "comet-ask",
+        expectedToolName: "comet_ask",
+        note: "Primary research/AI-prompt tool",
+    },
+    {
+        query: "generate pdf print page document",
+        expectedCanonicalId: "comet-pdf",
+        expectedToolName: "comet_pdf",
+        note: "PDF export from current tab",
+    },
+    {
+        query: "scrape extract table structured data",
+        expectedCanonicalId: "comet-scrape",
+        expectedToolName: "comet_scrape",
+        note: "Structured data extraction",
+    },
+    {
+        query: "capture network requests api traffic",
+        expectedCanonicalId: "comet-network",
+        expectedToolName: "comet_network",
+        note: "Network request monitoring",
+    },
+    {
+        query: "run automation workflow multi step",
+        expectedCanonicalId: "comet-automate",
+        expectedToolName: "comet_automate",
+        note: "Multi-step automation playbook",
+    },
+    // ── Lifecycle tools ───────────────────────────────────────────────────────
+    {
+        query: "start task thread lifecycle register run",
+        expectedCanonicalId: "comet-lifecycle-start",
+        expectedToolName: "comet_lifecycle_start",
+        note: "Lifecycle start — agent registers a new task run",
+    },
+    {
+        query: "mark task complete finish run",
+        expectedCanonicalId: "comet-lifecycle-complete",
+        expectedToolName: "comet_lifecycle_complete",
+        note: "Terminal lifecycle action for success",
+    },
+    // ── CAUTION tools ─────────────────────────────────────────────────────────
+    {
+        query: "delegate task spawn sub-agent equabot",
+        expectedCanonicalId: "comet-delegate",
+        expectedToolName: "comet_delegate",
+        note: "CAUTION: spawns a new agent — must appear with the CAUTION warning",
+    },
+];
+//# sourceMappingURL=golden-queries.fixture.js.map

package/dist/discovery/mcp-source.d.ts

@@ -0,0 +1,38 @@
+/**
+ * mcp-source.ts
+ * MCP source reader for the Comet Discovery Layer (Spec 042, T020).
+ *
+ * Reads the native tool metadata catalog (tool-meta.ts) and the TOOLS
+ * array from the running MCP server (imported via tool-registry.ts to
+ * avoid circular imports), then produces CapabilityEntry[] with
+ * sourceLayer: "mcp" for every registered native tool.
+ *
+ * Tools in the TOOLS array that have no matching entry in TOOL_META_MAP
+ * are skipped with a SourceError (warn-and-continue, FR-008a).
+ */
+import type { CapabilityEntry, SourceError } from "./capability-entry.js";
+/**
+ * Minimal shape of a native MCP tool definition.
+ * Matches the Tool type in index.ts without importing it (avoids circular dep).
+ */
+interface NativeTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * Read the native MCP tool source and return CapabilityEntry[].
+ *
+ * Accepts the TOOLS array as an argument so tests can inject fixtures
+ * without touching index.ts (FR-009).
+ *
+ * @param tools  The TOOLS array from index.ts (or a fixture subset for tests).
+ * @returns      { entries, errors } — entries for every tool in TOOL_META_MAP;
+ *               errors for tools missing from the catalog.
+ */
+export declare function readMcpSource(tools: NativeTool[]): {
+    entries: CapabilityEntry[];
+    errors: SourceError[];
+};
+export {};
+//# sourceMappingURL=mcp-source.d.ts.map

package/dist/discovery/mcp-source.js

@@ -0,0 +1,70 @@
+/**
+ * mcp-source.ts
+ * MCP source reader for the Comet Discovery Layer (Spec 042, T020).
+ *
+ * Reads the native tool metadata catalog (tool-meta.ts) and the TOOLS
+ * array from the running MCP server (imported via tool-registry.ts to
+ * avoid circular imports), then produces CapabilityEntry[] with
+ * sourceLayer: "mcp" for every registered native tool.
+ *
+ * Tools in the TOOLS array that have no matching entry in TOOL_META_MAP
+ * are skipped with a SourceError (warn-and-continue, FR-008a).
+ */
+import { errorFromException } from "./source-error.js";
+import { assertSafety } from "./safety.js";
+import { TOOL_META_MAP } from "./tool-meta.js";
+// ---------------------------------------------------------------------------
+// Source reader
+// ---------------------------------------------------------------------------
+/**
+ * Read the native MCP tool source and return CapabilityEntry[].
+ *
+ * Accepts the TOOLS array as an argument so tests can inject fixtures
+ * without touching index.ts (FR-009).
+ *
+ * @param tools  The TOOLS array from index.ts (or a fixture subset for tests).
+ * @returns      { entries, errors } — entries for every tool in TOOL_META_MAP;
+ *               errors for tools missing from the catalog.
+ */
+export function readMcpSource(tools) {
+    const entries = [];
+    const errors = [];
+    for (const tool of tools) {
+        const meta = TOOL_META_MAP.get(tool.name);
+        if (!meta) {
+            errors.push({
+                source: "mcp",
+                reason: `Tool "${tool.name}" has no entry in TOOL_META_MAP — add one to tool-meta.ts`,
+            });
+            continue;
+        }
+        // Validate safety class (should always pass for hand-authored catalog)
+        let safety;
+        try {
+            safety = assertSafety(meta.safety, tool.name);
+        }
+        catch (err) {
+            errors.push(errorFromException("mcp", err));
+            continue;
+        }
+        const entry = {
+            name: tool.name,
+            sourceLayer: "mcp",
+            sourcePath: `comet-mcp/src/index.ts#tool_${tool.name}`,
+            canonicalId: meta.canonicalId,
+            description: meta.description,
+            intentKeywords: meta.intentKeywords,
+            safety,
+            preconditions: meta.preconditions,
+            argsSchema: tool.inputSchema,
+            humanOnly: false,
+            invocation: { kind: "native", toolName: tool.name },
+            crossRef: null, // singletons until dedup.ts runs (T043)
+            recommended: true, // all native entries are recommended until dedup.ts runs
+            alternativeLabel: null,
+        };
+        entries.push(entry);
+    }
+    return { entries, errors };
+}
+//# sourceMappingURL=mcp-source.js.map

package/dist/discovery/metadata-completeness.d.ts

@@ -0,0 +1,48 @@
+/**
+ * metadata-completeness.ts
+ * Metadata completeness validator for the Comet Discovery Layer (Spec 042, T032).
+ *
+ * Walks a CapabilityEntry[] and returns a MetadataCompletenessReport with:
+ *   - completeness ratio (1.0 = SC-003 satisfied)
+ *   - per-entry gap list for drift-check and test assertion
+ *
+ * Used by:
+ *   - metadata-completeness.test.ts (T028)
+ *   - coverage.ts (US4, T054) for DriftReport.safetyGaps
+ */
+import type { CapabilityEntry } from "./capability-entry.js";
+export interface MetadataGap {
+    /** Entry name (tool name / plugin slug / extension slug). */
+    name: string;
+    /** Which field is incomplete. */
+    field: "safety" | "sourceLayer" | "preconditions" | "description" | "canonicalId" | "intentKeywords";
+    /** Human-readable reason. */
+    reason: string;
+}
+export interface MetadataCompletenessReport {
+    /**
+     * Ratio of entries with zero gaps to total entries.
+     * 0.0 (all entries gapped) to 1.0 (all entries complete).
+     * 1.0 = SC-003 satisfied.
+     */
+    completeness: number;
+    /** All gaps found across all entries. */
+    gaps: MetadataGap[];
+    /** How many entries were checked. */
+    totalChecked: number;
+    /** How many entries had zero gaps. */
+    totalComplete: number;
+}
+/**
+ * Validate metadata completeness for a list of CapabilityEntry objects.
+ * Returns the completeness ratio and all gaps found.
+ *
+ * @param entries  The composed registry entries to validate.
+ */
+export declare function checkMetadataCompleteness(entries: CapabilityEntry[]): MetadataCompletenessReport;
+/**
+ * Returns the names of entries missing their safety classification.
+ * Used by coverage.ts to populate DriftReport.safetyGaps.
+ */
+export declare function getSafetyGaps(entries: CapabilityEntry[]): string[];
+//# sourceMappingURL=metadata-completeness.d.ts.map

package/dist/discovery/metadata-completeness.js

@@ -0,0 +1,83 @@
+/**
+ * metadata-completeness.ts
+ * Metadata completeness validator for the Comet Discovery Layer (Spec 042, T032).
+ *
+ * Walks a CapabilityEntry[] and returns a MetadataCompletenessReport with:
+ *   - completeness ratio (1.0 = SC-003 satisfied)
+ *   - per-entry gap list for drift-check and test assertion
+ *
+ * Used by:
+ *   - metadata-completeness.test.ts (T028)
+ *   - coverage.ts (US4, T054) for DriftReport.safetyGaps
+ */
+// ---------------------------------------------------------------------------
+// Validator
+// ---------------------------------------------------------------------------
+/**
+ * Validate metadata completeness for a list of CapabilityEntry objects.
+ * Returns the completeness ratio and all gaps found.
+ *
+ * @param entries  The composed registry entries to validate.
+ */
+export function checkMetadataCompleteness(entries) {
+    const gaps = [];
+    let totalComplete = 0;
+    for (const entry of entries) {
+        const entryGaps = [];
+        // safety — must be a non-empty SAFE|SESSION|CAUTION value
+        if (!entry.safety) {
+            entryGaps.push({ name: entry.name, field: "safety", reason: "missing or empty" });
+        }
+        // sourceLayer — must be non-empty
+        if (!entry.sourceLayer) {
+            entryGaps.push({ name: entry.name, field: "sourceLayer", reason: "missing or empty" });
+        }
+        // preconditions — must be an array (may be empty)
+        if (!Array.isArray(entry.preconditions)) {
+            entryGaps.push({
+                name: entry.name,
+                field: "preconditions",
+                reason: `not an array (got ${typeof entry.preconditions})`,
+            });
+        }
+        // description — must be non-empty and at least 24 chars
+        if (!entry.description || entry.description.length < 24) {
+            entryGaps.push({
+                name: entry.name,
+                field: "description",
+                reason: `too short (${entry.description?.length ?? 0} chars, min 24)`,
+            });
+        }
+        // canonicalId — must be non-empty
+        if (!entry.canonicalId) {
+            entryGaps.push({ name: entry.name, field: "canonicalId", reason: "missing or empty" });
+        }
+        // intentKeywords — must be an array with ≥ 3 items
+        if (!Array.isArray(entry.intentKeywords) || entry.intentKeywords.length < 3) {
+            entryGaps.push({
+                name: entry.name,
+                field: "intentKeywords",
+                reason: `fewer than 3 keywords (got ${entry.intentKeywords?.length ?? 0})`,
+            });
+        }
+        gaps.push(...entryGaps);
+        if (entryGaps.length === 0)
+            totalComplete++;
+    }
+    const totalChecked = entries.length;
+    const completeness = totalChecked === 0 ? 1.0 : totalComplete / totalChecked;
+    return { completeness, gaps, totalChecked, totalComplete };
+}
+// ---------------------------------------------------------------------------
+// Convenience: extract safetyGaps for DriftReport (T054)
+// ---------------------------------------------------------------------------
+/**
+ * Returns the names of entries missing their safety classification.
+ * Used by coverage.ts to populate DriftReport.safetyGaps.
+ */
+export function getSafetyGaps(entries) {
+    return entries
+        .filter((e) => !e.safety)
+        .map((e) => e.name);
+}
+//# sourceMappingURL=metadata-completeness.js.map

package/dist/discovery/registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * registry.ts
+ * Registry composer for the Comet Discovery Layer (Spec 042, T010/T021/T044).
+ *
+ * T010: Stub — returned empty arrays (proved the integration point compiled).
+ * T021: Wire MCP source reader — reads native tools and returns CapabilityEntry[].
+ * T044: Will add plugin + extension sources and dedup (US3, future).
+ */
+import type { CapabilityEntry, SourceError } from "./capability-entry.js";
+export interface RegistryResult {
+    entries: CapabilityEntry[];
+    errors: SourceError[];
+}
+/**
+ * Minimal shape of a native MCP tool definition.
+ * Passed in by index.ts to avoid a circular import (index.ts → registry.ts
+ * is the existing direction; registry.ts must NOT import index.ts).
+ */
+export interface NativeToolSpec {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * Compose the full capability registry from all available canonical sources.
+ *
+ * @param nativeTools  The TOOLS array from index.ts (injected to avoid circular
+ *                     imports). If omitted, mcp source returns empty (tests only).
+ *
+ * Sources wired:
+ *   T021 — MCP native tools via mcp-source.ts (US1)
+ *   T044 — plugin + extension sources + dedup (US3, not yet wired)
+ */
+export declare function composeRegistry(nativeTools?: NativeToolSpec[]): Promise<RegistryResult>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/discovery/registry.js

@@ -0,0 +1,35 @@
+/**
+ * registry.ts
+ * Registry composer for the Comet Discovery Layer (Spec 042, T010/T021/T044).
+ *
+ * T010: Stub — returned empty arrays (proved the integration point compiled).
+ * T021: Wire MCP source reader — reads native tools and returns CapabilityEntry[].
+ * T044: Will add plugin + extension sources and dedup (US3, future).
+ */
+import { readMcpSource } from "./mcp-source.js";
+import { emitSourceWarnings } from "./source-error.js";
+/**
+ * Compose the full capability registry from all available canonical sources.
+ *
+ * @param nativeTools  The TOOLS array from index.ts (injected to avoid circular
+ *                     imports). If omitted, mcp source returns empty (tests only).
+ *
+ * Sources wired:
+ *   T021 — MCP native tools via mcp-source.ts (US1)
+ *   T044 — plugin + extension sources + dedup (US3, not yet wired)
+ */
+export async function composeRegistry(nativeTools = []) {
+    const allEntries = [];
+    const allErrors = [];
+    // ── T021: MCP native source ──────────────────────────────────────────────
+    const { entries: mcpEntries, errors: mcpErrors } = readMcpSource(nativeTools);
+    allEntries.push(...mcpEntries);
+    allErrors.push(...mcpErrors);
+    // Emit any source-level warnings to stderr (FR-008a / R7)
+    emitSourceWarnings(allErrors);
+    // TODO T044: call plugin-source.ts + extension-source.ts + dedup.ts here.
+    // Deterministic ordering by canonicalId (consistent across restarts)
+    allEntries.sort((a, b) => a.canonicalId.localeCompare(b.canonicalId));
+    return { entries: allEntries, errors: allErrors };
+}
+//# sourceMappingURL=registry.js.map

package/dist/discovery/safety.d.ts

@@ -0,0 +1,44 @@
+/**
+ * safety.ts
+ * Safety taxonomy loader for the Comet Discovery Layer (Spec 042, T007).
+ *
+ * Reads the three valid safety classes (SAFE | SESSION | CAUTION) from
+ * docs/TOOL-SAFETY-REFERENCE.md as the canonical authority. Exports a
+ * validator that rejects any value outside the taxonomy at runtime.
+ *
+ * This module deliberately does NOT import the taxonomy from TOOL-SAFETY-REFERENCE.md
+ * at file-read time (the doc is prose, not machine-readable JSON). Instead we
+ * hard-code the three classes here and note the canonical source in JSDoc so
+ * T061 can add a pointer from the doc back to this file.
+ */
+import type { SafetyClass } from "./capability-entry.js";
+/**
+ * The three valid safety classes.
+ * Canonical authority: docs/TOOL-SAFETY-REFERENCE.md
+ *
+ * SAFE     — Read-only, zero side effects, no active session required.
+ *            Examples: comet_observe, comet_peek, comet_tab_groups(action=list).
+ * SESSION  — Requires an active Comet CDP session (comet_connect first).
+ *            Scoped to the calling agent's own tab group.
+ *            Examples: comet_screenshot, comet_read_page, comet_navigate.
+ * CAUTION  — Cross-session side effects possible; can modify shared browser state.
+ *            Must carry an explicit multi-agent rule reminder in its description.
+ *            Examples: comet_stop, comet_automate (when interacting across groups).
+ */
+export declare const VALID_SAFETY_CLASSES: ReadonlySet<SafetyClass>;
+/**
+ * Assert that `value` is a valid SafetyClass.
+ * Throws a descriptive TypeError if not.
+ * Used by source readers to reject entries missing or misconfigured safety.
+ *
+ * @param value - The candidate safety string from a source definition.
+ * @param context - Optional label (tool name, file path) for error messages.
+ * @returns The validated SafetyClass.
+ */
+export declare function assertSafety(value: string, context?: string): SafetyClass;
+/**
+ * Safe version of assertSafety — returns null instead of throwing.
+ * Useful when the caller wants to route errors through SourceError rather than throw.
+ */
+export declare function parseSafety(value: unknown): SafetyClass | null;
+//# sourceMappingURL=safety.d.ts.map