oh-my-knowledge 0.47.0 → 0.49.0

package/dist/shared/record-count.js

@@ -0,0 +1,43 @@
+export function ownRecordValue(record, key) {
+    return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+export function setOwnRecordValue(record, key, value) {
+    Object.defineProperty(record, key, {
+        value,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
+    return value;
+}
+/**
+ * Increment an arbitrary string-keyed counter without reading inherited
+ * properties such as `constructor` or invoking the legacy `__proto__` setter.
+ */
+export function incrementRecordCount(record, key, amount = 1) {
+    if (!Number.isSafeInteger(amount) || amount < 0) {
+        throw new TypeError(`Record count increment must be a non-negative integer, got ${String(amount)}`);
+    }
+    const ownValue = ownRecordValue(record, key);
+    const current = typeof ownValue === 'number' && Number.isSafeInteger(ownValue) && ownValue >= 0
+        ? ownValue
+        : 0;
+    const next = current + amount;
+    if (!Number.isSafeInteger(next)) {
+        throw new RangeError(`Record count for "${key}" exceeds Number.MAX_SAFE_INTEGER`);
+    }
+    return setOwnRecordValue(record, key, next);
+}
+export function sumRecordCounts(...values) {
+    let total = 0;
+    for (const value of values) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new TypeError(`Record count must be a non-negative safe integer, got ${String(value)}`);
+        }
+        total += value;
+        if (!Number.isSafeInteger(total)) {
+            throw new RangeError('Record count sum exceeds Number.MAX_SAFE_INTEGER');
+        }
+    }
+    return total;
+}

package/dist/shared/sample-contract.d.ts

@@ -0,0 +1,3 @@
+export declare function assertionContractValidationError(value: unknown, depth?: number, insideAssertSet?: boolean): string | undefined;
+export declare function dependencyRequirementsValidationError(value: unknown): string | undefined;
+export declare function sampleContractValidationError(value: unknown, expectedId?: string): string | undefined;

package/dist/shared/sample-contract.js

@@ -0,0 +1,332 @@
+import { isJsonValue } from './json-value.js';
+import { ASYNC_ASSERTION_TYPES, SUPPORTED_ASSERTION_TYPES, } from './assertion-types.js';
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number'
+        && Number.isFinite(value)
+        && Math.abs(value) <= Number.MAX_SAFE_INTEGER;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(isNonEmptyString);
+}
+function hasOnlyKeys(value, allowed) {
+    const allowedKeys = new Set(allowed);
+    return Object.keys(value).every((key) => allowedKeys.has(key));
+}
+const STRING_VALUE_ASSERTIONS = new Set([
+    'contains',
+    'not_contains',
+    'starts_with',
+    'ends_with',
+    'equals',
+    'not_equals',
+    'tool_output_contains',
+    'tool_input_contains',
+    'tool_input_not_contains',
+    'mock_hit',
+]);
+const NUMBER_VALUE_ASSERTIONS = new Set([
+    'min_length',
+    'max_length',
+    'word_count_min',
+    'word_count_max',
+    'cost_max',
+    'latency_max',
+    'turns_max',
+    'turns_min',
+    'tools_count_max',
+    'tools_count_min',
+    'levenshtein_max',
+]);
+const NON_NEGATIVE_VALUE_ASSERTIONS = new Set([
+    ...NUMBER_VALUE_ASSERTIONS,
+]);
+const STRING_VALUES_ASSERTIONS = new Set([
+    'contains_all',
+    'contains_any',
+    'tools_called',
+    'tools_not_called',
+]);
+const REFERENCE_ASSERTIONS = new Set([
+    'semantic_similarity',
+    'rouge_n_min',
+    'levenshtein_max',
+    'bleu_min',
+]);
+export function assertionContractValidationError(value, depth = 0, insideAssertSet = false) {
+    if (depth >= 16)
+        return 'assertion nesting exceeds 16 levels';
+    if (!isRecord(value))
+        return 'assertion must be an object';
+    if (!isNonEmptyString(value.type))
+        return 'assertion "type" must be a non-empty string';
+    if (!SUPPORTED_ASSERTION_TYPES.has(value.type)) {
+        return `unsupported assertion type: ${JSON.stringify(value.type)}`;
+    }
+    if (insideAssertSet && ASYNC_ASSERTION_TYPES.has(value.type)) {
+        return `async assertion type ${JSON.stringify(value.type)} cannot be nested in "assert-set"`;
+    }
+    if (value.value !== undefined
+        && typeof value.value !== 'string'
+        && !isFiniteNumber(value.value))
+        return '"value" must be a finite number or string when present';
+    if (value.values !== undefined && !isStringArray(value.values)) {
+        return '"values" must be an array of non-empty strings when present';
+    }
+    if (value.pattern !== undefined && typeof value.pattern !== 'string') {
+        return '"pattern" must be a string when present';
+    }
+    if (value.flags !== undefined && typeof value.flags !== 'string') {
+        return '"flags" must be a string when present';
+    }
+    if (value.schema !== undefined
+        && (!isRecord(value.schema) || !isJsonValue(value.schema)))
+        return '"schema" must be a JSON object when present';
+    if (value.weight !== undefined && (!isFiniteNumber(value.weight) || value.weight <= 0)) {
+        return '"weight" must be a positive finite number when present';
+    }
+    if (value.fn !== undefined && typeof value.fn !== 'string') {
+        return '"fn" must be a string when present';
+    }
+    if (value.reference !== undefined && typeof value.reference !== 'string') {
+        return '"reference" must be a string when present';
+    }
+    if (value.threshold !== undefined && !isFiniteNumber(value.threshold)) {
+        return '"threshold" must be a finite number when present';
+    }
+    if (value.not !== undefined && typeof value.not !== 'boolean') {
+        return '"not" must be boolean when present';
+    }
+    if (value.mode !== undefined
+        && value.mode !== 'any'
+        && value.mode !== 'all')
+        return '"mode" must be "any" or "all" when present';
+    if (value.n !== undefined
+        && (!Number.isSafeInteger(value.n) || value.n <= 0))
+        return '"n" must be a positive integer when present';
+    if (STRING_VALUE_ASSERTIONS.has(value.type) && !isNonEmptyString(value.value)) {
+        return `${JSON.stringify(value.type)} requires a non-empty string "value"`;
+    }
+    if (NUMBER_VALUE_ASSERTIONS.has(value.type) && !isFiniteNumber(value.value)) {
+        return `${JSON.stringify(value.type)} requires a finite numeric "value"`;
+    }
+    if (NON_NEGATIVE_VALUE_ASSERTIONS.has(value.type)
+        && isFiniteNumber(value.value)
+        && value.value < 0)
+        return `${JSON.stringify(value.type)} requires a non-negative "value"`;
+    if (STRING_VALUES_ASSERTIONS.has(value.type)
+        && (!isStringArray(value.values) || value.values.length === 0))
+        return `${JSON.stringify(value.type)} requires non-empty string "values"`;
+    if (REFERENCE_ASSERTIONS.has(value.type) && !isNonEmptyString(value.reference)) {
+        return `${JSON.stringify(value.type)} requires a non-empty "reference"`;
+    }
+    if (value.type === 'regex') {
+        if (typeof value.pattern !== 'string')
+            return '"regex" requires a string "pattern"';
+        try {
+            new RegExp(value.pattern, typeof value.flags === 'string' ? value.flags : 'i');
+        }
+        catch {
+            return '"regex" contains an invalid pattern or flags';
+        }
+    }
+    if (value.type === 'json_schema' && (!isRecord(value.schema) || !isJsonValue(value.schema))) {
+        return '"json_schema" requires a JSON object "schema"';
+    }
+    if (value.type === 'custom' && !isNonEmptyString(value.fn)) {
+        return '"custom" requires a non-empty "fn"';
+    }
+    if ((value.type === 'rouge_n_min' || value.type === 'bleu_min')
+        && value.threshold !== undefined
+        && (value.threshold < 0 || value.threshold > 1))
+        return `${JSON.stringify(value.type)} "threshold" must be within [0, 1]`;
+    if ((value.type === 'semantic_similarity'
+        || value.type === 'faithfulness'
+        || value.type === 'answer_relevancy'
+        || value.type === 'context_recall')
+        && value.threshold !== undefined
+        && (value.threshold < 1 || value.threshold > 5))
+        return `${JSON.stringify(value.type)} "threshold" must be within [1, 5]`;
+    if (value.type === 'mock_hit'
+        && typeof value.value === 'string'
+        && !/^[^:]+:[1-9]\d*$/.test(value.value))
+        return '"mock_hit" value must use "Tool:N" with a positive 1-based ordinal';
+    if (value.type === 'assert-set'
+        && (!Array.isArray(value.children) || value.children.length === 0))
+        return '"assert-set" requires non-empty "children"';
+    if (value.children !== undefined) {
+        if (!Array.isArray(value.children))
+            return '"children" must be an array when present';
+        for (const [index, child] of value.children.entries()) {
+            const error = assertionContractValidationError(child, depth + 1, value.type === 'assert-set');
+            if (error)
+                return `children[${index}]: ${error}`;
+        }
+    }
+    return undefined;
+}
+function isMockReturn(value) {
+    return typeof value === 'string'
+        || (isRecord(value) && isJsonValue(value));
+}
+function mockValidationError(value) {
+    if (!isRecord(value))
+        return 'mock must be an object';
+    if (!isNonEmptyString(value.tool))
+        return '"tool" must be a non-empty string';
+    if (value.return !== undefined && !isMockReturn(value.return)) {
+        return '"return" must be a string or JSON object';
+    }
+    if (value.return_file !== undefined && !isNonEmptyString(value.return_file)) {
+        return '"return_file" must be a non-empty string';
+    }
+    if (value.return_seq !== undefined
+        && (!Array.isArray(value.return_seq)
+            || value.return_seq.length === 0
+            || !value.return_seq.every(isMockReturn)))
+        return '"return_seq" must be a non-empty array of mock returns';
+    if (value.return === undefined
+        && value.return_file === undefined
+        && value.return_seq === undefined)
+        return 'mock requires "return", "return_file", or "return_seq"';
+    if (value.match === undefined)
+        return undefined;
+    if (!isRecord(value.match))
+        return '"match" must be an object when present';
+    const matchFields = [
+        'file_path',
+        'file_path_endswith',
+        'url',
+        'url_glob',
+        'command_glob',
+        'input_contains',
+    ];
+    if (!hasOnlyKeys(value.match, [...matchFields, 'input'])) {
+        return '"match" contains an unsupported field';
+    }
+    for (const field of matchFields) {
+        if (value.match[field] !== undefined && !isNonEmptyString(value.match[field])) {
+            return `"match.${field}" must be a non-empty string when present`;
+        }
+    }
+    if (value.match.input !== undefined
+        && (!isRecord(value.match.input) || !isJsonValue(value.match.input)))
+        return '"match.input" must be a JSON object when present';
+    return undefined;
+}
+export function dependencyRequirementsValidationError(value) {
+    if (!isRecord(value))
+        return '"requires" must be an object';
+    if (!hasOnlyKeys(value, ['tools', 'files', 'env', 'preflight'])) {
+        return '"requires" contains an unsupported field';
+    }
+    for (const field of ['tools', 'files', 'env', 'preflight']) {
+        if (value[field] !== undefined && !isStringArray(value[field])) {
+            return `"requires.${field}" must be an array of non-empty strings`;
+        }
+    }
+    return undefined;
+}
+export function sampleContractValidationError(value, expectedId) {
+    if (!isRecord(value))
+        return 'sample must be an object';
+    if (!isNonEmptyString(value.sample_id)
+        || (expectedId !== undefined && value.sample_id !== expectedId))
+        return '"sample_id" must be a non-empty matching string';
+    if (!isNonEmptyString(value.prompt))
+        return '"prompt" must be a non-empty string';
+    for (const field of ['cwd', 'rubric', 'context']) {
+        if (value[field] !== undefined && typeof value[field] !== 'string') {
+            return `"${field}" must be a string when present`;
+        }
+    }
+    if (value.dimensions !== undefined
+        && (!isRecord(value.dimensions)
+            || !Object.keys(value.dimensions).every(isNonEmptyString)
+            || !Object.values(value.dimensions).every(isNonEmptyString)))
+        return '"dimensions" must map non-empty names to non-empty string rubrics';
+    if (value.assertions !== undefined) {
+        if (!Array.isArray(value.assertions))
+            return '"assertions" must be an array';
+        for (const [index, assertion] of value.assertions.entries()) {
+            const error = assertionContractValidationError(assertion);
+            if (error)
+                return `"assertions[${index}]": ${error}`;
+        }
+        for (const assertion of value.assertions) {
+            if (isRecord(assertion)
+                && (assertion.type === 'faithfulness' || assertion.type === 'context_recall')
+                && !isNonEmptyString(assertion.reference)
+                && !isNonEmptyString(value.context)) {
+                return `${JSON.stringify(assertion.type)} requires sample "context" or assertion "reference"`;
+            }
+        }
+    }
+    if (value.mocks !== undefined) {
+        if (!Array.isArray(value.mocks))
+            return '"mocks" must be an array';
+        for (const [index, mock] of value.mocks.entries()) {
+            const error = mockValidationError(mock);
+            if (error)
+                return `"mocks[${index}]": ${error}`;
+        }
+    }
+    if (value.mocksStrict !== undefined && typeof value.mocksStrict !== 'boolean') {
+        return '"mocksStrict" must be boolean when present';
+    }
+    for (const field of ['allowedTools', 'expectedTools', 'capability']) {
+        if (value[field] !== undefined && !isStringArray(value[field])) {
+            return `"${field}" must be an array of non-empty strings`;
+        }
+    }
+    if (value.environment !== undefined
+        && (!isRecord(value.environment)
+            || !hasOnlyKeys(value.environment, ['cli_available', 'files_available', 'notes'])
+            || (value.environment.cli_available !== undefined
+                && !isStringArray(value.environment.cli_available))
+            || (value.environment.files_available !== undefined
+                && !isStringArray(value.environment.files_available))
+            || (value.environment.notes !== undefined
+                && typeof value.environment.notes !== 'string')))
+        return '"environment" has an invalid shape';
+    if (value.difficulty !== undefined
+        && value.difficulty !== 'easy'
+        && value.difficulty !== 'medium'
+        && value.difficulty !== 'hard')
+        return '"difficulty" has an unsupported value';
+    if (value.construct !== undefined && typeof value.construct !== 'string') {
+        return '"construct" must be string when present';
+    }
+    if (value.provenance !== undefined
+        && value.provenance !== 'human'
+        && value.provenance !== 'llm-generated'
+        && value.provenance !== 'production-trace')
+        return '"provenance" has an unsupported value';
+    if (value.tripwire !== undefined && typeof value.tripwire !== 'boolean') {
+        return '"tripwire" must be boolean when present';
+    }
+    if (value.covers === undefined)
+        return undefined;
+    const targetKinds = new Set([
+        'skill',
+        'skill_file',
+        'frontmatter',
+        'reference',
+        'script',
+        'hard_rule',
+        'workflow',
+        'workflow_node',
+    ]);
+    return Array.isArray(value.covers)
+        && value.covers.every((target) => isRecord(target)
+            && typeof target.targetKind === 'string'
+            && targetKinds.has(target.targetKind)
+            && isNonEmptyString(target.ref))
+        ? undefined
+        : '"covers" contains an invalid coverage target';
+}

