@agent-finops/core 0.7.3 → 0.8.0

package/dist/localAgentFormats/gemini.js

@@ -0,0 +1,443 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+class DiagnosticCounter {
+    #counts = new Map();
+    add(code, count = 1) {
+        this.#counts.set(code, (this.#counts.get(code) ?? 0) + count);
+    }
+    values() {
+        return [...this.#counts].map(([code, count]) => ({ code, count }));
+    }
+}
+/** Parse a Gemini chat file according to its caller-supplied extension. */
+export function parseGeminiSession(content, options) {
+    const extension = extensionOf(options.filePath);
+    if (extension === ".jsonl")
+        return parseGeminiJsonlSession(content, options);
+    if (extension === ".json")
+        return parseGeminiJsonSession(content, options);
+    // A registry should normally constrain extensions. This fallback keeps the
+    // standalone API useful without guessing a malformed JSON document is JSONL.
+    try {
+        JSON.parse(content);
+        return parseGeminiJsonSession(content, options);
+    }
+    catch {
+        return parseGeminiJsonlSession(content, options);
+    }
+}
+/** Parse the legacy whole-conversation JSON representation. */
+export function parseGeminiJsonSession(content, options) {
+    const state = createState(options);
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        state.diagnostics.add("malformed_json");
+        return finish(state);
+    }
+    if (Array.isArray(parsed)) {
+        processRecordSequence(parsed, state);
+        return finish(state);
+    }
+    if (!isRecord(parsed)) {
+        state.diagnostics.add("unsupported_token_shape");
+        return finish(state);
+    }
+    state.metadata = mergeMetadata(state.metadata, parsed);
+    if (Object.prototype.hasOwnProperty.call(parsed, "messages")) {
+        if (!Array.isArray(parsed.messages)) {
+            state.diagnostics.add("unsupported_token_shape");
+            return finish(state);
+        }
+        for (const message of parsed.messages) {
+            if (isRecord(message))
+                processMessage(message, state);
+        }
+    }
+    else {
+        processRecord(parsed, state);
+    }
+    return finish(state);
+}
+/** Parse the append-only current JSONL message representation. */
+export function parseGeminiJsonlSession(content, options) {
+    // Gemini's loader remains backward compatible with a legacy conversation
+    // document even when the file has a .jsonl suffix. Accept that exact shape
+    // before falling back to the append-only line reader.
+    try {
+        const whole = JSON.parse(content);
+        if (Array.isArray(whole) || (isRecord(whole) && Array.isArray(whole.messages))) {
+            return parseGeminiJsonSession(content, options);
+        }
+    }
+    catch {
+        // A normal JSONL stream is not one JSON document.
+    }
+    const state = createState(options);
+    for (const line of content.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            state.diagnostics.add("malformed_jsonl");
+            continue;
+        }
+        if (!isRecord(parsed)) {
+            state.diagnostics.add("unsupported_token_shape");
+            continue;
+        }
+        processRecord(parsed, state);
+    }
+    return finish(state);
+}
+function createState(options) {
+    return {
+        metadata: {},
+        keyedCalls: new Map(),
+        diagnostics: new DiagnosticCounter(),
+        filePath: options.filePath,
+        ...(options.sinceMs !== undefined ? { sinceMs: options.sinceMs } : {})
+    };
+}
+function processRecordSequence(values, state) {
+    for (const value of values) {
+        if (isRecord(value))
+            processRecord(value, state);
+    }
+}
+function processRecord(record, state) {
+    if (isRecord(record.$set)) {
+        const update = record.$set;
+        state.metadata = mergeMetadata(state.metadata, update);
+        if (Object.prototype.hasOwnProperty.call(update, "messages")) {
+            if (!Array.isArray(update.messages)) {
+                state.diagnostics.add("unsupported_token_shape");
+                return;
+            }
+            // A checkpoint can replace conversational state, but earlier model work
+            // was still incurred usage. Reprocessing keyed messages updates matching
+            // ids without deleting prior unique token-bearing calls.
+            for (const message of update.messages) {
+                if (isRecord(message))
+                    processMessage(message, state);
+            }
+        }
+        return;
+    }
+    if (nonEmptyString(record.$rewindTo)) {
+        // Rewind changes resumable conversation state, not already incurred model
+        // usage. Financial evidence therefore keeps earlier token-bearing calls.
+        return;
+    }
+    state.metadata = mergeMetadata(state.metadata, record);
+    if (Object.prototype.hasOwnProperty.call(record, "messages")) {
+        if (!Array.isArray(record.messages)) {
+            state.diagnostics.add("unsupported_token_shape");
+            return;
+        }
+        for (const message of record.messages) {
+            if (isRecord(message))
+                processMessage(message, state);
+        }
+        return;
+    }
+    if (record.type === "gemini") {
+        processMessage(record, state);
+    }
+    else if (Object.prototype.hasOwnProperty.call(record, "tokens")) {
+        // Evolving token-bearing envelopes are evidence of coverage we cannot yet
+        // normalize. Surface partial coverage instead of silently omitting them.
+        state.diagnostics.add("unsupported_token_shape");
+    }
+}
+function processMessage(message, state) {
+    if (message.type !== "gemini") {
+        if (Object.prototype.hasOwnProperty.call(message, "tokens")) {
+            state.diagnostics.add("unsupported_token_shape");
+        }
+        return;
+    }
+    const messageId = nonEmptyString(message.id);
+    // A later tokenless duplicate must not erase an earlier complete snapshot.
+    // A unique tokenless Gemini response is still missing financial evidence,
+    // so retain it as unsupported instead of silently calling coverage complete.
+    if ((!Object.prototype.hasOwnProperty.call(message, "tokens") || message.tokens === null) &&
+        messageId &&
+        state.keyedCalls.get(messageId)?.usageSupport === "complete") {
+        return;
+    }
+    const timestamp = firstIsoTimestamp(message.timestamp, message.createdAt, message.created_at);
+    if (!timestamp) {
+        state.diagnostics.add("missing_timestamp");
+        return;
+    }
+    if (state.sinceMs !== undefined && Date.parse(timestamp) < state.sinceMs)
+        return;
+    const parsedTokens = parseTokens(message.tokens);
+    const metadata = mergeMetadata(state.metadata, message);
+    const attribution = explicitAttribution(message, metadata) ??
+        opaqueAttribution(state.filePath, metadata.projectHash);
+    const sessionId = firstString(message.sessionId, message.session_id, metadata.sessionId);
+    if (!messageId || !sessionId) {
+        // A stable session + message identity is required to prevent copied or
+        // checkpointed chat files from being counted twice across the chats tree.
+        state.diagnostics.add("unsupported_token_shape");
+        return;
+    }
+    const sourceVersion = sourceVersionOf(message) ?? metadata.sourceVersion;
+    const model = firstString(message.model, metadata.model) ?? "gemini-cli-unknown";
+    const startedAt = isoTimestamp(metadata.startedAt);
+    const call = {
+        agent: "gemini-cli",
+        callId: messageId,
+        model,
+        timestamp,
+        ...(startedAt ? { startedAt } : {}),
+        ...(attribution?.project ? { project: attribution.project } : {}),
+        ...(attribution?.workingDirectory
+            ? { workingDirectory: attribution.workingDirectory }
+            : {}),
+        ...(sessionId ? { sessionId } : {}),
+        usageScope: "turn",
+        usageSupport: parsedTokens.supported ? "complete" : "unsupported_token_shape",
+        ...(parsedTokens.reportedTotalTokens !== undefined
+            ? { reportedTotalTokens: parsedTokens.reportedTotalTokens }
+            : {}),
+        ...(sourceVersion ? { sourceVersion } : {}),
+        usage: parsedTokens.usage,
+        geminiTokenEvidence: parsedTokens.evidence
+    };
+    // Delete first so iteration order also reflects the authoritative snapshot.
+    state.keyedCalls.delete(messageId);
+    state.keyedCalls.set(messageId, call);
+}
+function parseTokens(value) {
+    if (!isRecord(value)) {
+        return {
+            usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 },
+            evidence: { cacheAccounting: "unknown" },
+            supported: false
+        };
+    }
+    const input = tokenField(value, "input");
+    const output = tokenField(value, "output");
+    const cached = tokenField(value, "cached");
+    const thoughts = tokenField(value, "thoughts");
+    const tool = tokenField(value, "tool");
+    const total = tokenField(value, "total");
+    const detailedFieldsValid = thoughts.present && thoughts.value !== undefined &&
+        tool.present && tool.value !== undefined;
+    const requiredFieldsValid = input.present && input.value !== undefined &&
+        output.present && output.value !== undefined &&
+        cached.present && cached.value !== undefined &&
+        total.present && total.value !== undefined;
+    const rawInput = input.value;
+    const rawOutput = output.value;
+    const rawCached = cached.value;
+    const rawThoughts = thoughts.value ?? 0;
+    const rawTool = tool.value ?? 0;
+    const rawTotal = total.value;
+    let cacheAccounting = "unknown";
+    if (requiredFieldsValid && detailedFieldsValid &&
+        rawInput !== undefined && rawOutput !== undefined &&
+        rawCached !== undefined && rawTotal !== undefined) {
+        const includedTotal = rawInput + rawOutput + rawThoughts + rawTool;
+        if (Number.isSafeInteger(includedTotal)) {
+            if (rawCached === 0 && rawTotal === includedTotal) {
+                cacheAccounting = "none";
+            }
+            else if (rawTotal === includedTotal && rawCached <= rawInput) {
+                cacheAccounting = "included";
+            }
+        }
+    }
+    const supported = requiredFieldsValid && detailedFieldsValid &&
+        cacheAccounting !== "unknown";
+    const normalizedInput = cacheAccounting === "included"
+        ? (rawInput ?? 0) - (rawCached ?? 0)
+        : cacheAccounting === "none"
+            ? rawInput ?? 0
+            : 0;
+    // Cached is an independently reported component. Retain it even when the
+    // fresh-input split is ambiguous; fresh input remains zero in that state so
+    // this never double-counts an uncertain overlap.
+    const normalizedCache = rawCached ?? 0;
+    return {
+        usage: {
+            inputTokens: normalizedInput,
+            outputTokens: rawOutput ?? 0,
+            ...(cached.value !== undefined ? { cacheReadTokens: normalizedCache } : {}),
+            ...(thoughts.value !== undefined ? { thoughtTokens: rawThoughts } : {}),
+            ...(tool.value !== undefined ? { toolTokens: rawTool } : {})
+        },
+        evidence: {
+            ...(rawInput !== undefined ? { input: rawInput } : {}),
+            ...(rawOutput !== undefined ? { output: rawOutput } : {}),
+            ...(rawCached !== undefined ? { cached: rawCached } : {}),
+            ...(thoughts.value !== undefined ? { thoughts: thoughts.value } : {}),
+            ...(tool.value !== undefined ? { tool: tool.value } : {}),
+            ...(rawTotal !== undefined ? { total: rawTotal } : {}),
+            cacheAccounting
+        },
+        supported,
+        ...(rawTotal !== undefined ? { reportedTotalTokens: rawTotal } : {})
+    };
+}
+function tokenField(record, key) {
+    if (!Object.prototype.hasOwnProperty.call(record, key))
+        return { present: false };
+    const value = record[key];
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+        ? { present: true, value }
+        : { present: true };
+}
+function mergeMetadata(current, record) {
+    const sessionId = firstString(record.sessionId, record.session_id);
+    const projectHash = nonEmptyString(record.projectHash);
+    const startedAt = firstIsoTimestamp(record.startTime, record.startedAt);
+    const model = nonEmptyString(record.model);
+    const sourceVersion = sourceVersionOf(record);
+    const explicit = explicitAttributionFromRecord(record, projectHash ?? current.projectHash);
+    return {
+        ...current,
+        ...(sessionId ? { sessionId } : {}),
+        ...(projectHash ? { projectHash } : {}),
+        ...(startedAt ? { startedAt } : {}),
+        ...(model ? { model } : {}),
+        ...(sourceVersion ? { sourceVersion } : {}),
+        ...(explicit?.project ? { project: explicit.project } : {}),
+        ...(explicit?.workingDirectory
+            ? { workingDirectory: explicit.workingDirectory }
+            : {})
+    };
+}
+function sourceVersionOf(record) {
+    return safeVersionString(record.geminiCliVersion) ?? safeVersionString(record.cliVersion);
+}
+function safeVersionString(value) {
+    const parsed = nonEmptyString(value);
+    return parsed && parsed.length <= 64 && /^[A-Za-z0-9][A-Za-z0-9.+_-]*$/.test(parsed)
+        ? parsed
+        : undefined;
+}
+function explicitAttribution(record, metadata) {
+    return explicitAttributionFromRecord(record, metadata.projectHash) ??
+        (metadata.project || metadata.workingDirectory
+            ? {
+                ...(metadata.project ? { project: metadata.project } : {}),
+                ...(metadata.workingDirectory
+                    ? { workingDirectory: metadata.workingDirectory }
+                    : {})
+            }
+            : undefined);
+}
+function explicitAttributionFromRecord(record, projectHash) {
+    const pathValue = firstString(record.cwd, record.workingDirectory, record.working_directory, record.projectPath, record.project_path);
+    if (pathValue && isAbsolutePath(pathValue)) {
+        const normalized = trimTrailingSeparators(pathValue);
+        const project = lastPathSegment(normalized);
+        if (project)
+            return { project, workingDirectory: normalized };
+    }
+    const project = nonEmptyString(record.project);
+    if (!project || project === projectHash || looksLikeProjectHash(project))
+        return undefined;
+    if (project.includes("/") || project.includes("\\"))
+        return undefined;
+    return { project };
+}
+function opaqueAttribution(filePath, metadataProjectHash) {
+    const pathProjectHash = projectHashFromPath(filePath);
+    const recordedProjectHash = metadataProjectHash && looksLikeProjectHash(metadataProjectHash)
+        ? metadataProjectHash
+        : undefined;
+    // Conflicting opaque identities are not attribution evidence. Financial
+    // tokens remain usable, but project ownership stays unattributed.
+    if (pathProjectHash && recordedProjectHash && pathProjectHash !== recordedProjectHash) {
+        return undefined;
+    }
+    const projectHash = pathProjectHash ?? recordedProjectHash;
+    if (!projectHash)
+        return undefined;
+    const alias = createHash("sha256").update(projectHash).digest("hex").slice(0, 12);
+    return { project: `gemini-project-${alias}` };
+}
+function projectHashFromPath(filePath) {
+    const parts = filePath.split(/[\\/]+/).filter(Boolean);
+    for (let index = parts.length - 1; index >= 0; index -= 1) {
+        if (parts[index] !== "chats" || index === 0)
+            continue;
+        const value = parts[index - 1];
+        if (value && looksLikeProjectHash(value))
+            return value;
+    }
+    return undefined;
+}
+function looksLikeProjectHash(value) {
+    return /^[a-f\d]{64}$/i.test(value);
+}
+function isAbsolutePath(value) {
+    return isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value) || /^\\\\/.test(value);
+}
+function trimTrailingSeparators(value) {
+    const trimmed = value.replace(/[\\/]+$/, "");
+    return trimmed || value;
+}
+function lastPathSegment(value) {
+    return value.split(/[\\/]+/).filter(Boolean).at(-1);
+}
+function finish(state) {
+    const calls = [...state.keyedCalls.values()]
+        .sort((left, right) => left.timestamp.localeCompare(right.timestamp));
+    const unsupported = calls.filter((call) => (call.usageSupport === "unsupported_token_shape")).length;
+    if (unsupported > 0)
+        state.diagnostics.add("unsupported_token_shape", unsupported);
+    return {
+        calls,
+        diagnostics: state.diagnostics.values()
+    };
+}
+function extensionOf(filePath) {
+    const basename = filePath.split(/[\\/]+/).at(-1) ?? "";
+    const index = basename.lastIndexOf(".");
+    return index >= 0 ? basename.slice(index).toLowerCase() : "";
+}
+function firstString(...values) {
+    for (const value of values) {
+        const parsed = nonEmptyString(value);
+        if (parsed)
+            return parsed;
+    }
+    return undefined;
+}
+function nonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+function firstIsoTimestamp(...values) {
+    for (const value of values) {
+        const parsed = isoTimestamp(value);
+        if (parsed)
+            return parsed;
+    }
+    return undefined;
+}
+function isoTimestamp(value) {
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    const milliseconds = Date.parse(value);
+    if (!Number.isFinite(milliseconds))
+        return undefined;
+    return new Date(milliseconds).toISOString();
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+//# sourceMappingURL=gemini.js.map

package/dist/localAgentFormats/registry.d.ts

@@ -2,7 +2,8 @@ import type { LocalAgentFormatDescriptor, LocalAgentFormatId } from "./types.js"
 export declare const localAgentFormatDescriptors: readonly LocalAgentFormatDescriptor[];
 export declare function localAgentFormatDescriptor(id: LocalAgentFormatId): LocalAgentFormatDescriptor | undefined;
 export declare function localAgentFormatLabel(id: LocalAgentFormatId): string;
-export declare function localAgentFormatSupports(id: LocalAgentFormatId, capability: keyof LocalAgentFormatDescriptor["capabilities"]): boolean;
+export declare function localAgentFormatSupports(id: string | undefined, capability: keyof LocalAgentFormatDescriptor["capabilities"]): boolean;
 export declare function matchesLocalAgentFormatFile(descriptor: LocalAgentFormatDescriptor, filePath: string): boolean;
+export declare function matchesLocalAgentDetectionFile(descriptor: LocalAgentFormatDescriptor, filePath: string): boolean;
 export declare function validateLocalAgentFormatDescriptors(registry?: readonly LocalAgentFormatDescriptor[]): void;
 //# sourceMappingURL=registry.d.ts.map

package/dist/localAgentFormats/registry.js

@@ -1,4 +1,4 @@
-import { basename } from "node:path";
+import { basename, dirname } from "node:path";
 const descriptors = [
     {
         schemaVersion: 1,
@@ -24,13 +24,15 @@ const descriptors = [
             operation: "claude-code sessions"
         },
         capabilities: {
+            actionPlanning: true,
             activity: true,
             contextHealth: true,
             financialFastPath: true,
             glance: true,
             invocationEvidence: false,
             planContext: true,
-            rateLimits: false
+            rateLimits: false,
+            statuslineSnapshot: true
         },
         financialRead: "full_jsonl",
         validationNote: "Local transcript parsing is exercised against live logs; dollar values remain API-rate estimates.",
@@ -92,13 +94,15 @@ const descriptors = [
             operation: "codex sessions"
         },
         capabilities: {
+            actionPlanning: true,
             activity: true,
             contextHealth: true,
             financialFastPath: true,
             glance: true,
             invocationEvidence: true,
             planContext: true,
-            rateLimits: true
+            rateLimits: true,
+            statuslineSnapshot: true
         },
         financialRead: "bounded_event_jsonl",
         validationNote: "Local parsing was replayed against live logs; total-only token shapes and unknown aliases remain missing rather than becoming estimated $0.",
@@ -135,6 +139,87 @@ const descriptors = [
             ]
         },
         fixtures: ["codex-v1"]
+    },
+    {
+        schemaVersion: 1,
+        id: "gemini-cli",
+        order: 30,
+        label: "Gemini CLI",
+        provider: "google",
+        defaultHomeRelative: [".gemini", "tmp"],
+        legacyDirectoryOption: "geminiSessionsDir",
+        discovery: {
+            extensions: [".json", ".jsonl"],
+            ancestorBasename: "chats",
+            detectionBasename: "logs.json"
+        },
+        confidenceDefaults: {
+            validationCoverage: "fixture_verified",
+            pricedFinancialEvidence: "estimated",
+            unpricedFinancialEvidence: "missing",
+            sourceConfidence: "estimated"
+        },
+        sourceRecord: {
+            id: "local-agent-logs",
+            name: "Local agent session logs",
+            providerCostType: "local_agent_logs",
+            observedFrom: "gemini-cli chats session JSON/JSONL (this machine)",
+            usageGranularity: "daily_aggregate",
+            operation: "gemini-cli sessions"
+        },
+        capabilities: {
+            actionPlanning: false,
+            activity: false,
+            contextHealth: false,
+            financialFastPath: true,
+            glance: false,
+            invocationEvidence: false,
+            planContext: false,
+            rateLimits: false,
+            statuslineSnapshot: false
+        },
+        financialRead: "full_session_files",
+        validationNote: "Gemini CLI session support is experimental and fixture-verified; evolving, incomplete, or modality-ambiguous token shapes remain missing rather than becoming estimated $0.",
+        docs: {
+            format: "JSON and JSON Lines under ~/.gemini/tmp/<opaque-project-id>/chats/**/*.{json,jsonl}",
+            howRead: [
+                "Read supported Gemini response records from chats session JSON or JSONL files, including nested subagent sessions.",
+                "For repeated JSONL message ids, retain the last token-bearing version so streaming updates are not double-counted.",
+                "Use logs.json only to detect that Gemini CLI is present; it never enters the financial parser or creates a financial row."
+            ],
+            fieldsRead: [
+                "timestamp, model, and explicit input, output, cached, thought, tool, and total token components",
+                "session identity and usable session-carried project metadata when present",
+                "Gemini CLI version metadata when the session format reports it"
+            ],
+            verified: [
+                "Synthetic recorded fixtures lock supported legacy JSON and current JSONL shapes, including cache-overlap and duplicate-message handling."
+            ],
+            estimated: [
+                "Complete, internally consistent Gemini 2.5 Pro token components are priced at published API rates as API-equivalent value only when the request's pricing tier is unambiguous.",
+                "Thought tokens are output-priced and tool tokens input-priced only when the explicit split is supported."
+            ],
+            notVerified: [
+                "Gemini CLI chat files are evolving and this reader is experimental, not live-verified.",
+                "API-equivalent value is not billed spend, subscription cost, savings, or ROI.",
+                "Session token counters do not establish authentication billing mode, free-tier coverage, subscription coverage, grounding/search fees, tool-specific fees, or context-cache storage duration charges.",
+                "Unknown models, missing components, and inconsistent totals remain missing financial evidence rather than estimated $0.",
+                "Gemini 2.5 Flash and Flash-Lite rows remain missing because chats summaries omit token modality while published audio and non-audio rates differ."
+            ],
+            privacy: [
+                "Parsing and aggregation run locally; raw prompts and responses are not returned by the parser registry.",
+                "Opaque project hashes are never reversed, guessed, or exposed; an opaque local alias is used when no usable project field exists.",
+                "aibill never sits in the inference path and never stores, prints, or proxies provider credentials."
+            ],
+            limitations: [
+                "The <opaque-project-id> directory is not treated as a readable project path.",
+                "logs.json contains prompt-history/resume metadata, not financial token evidence.",
+                "Normalized inputTokens/outputTokens are inclusive headline totals; cached/tool/thought fields are component subsets and must not be added again.",
+                "A Gemini 2.5 Pro request remains unpriced when separate prompt and tool-token counts straddle the published 200k pricing threshold.",
+                "Rewound JSONL turns still represent incurred usage; this reader does not reconstruct a cost-free final conversation."
+            ]
+        },
+        fixtures: ["gemini-cli-v1"]
     }
 ];
 export const localAgentFormatDescriptors = Object.freeze([...descriptors]
@@ -147,18 +232,25 @@ export function localAgentFormatLabel(id) {
     return localAgentFormatDescriptor(id)?.label ?? id;
 }
 export function localAgentFormatSupports(id, capability) {
-    return localAgentFormatDescriptor(id)?.capabilities[capability] === true;
+    return localAgentFormatDescriptors.some((descriptor) => (descriptor.id === id && descriptor.capabilities[capability] === true));
 }
 export function matchesLocalAgentFormatFile(descriptor, filePath) {
     const name = basename(filePath);
-    if (descriptor.discovery.extension && !name.endsWith(descriptor.discovery.extension))
+    const extensions = descriptor.discovery.extensions ?? (descriptor.discovery.extension ? [descriptor.discovery.extension] : []);
+    if (extensions.length > 0 && !extensions.some((extension) => name.endsWith(extension)))
         return false;
     if (descriptor.discovery.basename && name !== descriptor.discovery.basename)
         return false;
     if (descriptor.discovery.basenamePrefix && !name.startsWith(descriptor.discovery.basenamePrefix))
         return false;
+    if (descriptor.discovery.ancestorBasename && !hasAncestorBasename(filePath, descriptor.discovery.ancestorBasename))
+        return false;
     return true;
 }
+export function matchesLocalAgentDetectionFile(descriptor, filePath) {
+    return Boolean(descriptor.discovery.detectionBasename &&
+        basename(filePath) === descriptor.discovery.detectionBasename);
+}
 export function validateLocalAgentFormatDescriptors(registry = localAgentFormatDescriptors) {
     const ids = new Set();
     const orders = new Set();
@@ -179,13 +271,24 @@ export function validateLocalAgentFormatDescriptors(registry = localAgentFormatD
             throw new Error(`Unsafe default local-agent root for ${descriptor.id}.`);
         }
         const discovery = descriptor.discovery;
-        if (!discovery.extension && !discovery.basename && !discovery.basenamePrefix) {
+        if (!discovery.extension && !discovery.extensions?.length &&
+            !discovery.basename && !discovery.basenamePrefix) {
             throw new Error(`Local-agent format ${descriptor.id} must declare a bounded file rule.`);
         }
-        if (discovery.extension && !/^\.[A-Za-z0-9]+$/.test(discovery.extension)) {
-            throw new Error(`Unsafe discovery extension for ${descriptor.id}.`);
+        for (const extension of [
+            ...(discovery.extension ? [discovery.extension] : []),
+            ...(discovery.extensions ?? [])
+        ]) {
+            if (!/^\.[A-Za-z0-9]+$/.test(extension)) {
+                throw new Error(`Unsafe discovery extension for ${descriptor.id}.`);
+            }
         }
-        for (const value of [discovery.basename, discovery.basenamePrefix]) {
+        for (const value of [
+            discovery.basename,
+            discovery.basenamePrefix,
+            discovery.ancestorBasename,
+            discovery.detectionBasename
+        ]) {
             if (value && (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) || /[\\/\u0000]/.test(value))) {
                 throw new Error(`Unsafe discovery filename rule for ${descriptor.id}.`);
             }
@@ -204,6 +307,8 @@ export function validateLocalAgentFormatDescriptors(registry = localAgentFormatD
 }
 function freezeDescriptor(descriptor) {
     Object.freeze(descriptor.defaultHomeRelative);
+    if (descriptor.discovery.extensions)
+        Object.freeze(descriptor.discovery.extensions);
     Object.freeze(descriptor.discovery);
     Object.freeze(descriptor.confidenceDefaults);
     Object.freeze(descriptor.sourceRecord);
@@ -216,4 +321,15 @@ function freezeDescriptor(descriptor) {
     Object.freeze(descriptor.fixtures);
     return Object.freeze(descriptor);
 }
+function hasAncestorBasename(filePath, expected) {
+    let current = dirname(filePath);
+    while (true) {
+        if (basename(current) === expected)
+            return true;
+        const parent = dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
 //# sourceMappingURL=registry.js.map