@bunny-agent/manager 0.9.63-beta.2 → 0.10.0-beta.1

package/dist/contracts/projection.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure helpers converting between Bunny's canonical Unicode code-point
+ * offsets and JavaScript's native UTF-16 string indices, plus the
+ * Responses-shaped output-text projection.
+ *
+ * Bunny v1 annotation ranges are zero-based Unicode code-point offsets with
+ * an exclusive end, measured over the exact emitted Markdown text of one
+ * text part — before any Markdown rendering, Unicode normalization, or
+ * line-ending conversion. See design.md §7 for the canonical `A😀B [1]`
+ * example: the literal `[1]` is code-point range `[4,7)` and UTF-16 range
+ * `[5,8)`, because the leading `😀` is one code point but two UTF-16 units.
+ */
+import type { OutputTextContent, UrlCitationAnnotation } from "./types.js";
+/** Number of Unicode code points in `text` (NOT `text.length`, which counts UTF-16 units). */
+export declare function codePointLength(text: string): number;
+/**
+ * Convert a zero-based Unicode code-point offset into the corresponding
+ * UTF-16 index of `text`. `codePointOffset` may equal `codePointLength(text)`
+ * to address the end of the string.
+ *
+ * Throws if `codePointOffset` is negative or beyond the string's length.
+ */
+export declare function codePointOffsetToUtf16Index(text: string, codePointOffset: number): number;
+/**
+ * Convert a UTF-16 index of `text` into the corresponding zero-based Unicode
+ * code-point offset. `utf16Index` may equal `text.length` to address the end
+ * of the string. Throws if `utf16Index` splits a surrogate pair, is
+ * negative, or exceeds `text.length`.
+ */
+export declare function utf16IndexToCodePointOffset(text: string, utf16Index: number): number;
+/**
+ * Convert a native UTF-16 `[start, end)` range of `text` into a Bunny
+ * canonical Unicode code-point `[start, end)` range, preserving the exact
+ * covered substring. Throws if either boundary splits a surrogate pair or
+ * is out of range.
+ */
+export declare function utf16RangeToCodePointRange(text: string, utf16Start: number, utf16End: number): {
+    start_index: number;
+    end_index: number;
+};
+/** Validate that a code-point annotation range is well-formed for `text`. */
+export declare function isValidCodePointRange(text: string, startIndex: number, endIndex: number): boolean;
+/**
+ * Slice `text` by a validated Unicode code-point `[startIndex, endIndex)`
+ * range. Callers should validate with {@link isValidCodePointRange} first;
+ * this throws on an invalid range rather than silently clamping.
+ */
+export declare function sliceByCodePointRange(text: string, startIndex: number, endIndex: number): string;
+/**
+ * Project a finalized text part and its validated annotations into the
+ * flat Responses `output_text` shape. Annotation order is preserved because
+ * citation bindings address the sibling annotations array by index. Callers
+ * must validate ranges against the exact finalized text before projection.
+ */
+export declare function projectOutputText(text: string, annotations: UrlCitationAnnotation[]): OutputTextContent;
+//# sourceMappingURL=projection.d.ts.map

package/dist/contracts/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/contracts/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE3E,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GACtB,MAAM,CAiBR;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,MAAM,CA2BR;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAU5C;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAUT;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CASR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,qBAAqB,EAAE,GACnC,iBAAiB,CAYnB"}

package/dist/contracts/projection.js