package/dist/shared/shell-quote.d.ts

@@ -0,0 +1,2 @@
+/** Format one POSIX shell argument for user-facing copy/paste commands. */
+export declare function shellQuoteArg(value: string): string;

package/dist/shared/shell-quote.js

@@ -0,0 +1,7 @@
+const SAFE_SHELL_ARG_RE = /^[A-Za-z0-9_./:@%+=,-]+$/;
+/** Format one POSIX shell argument for user-facing copy/paste commands. */
+export function shellQuoteArg(value) {
+    if (value && SAFE_SHELL_ARG_RE.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/dist/shared/timestamp.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Normalize an absolute RFC 3339 timestamp without accepting JavaScript's
+ * environment-dependent date shortcuts or calendar rollover.
+ */
+export declare function normalizeRfc3339Timestamp(value: unknown): string | undefined;
+export declare function isRfc3339Timestamp(value: unknown): value is string;

package/dist/shared/timestamp.js

@@ -0,0 +1,64 @@
+const RFC3339_TIMESTAMP_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/i;
+/**
+ * Normalize an absolute RFC 3339 timestamp without accepting JavaScript's
+ * environment-dependent date shortcuts or calendar rollover.
+ */
+export function normalizeRfc3339Timestamp(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const candidate = value.trim();
+    const match = RFC3339_TIMESTAMP_RE.exec(candidate);
+    if (!match)
+        return undefined;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    if (month < 1
+        || month > 12
+        || day < 1
+        || day > daysInMonth(year, month)
+        || hour > 23
+        || minute > 59
+        || second > 60)
+        return undefined;
+    const offset = match[8].toUpperCase();
+    // RFC 3339 reserves -00:00 for an unknown local offset. It is syntactically
+    // valid but does not identify an absolute instant, so measurement code must
+    // not silently reinterpret it as UTC.
+    if (offset === '-00:00')
+        return undefined;
+    if (offset !== 'Z') {
+        const offsetHour = Number(offset.slice(1, 3));
+        const offsetMinute = Number(offset.slice(4, 6));
+        if (offsetHour > 23 || offsetMinute > 59)
+            return undefined;
+    }
+    const parseableCandidate = second === 60
+        ? `${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:59${match[7] ? `.${match[7]}` : ''}${offset}`
+        : candidate;
+    const parsedMs = Date.parse(parseableCandidate);
+    if (second === 60) {
+        const beforeLeap = new Date(parsedMs);
+        if (beforeLeap.getUTCHours() !== 23
+            || beforeLeap.getUTCMinutes() !== 59
+            || beforeLeap.getUTCSeconds() !== 59
+            || beforeLeap.getUTCDate()
+                !== daysInMonth(beforeLeap.getUTCFullYear(), beforeLeap.getUTCMonth() + 1))
+            return undefined;
+    }
+    const epochMs = second === 60 ? parsedMs + 1000 : parsedMs;
+    return Number.isFinite(epochMs) ? new Date(epochMs).toISOString() : undefined;
+}
+export function isRfc3339Timestamp(value) {
+    return normalizeRfc3339Timestamp(value) !== undefined;
+}
+function daysInMonth(year, month) {
+    if (month === 2) {
+        const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+        return leap ? 29 : 28;
+    }
+    return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;
+}

package/dist/shared/token-usage.d.ts

@@ -0,0 +1,19 @@
+export interface ExclusiveInputTokenUsage {
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+}
+/** Provider counters are untrusted protocol input. Token metrics are integer counts. */
+export declare function tokenCount(value: unknown): number;
+export declare function optionalTokenCount(value: unknown): number | undefined;
+/** Sum untrusted provider counters without exposing an unsafe integer. */
+export declare function sumTokenCounts(...values: unknown[]): number;
+/** Validate and sum provider counters while preserving invalid/overflow as unknown. */
+export declare function checkedSumTokenCounts(...values: unknown[]): number | undefined;
+export declare function nonNegativeMetric(value: unknown): number | undefined;
+/**
+ * Split providers whose input total includes cache reads/writes into mutually
+ * exclusive buckets. Invalid cache counters are bounded by the authoritative
+ * input total so one malformed response cannot inflate cross-runtime totals.
+ */
+export declare function splitInclusiveInputTokens(rawInput: unknown, rawCacheRead: unknown, rawCacheCreation?: unknown): ExclusiveInputTokenUsage;

package/dist/shared/token-usage.js

@@ -0,0 +1,50 @@
+/** Provider counters are untrusted protocol input. Token metrics are integer counts. */
+export function tokenCount(value) {
+    return typeof value === 'number'
+        && Number.isSafeInteger(value)
+        && value >= 0
+        ? value
+        : 0;
+}
+export function optionalTokenCount(value) {
+    return typeof value === 'number'
+        && Number.isSafeInteger(value)
+        && value >= 0
+        ? value
+        : undefined;
+}
+/** Sum untrusted provider counters without exposing an unsafe integer. */
+export function sumTokenCounts(...values) {
+    return checkedSumTokenCounts(...values) ?? 0;
+}
+/** Validate and sum provider counters while preserving invalid/overflow as unknown. */
+export function checkedSumTokenCounts(...values) {
+    let total = 0;
+    for (const value of values) {
+        const count = optionalTokenCount(value);
+        if (count === undefined || total > Number.MAX_SAFE_INTEGER - count)
+            return undefined;
+        total += count;
+    }
+    return total;
+}
+export function nonNegativeMetric(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? value
+        : undefined;
+}
+/**
+ * Split providers whose input total includes cache reads/writes into mutually
+ * exclusive buckets. Invalid cache counters are bounded by the authoritative
+ * input total so one malformed response cannot inflate cross-runtime totals.
+ */
+export function splitInclusiveInputTokens(rawInput, rawCacheRead, rawCacheCreation = 0) {
+    const totalInput = tokenCount(rawInput);
+    const cacheReadTokens = Math.min(tokenCount(rawCacheRead), totalInput);
+    const cacheCreationTokens = Math.min(tokenCount(rawCacheCreation), totalInput - cacheReadTokens);
+    return {
+        inputTokens: totalInput - cacheReadTokens - cacheCreationTokens,
+        cacheReadTokens,
+        cacheCreationTokens,
+    };
+}

package/dist/shared/tool-call-status.d.ts

@@ -0,0 +1,8 @@
+import type { ToolCallInfo, ToolCallStatus } from '../types/index.js';
+type ToolCallOutcomeInput = Partial<Pick<ToolCallInfo, 'status' | 'success'>>;
+export declare function toolCallStatus(call: ToolCallOutcomeInput): ToolCallStatus;
+export declare function isToolCallSuccess(call: ToolCallOutcomeInput): boolean;
+export declare function isToolCallFailure(call: ToolCallOutcomeInput): boolean;
+export declare function isToolCallCancelled(call: ToolCallOutcomeInput): boolean;
+export declare function isToolCallUnknown(call: ToolCallOutcomeInput): boolean;
+export {};

package/dist/shared/tool-call-status.js

@@ -0,0 +1,28 @@
+const TOOL_CALL_STATUSES = new Set([
+    'success',
+    'failure',
+    'cancelled',
+    'unknown',
+]);
+export function toolCallStatus(call) {
+    if (call.status !== undefined) {
+        return TOOL_CALL_STATUSES.has(call.status) ? call.status : 'unknown';
+    }
+    if (call.success === true)
+        return 'success';
+    if (call.success === false)
+        return 'failure';
+    return 'unknown';
+}
+export function isToolCallSuccess(call) {
+    return toolCallStatus(call) === 'success';
+}
+export function isToolCallFailure(call) {
+    return toolCallStatus(call) === 'failure';
+}
+export function isToolCallCancelled(call) {
+    return toolCallStatus(call) === 'cancelled';
+}
+export function isToolCallUnknown(call) {
+    return toolCallStatus(call) === 'unknown';
+}

package/dist/shared/tool-identity.d.ts

@@ -0,0 +1,21 @@
+export interface NormalizedToolIdentity {
+    /** Source-neutral name consumed by assertions and aggregate reports. */
+    name: string;
+    /** Runtime-native name, retained when normalization changes it. */
+    sourceName?: string;
+    namespace?: string;
+    provider?: string;
+    displayName?: string;
+}
+export interface ToolIdentityInput {
+    sourceName: string;
+    namespace?: string;
+    provider?: string;
+    /** Runtime-authoritative leaf name, such as an MCP end event's tool. */
+    authoritativeName?: string;
+}
+/**
+ * Normalize runtime-specific tool labels into one comparison namespace while
+ * retaining source identity for audit and future protocol migrations.
+ */
+export declare function normalizeToolIdentity(input: ToolIdentityInput): NormalizedToolIdentity;