agentfootprint 10.3.0 → 10.4.0

package/dist/tool-lint/rules.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * Structural lint rules (RFC-002 block C2) — the PLUGGABLE RULE PACK.
+ *
+ * Pattern: Strategy list — each rule is a plain `{ id, check }` object;
+ *          `defaultStructuralRules` is OUR pack, and consumers add /
+ *          remove / replace freely via `AnalyzeToolCatalogOptions.rules`.
+ *          Parameterizable rules ship as FACTORIES (`descriptionRule`,
+ *          `saysWhatNotWhenRule`, …) returning a configured `LintRule`.
+ * Role:    `src/tool-lint/` leaf. Pure functions over `CatalogTool`;
+ *          no embedder, no I/O.
+ *
+ * Every rule encodes a FIELD FINDING from real catalogs (the Neo SAN
+ * triage agent's 29-tool catalog was the seed corpus):
+ *
+ *   1. description-missing-or-short — the model can only guess from a name.
+ *   2. says-what-not-when — describes WHAT the tool returns but gives the
+ *      model no cue for WHEN to pick it over a sibling (the #1 cause of
+ *      twin-tool confusion: 'get_fcns_database' vs 'influx_get_fcns_database').
+ *   3. enum-in-prose — string params whose legal values are listed in prose
+ *      ("avg_iops | peak_iops | mbps") instead of a JSON-Schema `enum` the
+ *      model (and validators, see #9 tool-args validation) can act on.
+ *   4. optional-param-undocumented — optional params whose omission has
+ *      meaning (fabric-wide sweep vs one switch) but whose schema never
+ *      says so; the model can't reason about leaving them out.
+ *
+ * Honest claim: these are token/regex HEURISTICS. They flag review
+ * prompts, not certainties — expect (rare) false positives and tune via
+ * the factory options instead of deleting the rule.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultStructuralRules = exports.optionalParamRule = exports.DEFAULT_OMISSION_CUES = exports.enumInProseRule = exports.saysWhatNotWhenRule = exports.DEFAULT_WHEN_CUES = exports.descriptionRule = void 0;
+/** Read `properties` / `required` out of a JSON-Schema-ish inputSchema,
+ *  tolerating absent or malformed shapes (rules must never throw). */
+function readObjectSchema(tool) {
+    const schema = tool.inputSchema;
+    const props = schema?.properties;
+    const properties = props !== null && typeof props === 'object'
+        ? Object.entries(props).filter((entry) => entry[1] !== null && typeof entry[1] === 'object')
+        : [];
+    const required = new Set(Array.isArray(schema?.required) ? schema.required.filter((r) => typeof r === 'string') : []);
+    return { properties, required };
+}
+function hasWholeWord(text, word) {
+    return new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(word.toLowerCase())}(?:[^a-z0-9]|$)`).test(text.toLowerCase());
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Missing description → `error` (the model can only guess from the
+ * name). Present but shorter than `minChars` → `warn` (too short to
+ * differentiate from siblings).
+ */
+function descriptionRule(options = {}) {
+    const minChars = options.minChars ?? 40;
+    return {
+        id: 'description-missing-or-short',
+        check(tool) {
+            const description = tool.description?.trim() ?? '';
+            if (description.length === 0) {
+                return [
+                    {
+                        rule: 'description-missing-or-short',
+                        tool: tool.name,
+                        severity: 'error',
+                        message: 'tool has no description — the model can only guess from the name',
+                    },
+                ];
+            }
+            if (description.length < minChars) {
+                return [
+                    {
+                        rule: 'description-missing-or-short',
+                        tool: tool.name,
+                        severity: 'warn',
+                        message: `description is ${description.length} chars (< ${minChars}) — too short to differentiate this tool from its siblings`,
+                    },
+                ];
+            }
+            return [];
+        },
+    };
+}
+exports.descriptionRule = descriptionRule;
+// ── Rule 2 — says WHAT, not WHEN ─────────────────────────────────────
+/** RFC-002 C2 heuristic cue list — temporal/conditional words whose
+ *  presence suggests the description says WHEN to use the tool. */
+exports.DEFAULT_WHEN_CUES = [
+    'for',
+    'when',
+    'after',
+    'first',
+    'fallback',
+    'only',
+];
+/**
+ * A description with NO temporal/conditional cue token usually describes
+ * WHAT the tool returns but never WHEN to pick it — the #1 cause of
+ * twin-tool confusion. Heuristic by design: tune `cueTokens` rather than
+ * dropping the rule. Skips tools with no description (rule 1's finding).
+ */
+function saysWhatNotWhenRule(options = {}) {
+    const cues = options.cueTokens ?? exports.DEFAULT_WHEN_CUES;
+    return {
+        id: 'says-what-not-when',
+        check(tool) {
+            const description = tool.description?.trim() ?? '';
+            if (description.length === 0)
+                return [];
+            if (cues.some((cue) => hasWholeWord(description, cue)))
+                return [];
+            return [
+                {
+                    rule: 'says-what-not-when',
+                    tool: tool.name,
+                    severity: 'warn',
+                    message: 'description says WHAT the tool returns but gives no cue for WHEN to use it ' +
+                        `(no ${cues.map((c) => `'${c}'`).join('/')}) — add the choice condition, ` +
+                        'e.g. "Use when …" / "Call FIRST" / "FALLBACK if …"',
+                },
+            ];
+        },
+    };
+}
+exports.saysWhatNotWhenRule = saysWhatNotWhenRule;
+// ── Rule 3 — enum described in prose ─────────────────────────────────
+const IDENT = '[A-Za-z][A-Za-z0-9_.-]*';
+/** `avg_iops | peak_iops | mbps` — two or more pipe-separated literals. */
+const PIPE_LIST = new RegExp(`(${IDENT})(?:\\s*\\|\\s*(?:${IDENT}))+`);
+/** `one of: red, green, blue` — comma lists only behind an explicit
+ *  values marker, so free-form examples ("e.g. 1h, 24h") don't flag. */
+const COMMA_LIST = new RegExp(`(?:one of|allowed values?|valid values?|options|values)\\s*:?\\s*(${IDENT}(?:\\s*,\\s*${IDENT})+)`, 'i');
+/**
+ * A string param whose description enumerates its legal values in prose
+ * (pipe-separated literals, or comma lists behind "one of"/"allowed
+ * values") should declare a JSON-Schema `enum` instead — the model picks
+ * reliably from enums, and arg validators (#9) can enforce them. The
+ * field case: Neo's `influx_get_port_ranking.metric` =
+ * `"avg_iops | peak_iops | mbps"`.
+ */
+function enumInProseRule() {
+    return {
+        id: 'enum-in-prose',
+        check(tool) {
+            const findings = [];
+            const { properties } = readObjectSchema(tool);
+            for (const [param, prop] of properties) {
+                if (prop.enum !== undefined)
+                    continue;
+                if (prop.type !== undefined && prop.type !== 'string')
+                    continue;
+                const description = typeof prop.description === 'string' ? prop.description : '';
+                if (description.length === 0)
+                    continue;
+                const literals = extractProseLiterals(description);
+                if (literals === undefined)
+                    continue;
+                findings.push({
+                    rule: 'enum-in-prose',
+                    tool: tool.name,
+                    severity: 'warn',
+                    param,
+                    message: `param '${param}' lists its legal values in prose ("${description.slice(0, 80)}") — declare them as a JSON-Schema enum so the model picks reliably`,
+                    suggestion: `"enum": ${JSON.stringify(literals)}`,
+                });
+            }
+            return findings;
+        },
+    };
+}
+exports.enumInProseRule = enumInProseRule;
+function extractProseLiterals(description) {
+    const pipe = PIPE_LIST.exec(description);
+    if (pipe) {
+        return pipe[0].split('|').map((v) => v.trim());
+    }
+    const comma = COMMA_LIST.exec(description);
+    if (comma) {
+        return comma[1].split(',').map((v) => v.trim());
+    }
+    return undefined;
+}
+// ── Rule 4 — optional param whose omission is undocumented ───────────
+/** Words that signal the description DOES say what omission means. */
+exports.DEFAULT_OMISSION_CUES = [
+    'optional',
+    'default',
+    'defaults',
+    'omit',
+    'omitted',
+    'if not',
+    'when not',
+    'absent',
+    'all',
+    'entire',
+    'every',
+    'fallback',
+];
+/**
+ * An optional param's omission usually MEANS something (Neo:
+ * `influx_get_interface_counters` without `switch_name` = fabric-wide
+ * sweep) — but the model can only reason about leaving a param out if
+ * the description says so. No description at all, or one with no
+ * omission cue, gets a `warn`.
+ */
+function optionalParamRule(options = {}) {
+    const cues = options.omissionCues ?? exports.DEFAULT_OMISSION_CUES;
+    return {
+        id: 'optional-param-undocumented',
+        check(tool) {
+            const findings = [];
+            const { properties, required } = readObjectSchema(tool);
+            for (const [param, prop] of properties) {
+                if (required.has(param))
+                    continue;
+                const description = typeof prop.description === 'string' ? prop.description.trim() : '';
+                if (description.length === 0) {
+                    findings.push({
+                        rule: 'optional-param-undocumented',
+                        tool: tool.name,
+                        severity: 'warn',
+                        param,
+                        message: `optional param '${param}' has no description — say what happens when it is omitted (a default? a broader scope?)`,
+                    });
+                }
+                else if (!cues.some((cue) => hasWholeWord(description, cue))) {
+                    findings.push({
+                        rule: 'optional-param-undocumented',
+                        tool: tool.name,
+                        severity: 'warn',
+                        param,
+                        message: `optional param '${param}' is described but never says what omission means — add e.g. "optional — defaults to …" / "omit for all …"`,
+                    });
+                }
+            }
+            return findings;
+        },
+    };
+}
+exports.optionalParamRule = optionalParamRule;
+// ── The default pack ─────────────────────────────────────────────────
+/**
+ * OUR rule pack, built with default options. Compose your own:
+ *
+ *   rules: [...defaultStructuralRules, myRule]                 // add
+ *   rules: defaultStructuralRules.filter(r => r.id !== '…')    // remove
+ *   rules: [descriptionRule({ minChars: 80 }), …]              // re-tune
+ */
+exports.defaultStructuralRules = [
+    descriptionRule(),
+    saysWhatNotWhenRule(),
+    enumInProseRule(),
+    optionalParamRule(),
+];
+//# sourceMappingURL=rules.js.map

package/dist/tool-lint/rules.js.map

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

package/dist/tool-lint/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * tool-lint types — the tool-catalog confusability lint contract
+ * (RFC-002 tier 1, blocks C1–C3).
+ *
+ * Pattern: Strategy seam (the plug-and-play meta-pattern) — the frame
+ *          and rule engine are the library's; the embedder, thresholds,
+ *          and structural rule pack are all consumer-injected, with our
+ *          defaults. Exactly like NarrativeFormatter / reliability /
+ *          permission / commentary strategies.
+ * Role:    `src/tool-lint/` leaf module. ZERO stack buy-in: input is a plain
+ *          `{ name, description?, inputSchema? }[]` — any OpenAI /
+ *          Anthropic / LangChain / MCP tool list normalizes to it
+ *          (see `coerceCatalog`). The library's own `Tool[]` adapts via
+ *          `catalogFromTools`.
+ *
+ * ## Honest claim (RFC-002 §2)
+ *
+ * Confusability here is embedding geometry over what the model READS
+ * (tool name + description) — a deterministic heuristic for "could the
+ * model mix these up", never a measurement of any model's actual
+ * selection function. Tier 3 (choice-entropy sampling) validates the
+ * proxy; until then treat verdicts as review prompts, not ground truth.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/tool-lint/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tool-lint/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/tool-providers/gatedTools.js.map

@@ -1 +1 @@
-{"version":3,"file":"gatedTools.js","sourceRoot":"","sources":["../../src/tool-providers/gatedTools.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;;;AAKH,uCAAuC;AACvC,4GAA4G;AAC5G,yGAAyG;AACzG,qGAAqG;AACrG,2IAA2I;AAC3I,wCAAwC;AACxC,mFAAmF;AACnF,qBAAqB;AACrB,SAAgB,UAAU,CAAC,KAAmB,EAAE,SAA4B;IAC1E,OAAO;QACL,EAAE,EAAE,OAAO;QACX,IAAI,CAAC,GAAwB;YAC3B,8DAA8D;YAC9D,8DAA8D;YAC9D,8DAA8D;YAC9D,0DAA0D;YAC1D,mDAAmD;YACnD,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpC,MAAM,MAAM,GAAG,CAAC,UAA2B,EAAmB,EAAE;YAC9D,2DAA2D;YAC3D,6DAA6D;YAC7D,oDAAoD;YACpD,4CAA4C;YAC5C,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;YAC1D,OAAO,WAAW,YAAY,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACzF,CAAC;KACF,CAAC;AACJ,CAAC;AAnBD,gCAmBC;AACD,wBAAwB"}
+{"version":3,"file":"gatedTools.js","sourceRoot":"","sources":["../../src/tool-providers/gatedTools.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;;;AASH,uCAAuC;AACvC,4GAA4G;AAC5G,yGAAyG;AACzG,qGAAqG;AACrG,2IAA2I;AAC3I,wCAAwC;AACxC,mFAAmF;AACnF,qBAAqB;AACrB,SAAgB,UAAU,CAAC,KAAmB,EAAE,SAA4B;IAC1E,OAAO;QACL,EAAE,EAAE,OAAO;QACX,IAAI,CAAC,GAAwB;YAC3B,8DAA8D;YAC9D,8DAA8D;YAC9D,8DAA8D;YAC9D,0DAA0D;YAC1D,mDAAmD;YACnD,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpC,MAAM,MAAM,GAAG,CAAC,UAA2B,EAAmB,EAAE;YAC9D,2DAA2D;YAC3D,6DAA6D;YAC7D,oDAAoD;YACpD,4CAA4C;YAC5C,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;YAC1D,OAAO,WAAW,YAAY,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACzF,CAAC;KACF,CAAC;AACJ,CAAC;AAnBD,gCAmBC;AACD,wBAAwB"}

package/dist/tool-providers/index.js

@@ -49,12 +49,12 @@
  * symbols, one door. Import from the door.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENTCORE_SIGV4_SERVICE = exports.AGENTCORE_POLICY_SESSION_HEADER = exports.AGENTCORE_GATEWAY_SEARCH_TOOL = exports.hasGatewaySearch = exports.gatewaySearchTool = exports.agentCoreGatewayUrl = exports.agentCoreGatewayTransport = exports.retryingFetch = exports.MCP_TOOL_EXTRAS_KEY = exports.GatewayAuthorizationRequiredError = exports.gatewayTransport = exports.mockMcpClient = exports.mcpServe = exports.mcpClient = exports.SKILL_SCOPED_TOOLS_ID_PREFIX = exports.skillScopedToolsTarget = exports.skillScopedTools = exports.gatedTools = exports.staticTools = void 0;
+exports.AGENTCORE_RUNTIME_SESSION_HEADER = exports.agentCoreRuntimeUrl = exports.agentCoreRuntimeMcpTransport = exports.AGENTCORE_SIGV4_SERVICE = exports.AGENTCORE_POLICY_SESSION_HEADER = exports.AGENTCORE_GATEWAY_SEARCH_TOOL = exports.hasGatewaySearch = exports.gatewaySearchTool = exports.agentCoreGatewayUrl = exports.agentCoreGatewayTransport = exports.retryingFetch = exports.MCP_TOOL_EXTRAS_KEY = exports.GatewayAuthorizationRequiredError = exports.gatewayTransport = exports.mockMcpClient = exports.mcpServe = exports.mcpClient = exports.SKILL_SCOPED_TOOLS_ID_PREFIX = exports.skillScopedToolsTarget = exports.skillScopedTools = exports.gatedTools = exports.staticTools = void 0;
 var staticTools_js_1 = require("./staticTools.js");
 Object.defineProperty(exports, "staticTools", { enumerable: true, get: function () { return staticTools_js_1.staticTools; } });
 var gatedTools_js_1 = require("./gatedTools.js");
 Object.defineProperty(exports, "gatedTools", { enumerable: true, get: function () { return gatedTools_js_1.gatedTools; } });
-var skillScopedTools_js_1 = require("./skillScopedTools.js");
+var skillScopedTools_js_1 = require("../tools/skillScopedTools.js");
 Object.defineProperty(exports, "skillScopedTools", { enumerable: true, get: function () { return skillScopedTools_js_1.skillScopedTools; } });
 // 8.7.0 — the provider-id convention, readable by anyone composing providers (and
 // by the agent builder, which uses it to name a redundant pairing at build time).
@@ -63,7 +63,7 @@ Object.defineProperty(exports, "SKILL_SCOPED_TOOLS_ID_PREFIX", { enumerable: tru
 // Re-export tool sources from the MCP module so consumers find them in
 // one place. This subpath is the ONLY place `mcpClient` is public — the
 // top-level barrel does not re-export it.
-var index_js_1 = require("../lib/mcp/index.js");
+var index_js_1 = require("../mcp/index.js");
 Object.defineProperty(exports, "mcpClient", { enumerable: true, get: function () { return index_js_1.mcpClient; } });
 Object.defineProperty(exports, "mcpServe", { enumerable: true, get: function () { return index_js_1.mcpServe; } });
 Object.defineProperty(exports, "mockMcpClient", { enumerable: true, get: function () { return index_js_1.mockMcpClient; } });
@@ -90,4 +90,13 @@ Object.defineProperty(exports, "hasGatewaySearch", { enumerable: true, get: func
 Object.defineProperty(exports, "AGENTCORE_GATEWAY_SEARCH_TOOL", { enumerable: true, get: function () { return agentcore_js_1.AGENTCORE_GATEWAY_SEARCH_TOOL; } });
 Object.defineProperty(exports, "AGENTCORE_POLICY_SESSION_HEADER", { enumerable: true, get: function () { return agentcore_js_1.AGENTCORE_POLICY_SESSION_HEADER; } });
 Object.defineProperty(exports, "AGENTCORE_SIGV4_SERVICE", { enumerable: true, get: function () { return agentcore_js_1.AGENTCORE_SIGV4_SERVICE; } });
+// An MCP server HOSTED ON AgentCore Runtime — an `http` transport whose fetch
+// carries the runtime's session, its session-busy retry and its auth (SigV4
+// through InvokeAgentRuntime, or a bearer token over HTTPS). `mcpClient` sees an
+// ordinary Streamable HTTP server.
+var transport_js_1 = require("../adapters/mcp/agentcoreRuntime/transport.js");
+Object.defineProperty(exports, "agentCoreRuntimeMcpTransport", { enumerable: true, get: function () { return transport_js_1.agentCoreRuntimeMcpTransport; } });
+Object.defineProperty(exports, "agentCoreRuntimeUrl", { enumerable: true, get: function () { return transport_js_1.agentCoreRuntimeUrl; } });
+var session_js_1 = require("../adapters/mcp/agentcoreRuntime/session.js");
+Object.defineProperty(exports, "AGENTCORE_RUNTIME_SESSION_HEADER", { enumerable: true, get: function () { return session_js_1.AGENTCORE_RUNTIME_SESSION_HEADER; } });
 //# sourceMappingURL=index.js.map

package/dist/tool-providers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tool-providers/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;;;AAEH,mDAA+C;AAAtC,6GAAA,WAAW,OAAA;AACpB,iDAA6C;AAApC,2GAAA,UAAU,OAAA;AACnB,6DAM+B;AAL7B,uHAAA,gBAAgB,OAAA;AAChB,kFAAkF;AAClF,kFAAkF;AAClF,6HAAA,sBAAsB,OAAA;AACtB,mIAAA,4BAA4B,OAAA;AAI9B,uEAAuE;AACvE,wEAAwE;AACxE,0CAA0C;AAC1C,gDAe6B;AAd3B,qGAAA,SAAS,OAAA;AACT,oGAAA,QAAQ,OAAA;AACR,yGAAA,aAAa,OAAA;AACb,4GAAA,gBAAgB,OAAA;AAChB,6HAAA,iCAAiC,OAAA;AACjC,2EAA2E;AAC3E,yEAAyE;AACzE,wDAAwD;AACxD,+GAAA,mBAAmB,OAAA;AACnB,4EAA4E;AAC5E,8EAA8E;AAC9E,2EAA2E;AAC3E,iCAAiC;AACjC,yGAAA,aAAa,OAAA;AAEf,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,yCAAyC;AACzC,6DAQsC;AAPpC,yHAAA,yBAAyB,OAAA;AACzB,mHAAA,mBAAmB,OAAA;AACnB,iHAAA,iBAAiB,OAAA;AACjB,gHAAA,gBAAgB,OAAA;AAChB,6HAAA,6BAA6B,OAAA;AAC7B,+HAAA,+BAA+B,OAAA;AAC/B,uHAAA,uBAAuB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tool-providers/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;;;AAEH,mDAA+C;AAAtC,6GAAA,WAAW,OAAA;AACpB,iDAA6C;AAApC,2GAAA,UAAU,OAAA;AACnB,oEAMsC;AALpC,uHAAA,gBAAgB,OAAA;AAChB,kFAAkF;AAClF,kFAAkF;AAClF,6HAAA,sBAAsB,OAAA;AACtB,mIAAA,4BAA4B,OAAA;AAQ9B,uEAAuE;AACvE,wEAAwE;AACxE,0CAA0C;AAC1C,4CAeyB;AAdvB,qGAAA,SAAS,OAAA;AACT,oGAAA,QAAQ,OAAA;AACR,yGAAA,aAAa,OAAA;AACb,4GAAA,gBAAgB,OAAA;AAChB,6HAAA,iCAAiC,OAAA;AACjC,2EAA2E;AAC3E,yEAAyE;AACzE,wDAAwD;AACxD,+GAAA,mBAAmB,OAAA;AACnB,4EAA4E;AAC5E,8EAA8E;AAC9E,2EAA2E;AAC3E,iCAAiC;AACjC,yGAAA,aAAa,OAAA;AAEf,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,yCAAyC;AACzC,6DAQsC;AAPpC,yHAAA,yBAAyB,OAAA;AACzB,mHAAA,mBAAmB,OAAA;AACnB,iHAAA,iBAAiB,OAAA;AACjB,gHAAA,gBAAgB,OAAA;AAChB,6HAAA,6BAA6B,OAAA;AAC7B,+HAAA,+BAA+B,OAAA;AAC/B,uHAAA,uBAAuB,OAAA;AAMzB,8EAA8E;AAC9E,4EAA4E;AAC5E,iFAAiF;AACjF,mCAAmC;AACnC,8EAGuD;AAFrD,4HAAA,4BAA4B,OAAA;AAC5B,mHAAA,mBAAmB,OAAA;AAErB,0EAA+F;AAAtF,8HAAA,gCAAgC,OAAA"}

package/dist/tools/askComponent.js.map

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