@@ -0,0 +1,129 @@
+/**
+ * Pure helpers converting between Bunny's canonical Unicode code-point
+ * offsets and JavaScript's native UTF-16 string indices, plus the
+ * Responses-shaped output-text projection.
+ *
+ * Bunny v1 annotation ranges are zero-based Unicode code-point offsets with
+ * an exclusive end, measured over the exact emitted Markdown text of one
+ * text part — before any Markdown rendering, Unicode normalization, or
+ * line-ending conversion. See design.md §7 for the canonical `A😀B [1]`
+ * example: the literal `[1]` is code-point range `[4,7)` and UTF-16 range
+ * `[5,8)`, because the leading `😀` is one code point but two UTF-16 units.
+ */
+/** Number of Unicode code points in `text` (NOT `text.length`, which counts UTF-16 units). */
+export function codePointLength(text) {
+    let count = 0;
+    // `for...of` over a string iterates by code point, not UTF-16 code unit.
+    for (const _ of text)
+        count++;
+    return count;
+}
+/**
+ * Convert a zero-based Unicode code-point offset into the corresponding
+ * UTF-16 index of `text`. `codePointOffset` may equal `codePointLength(text)`
+ * to address the end of the string.
+ *
+ * Throws if `codePointOffset` is negative or beyond the string's length.
+ */
+export function codePointOffsetToUtf16Index(text, codePointOffset) {
+    if (!Number.isInteger(codePointOffset) || codePointOffset < 0) {
+        throw new RangeError(`codePointOffset must be a non-negative integer, got ${codePointOffset}`);
+    }
+    let remaining = codePointOffset;
+    let utf16Index = 0;
+    for (const ch of text) {
+        if (remaining === 0)
+            return utf16Index;
+        remaining--;
+        utf16Index += ch.length; // 1 for BMP code points, 2 for astral (surrogate pair)
+    }
+    if (remaining === 0)
+        return utf16Index;
+    throw new RangeError(`codePointOffset ${codePointOffset} exceeds code-point length of text`);
+}
+/**
+ * Convert a UTF-16 index of `text` into the corresponding zero-based Unicode
+ * code-point offset. `utf16Index` may equal `text.length` to address the end
+ * of the string. Throws if `utf16Index` splits a surrogate pair, is
+ * negative, or exceeds `text.length`.
+ */
+export function utf16IndexToCodePointOffset(text, utf16Index) {
+    if (!Number.isInteger(utf16Index) || utf16Index < 0) {
+        throw new RangeError(`utf16Index must be a non-negative integer, got ${utf16Index}`);
+    }
+    if (utf16Index > text.length) {
+        throw new RangeError(`utf16Index ${utf16Index} exceeds UTF-16 length of text`);
+    }
+    let codePointOffset = 0;
+    let utf16Cursor = 0;
+    for (const ch of text) {
+        if (utf16Cursor === utf16Index)
+            return codePointOffset;
+        if (utf16Cursor + ch.length > utf16Index) {
+            throw new RangeError(`utf16Index ${utf16Index} splits a surrogate pair at code-point offset ${codePointOffset}`);
+        }
+        utf16Cursor += ch.length;
+        codePointOffset++;
+    }
+    if (utf16Cursor === utf16Index)
+        return codePointOffset;
+    throw new RangeError(`utf16Index ${utf16Index} exceeds UTF-16 length of text`);
+}
+/**
+ * Convert a native UTF-16 `[start, end)` range of `text` into a Bunny
+ * canonical Unicode code-point `[start, end)` range, preserving the exact
+ * covered substring. Throws if either boundary splits a surrogate pair or
+ * is out of range.
+ */
+export function utf16RangeToCodePointRange(text, utf16Start, utf16End) {
+    if (utf16End < utf16Start) {
+        throw new RangeError(`utf16End ${utf16End} must be >= utf16Start ${utf16Start}`);
+    }
+    return {
+        start_index: utf16IndexToCodePointOffset(text, utf16Start),
+        end_index: utf16IndexToCodePointOffset(text, utf16End),
+    };
+}
+/** Validate that a code-point annotation range is well-formed for `text`. */
+export function isValidCodePointRange(text, startIndex, endIndex) {
+    if (!Number.isInteger(startIndex) ||
+        !Number.isInteger(endIndex) ||
+        startIndex < 0 ||
+        endIndex <= startIndex) {
+        return false;
+    }
+    return endIndex <= codePointLength(text);
+}
+/**
+ * Slice `text` by a validated Unicode code-point `[startIndex, endIndex)`
+ * range. Callers should validate with {@link isValidCodePointRange} first;
+ * this throws on an invalid range rather than silently clamping.
+ */
+export function sliceByCodePointRange(text, startIndex, endIndex) {
+    if (!isValidCodePointRange(text, startIndex, endIndex)) {
+        throw new RangeError(`invalid code-point range [${startIndex}, ${endIndex}) for text of length ${codePointLength(text)}`);
+    }
+    const utf16Start = codePointOffsetToUtf16Index(text, startIndex);
+    const utf16End = codePointOffsetToUtf16Index(text, endIndex);
+    return text.slice(utf16Start, utf16End);
+}
+/**
+ * Project a finalized text part and its validated annotations into the
+ * flat Responses `output_text` shape. Annotation order is preserved because
+ * citation bindings address the sibling annotations array by index. Callers
+ * must validate ranges against the exact finalized text before projection.
+ */
+export function projectOutputText(text, annotations) {
+    return {
+        type: "output_text",
+        text,
+        annotations: annotations.map((annotation) => ({
+            type: "url_citation",
+            start_index: annotation.start_index,
+            end_index: annotation.end_index,
+            url: annotation.url,
+            title: annotation.title,
+        })),
+    };
+}
+//# sourceMappingURL=projection.js.map

