@automaton-labs/aib 0.0.7 → 0.0.8

package/dist/agent-dx/agent-dx.js

@@ -0,0 +1,805 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_DX_TESTING = void 0;
+exports.collectUnknownFlagSignal = collectUnknownFlagSignal;
+exports.recordAgentDxObservation = recordAgentDxObservation;
+exports.collectAgentDxObservationSignals = collectAgentDxObservationSignals;
+exports.applyAgentDxSignals = applyAgentDxSignals;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const product_storage_1 = require("../config/product-storage");
+const env_vars_1 = require("../config/env-vars");
+const session_workspace_1 = require("../commands/session-workspace");
+const presentation_1 = require("./presentation");
+const AGENT_TEXT_FIELD = "__aibText";
+function collectUnknownFlagSignal(input) {
+    const valueFlags = input.valueFlags ?? new Set();
+    const unknownFlags = [];
+    for (let index = 0; index < input.args.length; index += 1) {
+        const current = input.args[index] ?? "";
+        if (!current.startsWith("-") || current === "--") {
+            continue;
+        }
+        if (input.knownFlags.has(current)) {
+            if (valueFlags.has(current)) {
+                index += 1;
+            }
+            continue;
+        }
+        unknownFlags.push(current);
+    }
+    if (unknownFlags.length === 0) {
+        return null;
+    }
+    return {
+        kind: "unknownFlag",
+        command: input.command,
+        flags: uniqueStrings(unknownFlags),
+        ...(input.helpRefs ? { helpRefs: input.helpRefs } : {}),
+        ...(input.suggestions ? { suggestions: input.suggestions } : {})
+    };
+}
+function recordAgentDxObservation(cwd, observation) {
+    collectAgentDxObservationSignals(cwd, observation);
+}
+function collectAgentDxObservationSignals(cwd, observation) {
+    const policy = resolveAgentDxPolicy();
+    const state = readAgentDxState(cwd);
+    const nowMs = Date.now();
+    const stored = {
+        ...observation,
+        targets: observation.targets.filter((target) => target.length > 0).slice(0, 20),
+        atMs: nowMs
+    };
+    state.observations = trimObservations([...state.observations, stored], nowMs, policy);
+    state.updatedAt = new Date(nowMs).toISOString();
+    const signals = buildObservationSignals(state, stored, nowMs, policy);
+    writeAgentDxState(state);
+    return signals;
+}
+function applyAgentDxSignals(cwd, response, signals) {
+    const persistentSignals = mergeAgentDxSignals(signals.filter((signal) => Boolean(signal)));
+    if (persistentSignals.length === 0) {
+        return response;
+    }
+    const state = readAgentDxState(cwd);
+    const now = new Date().toISOString();
+    for (const signal of persistentSignals) {
+        const key = signalKey(signal);
+        const item = state.signals[key] ?? {
+            count: 0,
+            firstSeenAt: now,
+            lastSeenAt: now,
+            shownCount: 0
+        };
+        item.count += 1;
+        item.lastSeenAt = now;
+        if (buildReminder(signal)) {
+            item.shownCount += 1;
+            item.lastShownAt = now;
+        }
+        state.signals[key] = item;
+    }
+    state.updatedAt = now;
+    writeAgentDxState(state);
+    const reminders = buildReminders(mergeAgentDxResponseSignals(persistentSignals));
+    if (reminders.length === 0) {
+        return response;
+    }
+    const nextResponse = {
+        ...response,
+        agentDx: {
+            schemaVersion: 1,
+            reminders: reminders.map((reminder) => ({
+                kind: reminder.kind,
+                level: reminder.level,
+                command: reminder.command,
+                flags: reminder.flags,
+                textLines: reminder.textLines,
+                ...(reminder.helpRefs ? { helpRefs: reminder.helpRefs } : {}),
+                ...(reminder.suggestions ? { suggestions: reminder.suggestions } : {})
+            }))
+        }
+    };
+    const existingText = nextResponse[AGENT_TEXT_FIELD];
+    if (typeof existingText === "string" && existingText !== "") {
+        nextResponse[AGENT_TEXT_FIELD] = (0, presentation_1.appendAgentDxText)(existingText, nextResponse);
+    }
+    return nextResponse;
+}
+function buildReminders(signals) {
+    const unknownSignals = signals.filter(isUnknownFlagSignal);
+    const inspectUnknown = unknownSignals.filter((signal) => signal.command.startsWith("inspect ") &&
+        signal.flags.length > 0);
+    const mutateUnknown = unknownSignals.filter((signal) => signal.command.startsWith("mutate ") &&
+        signal.flags.length > 0);
+    const inspectKeys = new Set(inspectUnknown.map((signal) => signalKey(signal)));
+    const mutateKeys = new Set(mutateUnknown.map((signal) => signalKey(signal)));
+    const reminders = signals
+        .filter((signal) => !inspectKeys.has(signalKey(signal)) && !mutateKeys.has(signalKey(signal)))
+        .map(buildReminder)
+        .filter((reminder) => reminder !== null);
+    if (inspectUnknown.length === 1) {
+        const reminder = buildReminder(inspectUnknown[0]);
+        if (reminder) {
+            reminders.push(reminder);
+        }
+    }
+    else if (inspectUnknown.length > 1) {
+        reminders.push(buildInspectUnknownFlagReminder(inspectUnknown));
+    }
+    if (mutateUnknown.length > 0) {
+        reminders.push(buildMutateUnknownFlagReminder(mutateUnknown));
+    }
+    return reminders;
+}
+function buildInspectUnknownFlagReminder(signals) {
+    const byFlags = new Map();
+    const helpRefs = mergeHelpRefs(...signals.map((signal) => signal.helpRefs));
+    for (const signal of signals) {
+        const flags = uniqueStrings(signal.flags);
+        const key = flags.join("\0");
+        const group = byFlags.get(key) ?? { flags, ops: [] };
+        const op = signal.command.slice("inspect ".length);
+        if (op && !group.ops.includes(op)) {
+            group.ops.push(op);
+        }
+        byFlags.set(key, group);
+    }
+    const helpTopics = uniqueStrings((helpRefs ?? []).map((ref) => ref.topic));
+    const textLines = [
+        "inspect request uses unsupported options:",
+        ...Array.from(byFlags.values()).map((group) => `${group.ops.join(", ")}: ${group.flags.join(" ")}`)
+    ];
+    if (helpTopics.length > 0) {
+        textLines.push(`Help: aib help ${helpTopics.join(" ")}`);
+    }
+    return {
+        kind: "unknownFlag",
+        level: "short",
+        command: "inspect request",
+        flags: uniqueStrings(signals.flatMap((signal) => signal.flags)),
+        textLines,
+        ...(helpRefs ? { helpRefs } : {})
+    };
+}
+function buildMutateUnknownFlagReminder(signals) {
+    const byFlags = new Map();
+    const helpRefs = mergeHelpRefs(...signals.map((signal) => signal.helpRefs));
+    for (const signal of signals) {
+        const flags = uniqueStrings(signal.flags);
+        const key = flags.join("\0");
+        const group = byFlags.get(key) ?? { flags, ops: [] };
+        const op = formatMutateUnknownFlagOperation(signal.command);
+        if (op && !group.ops.includes(op)) {
+            group.ops.push(op);
+        }
+        byFlags.set(key, group);
+    }
+    const helpTopics = uniqueStrings((helpRefs ?? []).map((ref) => ref.topic));
+    const textLines = [
+        "mutate preview uses unsupported options:",
+        ...Array.from(byFlags.values()).map((group) => `${group.ops.join(", ")}: ${group.flags.join(" ")}`)
+    ];
+    if (helpTopics.length > 0) {
+        textLines.push(`Help: aib help ${helpTopics.join(" ")}`);
+    }
+    return {
+        kind: "unknownFlag",
+        level: "short",
+        command: "mutate preview",
+        flags: uniqueStrings(signals.flatMap((signal) => signal.flags)),
+        textLines,
+        ...(helpRefs ? { helpRefs } : {})
+    };
+}
+function formatMutateUnknownFlagOperation(command) {
+    const op = command.slice("mutate ".length).trim();
+    switch (op) {
+        case "semantic rename":
+            return "rename";
+        case "semantic move":
+            return "move";
+        case "file moveToDir":
+            return "moveToDir";
+        case "file rename":
+            return "renameFile";
+        case "module":
+            return "module";
+        default:
+            return op;
+    }
+}
+function mergeAgentDxSignals(signals, keyForSignal = signalKey) {
+    const byCommand = new Map();
+    for (const signal of signals) {
+        const key = keyForSignal(signal);
+        const existing = byCommand.get(key);
+        if (!existing) {
+            byCommand.set(key, signal.kind === "unknownFlag" ? {
+                ...signal,
+                flags: uniqueStrings(signal.flags)
+            } : signal);
+            continue;
+        }
+        if (existing.kind !== "unknownFlag" || signal.kind !== "unknownFlag") {
+            continue;
+        }
+        existing.flags = uniqueStrings([...existing.flags, ...signal.flags]);
+        const helpRefs = mergeHelpRefs(existing.helpRefs, signal.helpRefs);
+        if (helpRefs) {
+            existing.helpRefs = helpRefs;
+        }
+        const suggestions = mergeSuggestions(existing.suggestions, signal.suggestions);
+        if (suggestions) {
+            existing.suggestions = suggestions;
+        }
+    }
+    return Array.from(byCommand.values());
+}
+function mergeAgentDxResponseSignals(signals) {
+    return mergeAgentDxSignals(signals, responseSignalKey);
+}
+function responseSignalKey(signal) {
+    return signal.kind === "unknownFlag"
+        ? `${signal.kind}:${signal.command}`
+        : signalKey(signal);
+}
+function isUnknownFlagSignal(signal) {
+    return signal.kind === "unknownFlag";
+}
+function mergeHelpRefs(...items) {
+    const merged = items.flatMap((item) => item ?? []);
+    if (merged.length === 0) {
+        return undefined;
+    }
+    const seen = new Set();
+    return merged.filter((item) => {
+        const key = `${item.topic}:${item.reason ?? ""}:${item.mode ?? ""}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function mergeSuggestions(left, right) {
+    const merged = [...(left ?? []), ...(right ?? [])];
+    if (merged.length === 0) {
+        return undefined;
+    }
+    const seen = new Set();
+    return merged.filter((item) => {
+        const key = item.command ?? item.text ?? "";
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function buildReminder(signal) {
+    if (signal.kind === "batchSuggestion") {
+        return {
+            kind: "batchSuggestion",
+            level: "short",
+            command: signal.command,
+            flags: [],
+            textLines: [
+                `You called ${signal.command} ${signal.count} times in a row. Batch compatible reads:`,
+                signal.exampleCommand
+            ]
+        };
+    }
+    if (signal.kind === "inspectDslNudge") {
+        return {
+            kind: "inspectDslNudge",
+            level: "short",
+            command: `inspect ${signal.op}`,
+            flags: [],
+            textLines: formatInspectDslNudgeLines(signal)
+        };
+    }
+    if (signal.kind === "toolSuggestion") {
+        return {
+            kind: "toolSuggestion",
+            level: "short",
+            command: signal.command,
+            flags: [],
+            textLines: [
+                `You are reading many TS/JS files with ${signal.command}. Prefer focused inspect when you need symbols, imports, or code:`,
+                ...signal.suggestedCommands
+            ]
+        };
+    }
+    if (signal.kind !== "unknownFlag" || signal.flags.length === 0) {
+        return null;
+    }
+    const textLines = [
+        `${signal.command} does not support: ${signal.flags.join(" ")}`
+    ];
+    const suggestion = preferredSuggestion(signal.suggestions);
+    if (suggestion) {
+        textLines.push(suggestion);
+    }
+    const help = preferredHelp(signal.helpRefs);
+    if (help && suggestion !== `Use: aib help ${help.topic}`) {
+        textLines.push(`Help: aib help ${help.topic}`);
+    }
+    return {
+        kind: "unknownFlag",
+        level: "short",
+        command: signal.command,
+        flags: signal.flags,
+        textLines,
+        ...(signal.helpRefs ? { helpRefs: signal.helpRefs } : {}),
+        ...(signal.suggestions ? { suggestions: signal.suggestions } : {})
+    };
+}
+function formatInspectDslNudgeLines(signal) {
+    const intro = signal.reason === "repeatedInlineCalls"
+        ? `You called inspect ${signal.op} ${signal.callCount ?? signal.targets.length} times. Use inspect DSL for batched reads:`
+        : `You used inline multi-target inspect ${signal.op}. Prefer inspect DSL for grouped reads:`;
+    return [
+        intro,
+        "@'",
+        ...signal.exampleLines,
+        "'@ | aib inspect --stdin"
+    ];
+}
+function preferredSuggestion(suggestions) {
+    const sorted = (suggestions ?? []).slice().sort((left, right) => (left.priority ?? 100) - (right.priority ?? 100));
+    const first = sorted[0];
+    if (!first) {
+        return null;
+    }
+    if (first.command) {
+        return `Use: ${first.command}`;
+    }
+    return first.text ?? null;
+}
+function preferredHelp(helpRefs) {
+    const sorted = (helpRefs ?? []).slice().sort((left, right) => (left.priority ?? 100) - (right.priority ?? 100));
+    return sorted[0] ?? null;
+}
+function signalKey(signal) {
+    if (signal.kind === "batchSuggestion") {
+        return `${signal.kind}:${signal.command}:${signal.reason}`;
+    }
+    if (signal.kind === "toolSuggestion") {
+        return `${signal.kind}:${signal.command}:${signal.reason}`;
+    }
+    if (signal.kind === "inspectDslNudge") {
+        return `${signal.kind}:inspect:${signal.reason}:${signal.op}`;
+    }
+    return `${signal.kind}:${signal.command}:${signal.flags.slice().sort().join(",")}`;
+}
+exports.AGENT_DX_TESTING = {
+    buildReminders(signals) {
+        return buildReminders(mergeAgentDxResponseSignals(mergeAgentDxSignals(signals)));
+    }
+};
+function readAgentDxState(cwd) {
+    const scopeKey = agentDxScopeKey(cwd);
+    const file = agentDxStatePath(scopeKey);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (isObject(parsed) && parsed.version === 1 && parsed.scopeKey === scopeKey && isObject(parsed.signals)) {
+            return {
+                version: 1,
+                scopeKey,
+                updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date().toISOString(),
+                observations: Array.isArray(parsed.observations) ? normalizeObservations(parsed.observations) : [],
+                signals: normalizeSignals(parsed.signals)
+            };
+        }
+    }
+    catch {
+        // State is best-effort. Corrupt or missing state should not affect command behavior.
+    }
+    return {
+        version: 1,
+        scopeKey,
+        updatedAt: new Date().toISOString(),
+        observations: [],
+        signals: {}
+    };
+}
+function writeAgentDxState(state) {
+    try {
+        const file = agentDxStatePath(state.scopeKey);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // State is best-effort.
+    }
+}
+function agentDxStatePath(scopeKey) {
+    return path.join((0, product_storage_1.productStorageRoot)(), "agent-dx", `${safeFileName(scopeKey)}.json`);
+}
+function agentDxScopeKey(cwd) {
+    const session = (0, session_workspace_1.tryResolveCurrentSessionId)(cwd);
+    if (session.sessionId) {
+        return `session:${session.sessionId}`;
+    }
+    return `cwd:${hashText(path.resolve(cwd).toLowerCase())}`;
+}
+function normalizeSignals(value) {
+    const result = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (!isObject(raw)) {
+            continue;
+        }
+        result[key] = {
+            count: numberOrZero(raw.count),
+            firstSeenAt: typeof raw.firstSeenAt === "string" ? raw.firstSeenAt : new Date().toISOString(),
+            lastSeenAt: typeof raw.lastSeenAt === "string" ? raw.lastSeenAt : new Date().toISOString(),
+            shownCount: numberOrZero(raw.shownCount),
+            ...(typeof raw.lastShownAt === "string" ? { lastShownAt: raw.lastShownAt } : {})
+        };
+    }
+    return result;
+}
+function normalizeObservations(values) {
+    return values.flatMap((value) => {
+        if (!isObject(value)) {
+            return [];
+        }
+        const command = typeof value.command === "string" ? value.command : "";
+        const family = readObservationFamily(value.family);
+        const surface = readObservationSurface(value.surface);
+        const targets = Array.isArray(value.targets)
+            ? value.targets.filter((target) => typeof target === "string")
+            : [];
+        const atMs = typeof value.atMs === "number" && Number.isFinite(value.atMs) ? value.atMs : 0;
+        if (!command || !family || !surface || atMs <= 0) {
+            return [];
+        }
+        return [{
+                command,
+                family,
+                surface,
+                targets: targets.slice(0, 20),
+                batchable: value.batchable === true,
+                atMs
+            }];
+    });
+}
+function trimObservations(observations, nowMs, policy) {
+    return observations
+        .filter((observation) => nowMs - observation.atMs <= policy.storage.observationWindowMs)
+        .slice(-policy.storage.observationMaxCount);
+}
+function buildObservationSignals(state, current, nowMs, policy) {
+    if (current.command === "qr") {
+        return [
+            ...buildQrBatchSuggestionSignals(state, current, nowMs, policy),
+            ...buildQrOveruseSignals(state, current, nowMs, policy)
+        ];
+    }
+    if (current.family === "inspect") {
+        return buildInspectDslNudgeSignals(state, current, nowMs, policy);
+    }
+    return [];
+}
+function buildQrBatchSuggestionSignals(state, current, nowMs, policy) {
+    const config = policy.signals.repeatedQrBatch;
+    if (!config.enabled || current.surface !== "inline" || !current.batchable) {
+        return [];
+    }
+    const recent = state.observations
+        .filter((observation) => nowMs - observation.atMs <= config.windowMs)
+        .slice(-config.minCount);
+    if (recent.length < config.minCount || recent.some((observation) => observation.command !== "qr" ||
+        observation.surface !== "inline" ||
+        !observation.batchable ||
+        observation.targets.length === 0)) {
+        return [];
+    }
+    const signal = {
+        kind: "batchSuggestion",
+        command: "qr",
+        reason: "repeatedInline",
+        count: recent.length,
+        targets: uniqueStrings(recent.flatMap((observation) => observation.targets)).slice(0, 6),
+        exampleCommand: formatQrBatchExample(recent.flatMap((observation) => observation.targets), config.maxExampleItems, config.maxExampleChars),
+        windowMs: config.windowMs
+    };
+    const signalState = state.signals[signalKey(signal)];
+    if (signalState?.lastShownAt && nowMs - Date.parse(signalState.lastShownAt) < config.cooldownMs) {
+        return [];
+    }
+    return [signal];
+}
+function formatQrBatchExample(targets, maxItems, maxChars) {
+    const uniqueTargets = uniqueStrings(targets);
+    const selected = [];
+    for (const target of uniqueTargets) {
+        const candidate = `aib qr ${[...selected, target].join(" ")}`;
+        if (selected.length >= maxItems || (selected.length > 0 && candidate.length > maxChars)) {
+            break;
+        }
+        selected.push(target);
+    }
+    const hidden = Math.max(0, uniqueTargets.length - selected.length);
+    const suffix = hidden > 0 ? ` # +${hidden} more` : "";
+    return `aib qr ${selected.join(" ")}${suffix}`;
+}
+function buildInspectDslNudgeSignals(state, current, nowMs, policy) {
+    const config = policy.signals.inspectDslNudge;
+    if (!config.enabled || current.family !== "inspect" || current.surface !== "inline" || !current.batchable || current.targets.length === 0) {
+        return [];
+    }
+    const op = current.command.startsWith("inspect ") ? current.command.slice("inspect ".length) : "";
+    if (!op) {
+        return [];
+    }
+    if (current.targets.length > 1 && op !== "tree") {
+        const signal = buildInspectDslNudgeSignal({
+            reason: "inlineMultiTarget",
+            op,
+            targets: current.targets,
+            config
+        });
+        return shouldSuppressSignal(state, signal, nowMs, config.cooldownMs) ? [] : [signal];
+    }
+    const recent = state.observations
+        .filter((observation) => nowMs - observation.atMs <= config.windowMs &&
+        observation.command === current.command &&
+        observation.family === "inspect" &&
+        observation.surface === "inline" &&
+        observation.batchable &&
+        observation.targets.length > 0)
+        .slice(-config.minCount);
+    if (recent.length < config.minCount) {
+        return [];
+    }
+    const signal = buildInspectDslNudgeSignal({
+        reason: "repeatedInlineCalls",
+        op,
+        targets: recent.flatMap((observation) => observation.targets),
+        callCount: recent.length,
+        config
+    });
+    return shouldSuppressSignal(state, signal, nowMs, config.cooldownMs) ? [] : [signal];
+}
+function buildInspectDslNudgeSignal(input) {
+    const formatted = formatInspectDslExample(input.op, input.targets, input.config.maxExampleItems, input.config.maxExampleChars);
+    return {
+        kind: "inspectDslNudge",
+        reason: input.reason,
+        op: input.op,
+        targets: uniqueStrings(input.targets),
+        ...(input.callCount !== undefined ? { callCount: input.callCount } : {}),
+        exampleLines: formatted.lines,
+        hiddenCount: formatted.hiddenCount
+    };
+}
+function formatInspectDslExample(op, targets, maxItems, maxChars) {
+    const uniqueTargets = uniqueStrings(targets);
+    const lines = [];
+    for (const target of uniqueTargets) {
+        const nextLine = `${op} ${target}`;
+        const nextLines = [...lines, nextLine];
+        const nextLength = nextLines.join("\n").length;
+        if (lines.length >= maxItems || (lines.length > 0 && nextLength > maxChars)) {
+            break;
+        }
+        lines.push(nextLine);
+    }
+    const hiddenCount = Math.max(0, uniqueTargets.length - lines.length);
+    if (hiddenCount > 0) {
+        lines.push(`# +${hiddenCount} more`);
+    }
+    return { lines, hiddenCount };
+}
+function buildQrOveruseSignals(state, current, nowMs, policy) {
+    const config = policy.signals.qrOveruseTsJs;
+    if (!config.enabled || current.targets.filter(isCodeLikeTarget).length === 0) {
+        return [];
+    }
+    const recent = state.observations.filter((observation) => nowMs - observation.atMs <= config.windowMs);
+    const qrCodeTargets = recent
+        .filter((observation) => observation.command === "qr")
+        .flatMap((observation) => observation.targets.filter(isCodeLikeTarget));
+    const inspectCodeCount = recent.filter((observation) => observation.family === "inspect" &&
+        observation.targets.some(isCodeLikeTarget)).length;
+    if (qrCodeTargets.length < config.targetMinCount || inspectCodeCount > 0) {
+        return [];
+    }
+    const signal = {
+        kind: "toolSuggestion",
+        command: "qr",
+        reason: "qrOveruseTsJs",
+        observedCount: qrCodeTargets.length,
+        sampleTargets: uniqueStrings(qrCodeTargets.map(firstShellToken)).slice(0, 5),
+        suggestedCommands: [
+            "aib inspect file <file>",
+            "aib inspect imports <file>",
+            "aib inspect code <file> <selector>"
+        ]
+    };
+    const signalState = state.signals[signalKey(signal)];
+    if (signalState?.lastShownAt && nowMs - Date.parse(signalState.lastShownAt) < config.cooldownMs) {
+        return [];
+    }
+    return [signal];
+}
+function shouldSuppressSignal(state, signal, nowMs, cooldownMs) {
+    const signalState = state.signals[signalKey(signal)];
+    return Boolean(signalState?.lastShownAt && nowMs - Date.parse(signalState.lastShownAt) < cooldownMs);
+}
+let cachedAgentDxPolicy = null;
+function resolveAgentDxPolicy() {
+    if (cachedAgentDxPolicy) {
+        return cachedAgentDxPolicy;
+    }
+    cachedAgentDxPolicy = readAgentDxPolicy();
+    return cachedAgentDxPolicy;
+}
+function readAgentDxPolicy() {
+    const raw = readAgentDxPolicyJson();
+    return mergeAgentDxPolicy(DEFAULT_AGENT_DX_POLICY, raw);
+}
+function readAgentDxPolicyJson() {
+    const paths = [
+        process.env[env_vars_1.CLI_ENV.agentDxPolicyConfig],
+        path.resolve(__dirname, "..", "..", "config", "agent-dx-policy.default.json")
+    ].filter((item) => typeof item === "string" && item.trim().length > 0);
+    for (const filePath of paths) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+            if (isObject(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Policy config is best-effort; fall back to bundled defaults.
+        }
+    }
+    return null;
+}
+const DEFAULT_AGENT_DX_POLICY = {
+    schemaVersion: 1,
+    storage: {
+        observationWindowMs: 900000,
+        observationMaxCount: 200
+    },
+    signals: {
+        repeatedQrBatch: {
+            enabled: true,
+            windowMs: 3000,
+            minCount: 3,
+            cooldownMs: 600000,
+            maxExampleItems: 3,
+            maxExampleChars: 240
+        },
+        qrOveruseTsJs: {
+            enabled: true,
+            windowMs: 600000,
+            targetMinCount: 6,
+            cooldownMs: 900000
+        },
+        inspectDslNudge: {
+            enabled: true,
+            windowMs: 30000,
+            minCount: 3,
+            cooldownMs: 600000,
+            maxExampleItems: 3,
+            maxExampleChars: 320
+        }
+    }
+};
+function mergeAgentDxPolicy(base, raw) {
+    if (!raw) {
+        return base;
+    }
+    const storage = isObject(raw.storage) ? raw.storage : {};
+    const signals = isObject(raw.signals) ? raw.signals : {};
+    const repeatedQrBatch = isObject(signals.repeatedQrBatch) ? signals.repeatedQrBatch : {};
+    const qrOveruseTsJs = isObject(signals.qrOveruseTsJs) ? signals.qrOveruseTsJs : {};
+    const inspectDslNudge = isObject(signals.inspectDslNudge) ? signals.inspectDslNudge : {};
+    return {
+        schemaVersion: 1,
+        storage: {
+            observationWindowMs: readPositiveInteger(storage.observationWindowMs, base.storage.observationWindowMs),
+            observationMaxCount: readPositiveInteger(storage.observationMaxCount, base.storage.observationMaxCount)
+        },
+        signals: {
+            repeatedQrBatch: {
+                enabled: readBoolean(repeatedQrBatch.enabled, base.signals.repeatedQrBatch.enabled),
+                windowMs: readPositiveInteger(repeatedQrBatch.windowMs, base.signals.repeatedQrBatch.windowMs),
+                minCount: readPositiveInteger(repeatedQrBatch.minCount, base.signals.repeatedQrBatch.minCount),
+                cooldownMs: readPositiveInteger(repeatedQrBatch.cooldownMs, base.signals.repeatedQrBatch.cooldownMs),
+                maxExampleItems: readPositiveInteger(repeatedQrBatch.maxExampleItems, base.signals.repeatedQrBatch.maxExampleItems),
+                maxExampleChars: readPositiveInteger(repeatedQrBatch.maxExampleChars, base.signals.repeatedQrBatch.maxExampleChars)
+            },
+            qrOveruseTsJs: {
+                enabled: readBoolean(qrOveruseTsJs.enabled, base.signals.qrOveruseTsJs.enabled),
+                windowMs: readPositiveInteger(qrOveruseTsJs.windowMs, base.signals.qrOveruseTsJs.windowMs),
+                targetMinCount: readPositiveInteger(qrOveruseTsJs.targetMinCount, base.signals.qrOveruseTsJs.targetMinCount),
+                cooldownMs: readPositiveInteger(qrOveruseTsJs.cooldownMs, base.signals.qrOveruseTsJs.cooldownMs)
+            },
+            inspectDslNudge: {
+                enabled: readBoolean(inspectDslNudge.enabled, base.signals.inspectDslNudge.enabled),
+                windowMs: readPositiveInteger(inspectDslNudge.windowMs, base.signals.inspectDslNudge.windowMs),
+                minCount: readPositiveInteger(inspectDslNudge.minCount, base.signals.inspectDslNudge.minCount),
+                cooldownMs: readPositiveInteger(inspectDslNudge.cooldownMs, base.signals.inspectDslNudge.cooldownMs),
+                maxExampleItems: readPositiveInteger(inspectDslNudge.maxExampleItems, base.signals.inspectDslNudge.maxExampleItems),
+                maxExampleChars: readPositiveInteger(inspectDslNudge.maxExampleChars, base.signals.inspectDslNudge.maxExampleChars)
+            }
+        }
+    };
+}
+function readPositiveInteger(value, fallback) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function readBoolean(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+function isCodeLikeTarget(target) {
+    return /\.(?:cjs|cts|js|jsx|mjs|mts|ts|tsx)(?:\s|$)/i.test(firstShellToken(target));
+}
+function firstShellToken(value) {
+    return value.trim().split(/\s+/, 1)[0] ?? "";
+}
+function readObservationFamily(value) {
+    return value === "read" || value === "inspect" || value === "mutation" || value === "view" || value === "other"
+        ? value
+        : null;
+}
+function readObservationSurface(value) {
+    return value === "inline" || value === "stdin-dsl" || value === "json" || value === "stdin-raw"
+        ? value
+        : null;
+}
+function safeFileName(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 120);
+}
+function hashText(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value).digest("hex").slice(0, 16);
+}
+function uniqueStrings(values) {
+    return Array.from(new Set(values));
+}
+function numberOrZero(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}