package/dist/contracts/projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","sourceRoot":"","sources":["../../src/contracts/projection.ts"],"names":[],"mappings":"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"}

package/dist/contracts/record.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Server-only helpers for building a v1 {@link WebSearchCallRecord} from raw
+ * provider search results.
+ *
+ * This module uses `node:crypto` (via `source-id.ts`) and MUST NOT be
+ * imported from `contracts/index.ts` (the browser-safe barrel re-exported
+ * through `@bunny-agent/sdk/contracts`). Import it directly from
+ * `@bunny-agent/manager/contracts/record` in Node-only runner/harness code
+ * that actually executes a search.
+ */
+import type { WebSearchCallRecord, WebSearchError, WebSearchErrorCode } from "./types.js";
+/** A single raw provider result, as already normalized by each tool's own provider adapter. */
+export interface RawWebSearchResult {
+    title: string;
+    link: string;
+    snippet: string;
+    age?: string;
+    content?: string;
+}
+/**
+ * Project raw provider results into a validated v1 {@link WebSearchCallRecord}.
+ *
+ * Unsafe URLs are omitted and reported through `truncated`. If every returned
+ * URL is unusable, detail is unavailable; that is distinct from a confirmed
+ * zero-hit response. Result rows and distinct sources are both bounded.
+ */
+export declare function buildWebSearchCallRecord(params: {
+    id: string;
+    query: string;
+    provider: string;
+    results: RawWebSearchResult[];
+}): WebSearchCallRecord;
+/**
+ * Build a `completed` v1 record for a provider that only exposes the search
+ * query, with no recoverable result list or citation metadata (e.g. Codex's
+ * `web_search` completion). `source_details: "unavailable"` is truthful
+ * here: the search genuinely completed, but no sources/results can ever be
+ * reconstructed from this provider's event shape — this is distinct from,
+ * and must not be confused with, a confirmed zero-hit search.
+ */
+export declare function buildWebSearchUnavailableDetailRecord(params: {
+    id: string;
+    query: string;
+    provider: string;
+}): WebSearchCallRecord;
+/** Build a sanitized `failed` v1 record. Never include raw auth headers, keys, or unsanitized request dumps in `message`. */
+export declare function buildWebSearchFailureRecord(params: {
+    id: string;
+    query: string;
+    provider: string;
+    error: WebSearchError;
+}): WebSearchCallRecord;
+/** Classify a thrown search error into a safe, provider-neutral {@link WebSearchErrorCode}. */
+export declare function classifyWebSearchError(err: unknown): WebSearchError;
+export type { WebSearchErrorCode };
+//# sourceMappingURL=record.d.ts.map

package/dist/contracts/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/contracts/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAGnB,MAAM,YAAY,CAAC;AAIpB,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B,GAAG,mBAAmB,CA+DtB;AAED;;;;;;;GAOG;AACH,wBAAgB,qCAAqC,CAAC,MAAM,EAAE;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,mBAAmB,CAgBtB;AAED,6HAA6H;AAC7H,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,cAAc,CAAC;CACvB,GAAG,mBAAmB,CAiBtB;AAED,+FAA+F;AAC/F,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAqCnE;AA0CD,YAAY,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/contracts/record.js

@@ -0,0 +1,205 @@
+/**
+ * Server-only helpers for building a v1 {@link WebSearchCallRecord} from raw
+ * provider search results.
+ *
+ * This module uses `node:crypto` (via `source-id.ts`) and MUST NOT be
+ * imported from `contracts/index.ts` (the browser-safe barrel re-exported
+ * through `@bunny-agent/sdk/contracts`). Import it directly from
+ * `@bunny-agent/manager/contracts/record` in Node-only runner/harness code
+ * that actually executes a search.
+ */
+import { deriveSourceId } from "./source-id.js";
+import { SEARCH_CONTRACT_LIMITS } from "./types.js";
+import { isSafeHttpUrl } from "./validators.js";
+/**
+ * Project raw provider results into a validated v1 {@link WebSearchCallRecord}.
+ *
+ * Unsafe URLs are omitted and reported through `truncated`. If every returned
+ * URL is unusable, detail is unavailable; that is distinct from a confirmed
+ * zero-hit response. Result rows and distinct sources are both bounded.
+ */
+export function buildWebSearchCallRecord(params) {
+    const sources = [];
+    const resultItems = [];
+    const seenSourceIds = new Set();
+    let truncated = false;
+    for (let i = 0; i < params.results.length; i++) {
+        if (resultItems.length >= SEARCH_CONTRACT_LIMITS.maxSourcesPerSearch) {
+            truncated = true;
+            break;
+        }
+        const raw = params.results[i];
+        if (!raw || !isSafeHttpUrl(raw.link)) {
+            truncated = true;
+            continue;
+        }
+        const sourceId = deriveSourceId(raw.link);
+        if (sourceId === undefined) {
+            truncated = true;
+            continue;
+        }
+        const title = typeof raw.title === "string" ? raw.title : undefined;
+        if (!seenSourceIds.has(sourceId)) {
+            seenSourceIds.add(sourceId);
+            sources.push({
+                type: "url",
+                source_id: sourceId,
+                url: raw.link,
+                ...(title ? { title } : {}),
+            });
+        }
+        resultItems.push({
+            source_id: sourceId,
+            url: raw.link,
+            ...(title ? { title } : {}),
+            ...(typeof raw.snippet === "string" && raw.snippet
+                ? { snippet: raw.snippet }
+                : {}),
+            ...(typeof raw.age === "string" && raw.age ? { age: raw.age } : {}),
+            ...(typeof raw.content === "string" && raw.content
+                ? { content: raw.content }
+                : {}),
+        });
+    }
+    return {
+        schema_version: 1,
+        type: "web_search_call",
+        id: params.id,
+        status: "completed",
+        action: {
+            type: "search",
+            query: params.query,
+            sources,
+        },
+        source_details: params.results.length > 0 && resultItems.length === 0
+            ? "unavailable"
+            : "available",
+        results: resultItems,
+        provider: params.provider,
+        truncated,
+    };
+}
+/**
+ * Build a `completed` v1 record for a provider that only exposes the search
+ * query, with no recoverable result list or citation metadata (e.g. Codex's
+ * `web_search` completion). `source_details: "unavailable"` is truthful
+ * here: the search genuinely completed, but no sources/results can ever be
+ * reconstructed from this provider's event shape — this is distinct from,
+ * and must not be confused with, a confirmed zero-hit search.
+ */
+export function buildWebSearchUnavailableDetailRecord(params) {
+    return {
+        schema_version: 1,
+        type: "web_search_call",
+        id: params.id,
+        status: "completed",
+        action: {
+            type: "search",
+            query: params.query,
+            sources: [],
+        },
+        source_details: "unavailable",
+        results: [],
+        provider: params.provider,
+        truncated: false,
+    };
+}
+/** Build a sanitized `failed` v1 record. Never include raw auth headers, keys, or unsanitized request dumps in `message`. */
+export function buildWebSearchFailureRecord(params) {
+    return {
+        schema_version: 1,
+        type: "web_search_call",
+        id: params.id,
+        status: "failed",
+        action: {
+            type: "search",
+            query: params.query,
+            sources: [],
+        },
+        source_details: "unavailable",
+        results: [],
+        provider: params.provider,
+        truncated: false,
+        error: params.error,
+    };
+}
+/** Classify a thrown search error into a safe, provider-neutral {@link WebSearchErrorCode}. */
+export function classifyWebSearchError(err) {
+    // Provider response bodies can echo credentials or request dumps. Never
+    // project err.message (or String(err)) into public tool results/metadata.
+    const httpStatus = extractHttpStatus(err);
+    if (httpStatus === 401 || httpStatus === 403) {
+        return {
+            code: "authentication",
+            message: "Web search authentication failed.",
+            retryable: false,
+        };
+    }
+    if (httpStatus === 429) {
+        return {
+            code: "rate_limit",
+            message: "Web search rate limit exceeded.",
+            retryable: true,
+        };
+    }
+    if (httpStatus !== undefined && httpStatus >= 400 && httpStatus < 500) {
+        return {
+            code: "invalid_request",
+            message: "Web search request was rejected.",
+            retryable: false,
+        };
+    }
+    if (isNetworkError(err)) {
+        return {
+            code: "network",
+            message: "Web search network request failed.",
+            retryable: true,
+        };
+    }
+    return {
+        code: "provider_error",
+        message: "Web search provider failed.",
+        retryable: httpStatus !== undefined && httpStatus >= 500,
+    };
+}
+function extractHttpStatus(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const match = err.message.match(/\b(\d{3})\b/);
+    if (!match)
+        return undefined;
+    const status = Number.parseInt(match[1], 10);
+    return status >= 100 && status < 600 ? status : undefined;
+}
+const RETRYABLE_NETWORK_ERROR_CODES = new Set([
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENOTFOUND",
+    "ETIMEDOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+function isNetworkError(err, seen = new Set()) {
+    if (err instanceof TypeError && err.message === "fetch failed")
+        return true;
+    if (err === null || typeof err !== "object" || seen.has(err))
+        return false;
+    seen.add(err);
+    const code = err.code;
+    if (typeof code === "string" && RETRYABLE_NETWORK_ERROR_CODES.has(code)) {
+        return true;
+    }
+    const nested = [];
+    if ("cause" in err)
+        nested.push(err.cause);
+    if ("errors" in err && Array.isArray(err.errors)) {
+        nested.push(...err.errors);
+    }
+    return nested.some((n) => isNetworkError(n, seen));
+}
+//# sourceMappingURL=record.js.map

package/dist/contracts/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/contracts/record.ts"],"names":[],"mappings":"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"}

package/dist/contracts/source-id.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Server-only stable URL source identity generation.
+ *
+ * This module uses `node:crypto` and MUST NOT be imported from
+ * `contracts/index.ts` (the browser-safe barrel re-exported through
+ * `@bunny-agent/sdk/contracts`). Import it directly from
+ * `@bunny-agent/manager/contracts/source-id` in Node-only runner/harness
+ * code that actually registers sources.
+ */
+/**
+ * Validate and normalize a candidate source URL for identity hashing.
+ * Returns `undefined` for unsafe URLs (non-http(s), embedded credentials,
+ * unparsable). Path, query, and fragment are preserved verbatim — this
+ * intentionally does NOT strip tracking parameters, since doing so would
+ * create false equivalence between distinct URLs.
+ */
+export declare function normalizeSourceUrl(url: string): string | undefined;
+/**
+ * Derive a stable, opaque, collision-resistant source ID for a validated
+ * URL. The same normalized URL always yields the same ID within and across
+ * processes (pure function of the URL string, no per-process salt), so
+ * repeated searches and session resume/fork reuse one identity. Returns
+ * `undefined` if `url` is not a safe http(s) URL.
+ */
+export declare function deriveSourceId(url: string): string | undefined;
+//# sourceMappingURL=source-id.d.ts.map

package/dist/contracts/source-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-id.d.ts","sourceRoot":"","sources":["../../src/contracts/source-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMlE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK9D"}

package/dist/contracts/source-id.js

@@ -0,0 +1,42 @@
+/**
+ * Server-only stable URL source identity generation.
+ *
+ * This module uses `node:crypto` and MUST NOT be imported from
+ * `contracts/index.ts` (the browser-safe barrel re-exported through
+ * `@bunny-agent/sdk/contracts`). Import it directly from
+ * `@bunny-agent/manager/contracts/source-id` in Node-only runner/harness
+ * code that actually registers sources.
+ */
+import { createHash } from "node:crypto";
+import { isSafeHttpUrl } from "./validators.js";
+const SOURCE_ID_PREFIX = "src_";
+/**
+ * Validate and normalize a candidate source URL for identity hashing.
+ * Returns `undefined` for unsafe URLs (non-http(s), embedded credentials,
+ * unparsable). Path, query, and fragment are preserved verbatim — this
+ * intentionally does NOT strip tracking parameters, since doing so would
+ * create false equivalence between distinct URLs.
+ */
+export function normalizeSourceUrl(url) {
+    if (!isSafeHttpUrl(url))
+        return undefined;
+    // `new URL(...).toString()` is deterministic for a given safe input
+    // (consistent percent-encoding, lowercased host) without rewriting the
+    // semantic content of path/query/fragment.
+    return new URL(url).toString();
+}
+/**
+ * Derive a stable, opaque, collision-resistant source ID for a validated
+ * URL. The same normalized URL always yields the same ID within and across
+ * processes (pure function of the URL string, no per-process salt), so
+ * repeated searches and session resume/fork reuse one identity. Returns
+ * `undefined` if `url` is not a safe http(s) URL.
+ */
+export function deriveSourceId(url) {
+    const normalized = normalizeSourceUrl(url);
+    if (normalized === undefined)
+        return undefined;
+    const hash = createHash("sha256").update(normalized, "utf8").digest("hex");
+    return `${SOURCE_ID_PREFIX}${hash}`;
+}
+//# sourceMappingURL=source-id.js.map

package/dist/contracts/source-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-id.js","sourceRoot":"","sources":["../../src/contracts/source-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,oEAAoE;IACpE,uEAAuE;IACvE,2CAA2C;IAC3C,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,UAAU,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC/C,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3E,OAAO,GAAG,gBAAgB,GAAG,IAAI,EAAE,CAAC;AACtC,CAAC"}