@yagni-app/code 1.0.6 → 1.0.7

package/README.md

@@ -173,62 +173,100 @@ environment is recorded in `~/.yagni-code/config.json`. A pre-profiles
 
 ### OTel export (opt-in)
 
-Point sessions at **your own** OpenTelemetry collector (Datadog Agent, Grafana
-Alloy, an OTLP-native backend) and every session — including `/go` stage
-children and subagents — emits a per-prompt span tree: interaction → LLM
-request → tool calls, following the OTel GenAI semantic conventions. Nothing is
-exported unless you configure an endpoint.
-
-Enable it one of four ways (first match wins):
-
-- `OTEL_EXPORTER_OTLP_ENDPOINT=…` in the environment (a personal override —
-  handy for pointing one session at a scratch collector), or
-- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=…` in the environment — the per-signal
-  form Claude Code setups use (e.g.
-  `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.datadoghq.com/v1/traces`
-  with `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf`); the launcher
-  bridges it to the generic var pi-otel reads, so a Claude Code OTel env
-  lights up YAGNI Code traces with no extra config, or
+Point sessions at **your own** OpenTelemetry collector (Datadog, Grafana
+Cloud, a Datadog Agent or Grafana Alloy, any OTLP-native backend) and every
+session — including `/go` stage children and subagents — exports three
+signals in the shape Claude Code's telemetry uses, under a `yagni_code`
+prefix instead of `claude_code`:
+
+- **Traces:** a per-prompt span tree, `yagni_code.interaction` →
+  `yagni_code.llm_request` and `yagni_code.tool`, carrying both the flat
+  Claude Code attributes (`model`, `input_tokens`, `cost_usd`, `tool_name`)
+  and the OTel GenAI conventions (`gen_ai.*`) that LLM-observability
+  products read. `gen_ai.operation.name` classifies each span the way those
+  products expect: `invoke_agent` on the interaction root, `chat` on the LLM
+  request, `execute_tool` on tool spans (the turn span has no semconv
+  operation and is left unset). The two count tokens differently on purpose: the flat
+  `input_tokens` / `cache_read_tokens` / `cache_creation_tokens` are disjoint,
+  exactly as Claude Code reports them, while `gen_ai.usage.input_tokens`
+  follows the semconv and includes the cached tokens, with
+  `gen_ai.usage.cache_read.input_tokens` and
+  `gen_ai.usage.cache_write.input_tokens` as subsets of it.
+  `gen_ai.cost.estimated_total` carries the same sell-rate cost as `cost_usd`
+  so vendor cost views work for the opaque tier id. It is an integer in
+  nanodollars (`cost_usd * 1e9`): Datadog reads that attribute unscaled into
+  its nanodollar cost metric, so a dollar value shows up a billion times too
+  small.
+- **Metrics:** `yagni_code.session.count`, `token.usage` (by `type` and
+  `model`), `cost.usage`, `lines_of_code.count`, `commit.count`,
+  `pull_request.count`, `code_edit_tool.decision`, `active_time.total`.
+- **Log events:** `user_prompt`, `assistant_response`, `api_request`,
+  `api_error`, `tool_result`, `tool_decision`, `permission_mode_changed`
+  (as `event.name`, body `yagni_code.<name>`), with `session.id`,
+  `organization.id`, `terminal.type`, and a per-prompt `prompt.id`.
+
+Nothing is exported unless you configure an endpoint. Enable it one of three
+ways (first match wins):
+
+- the standard OTel env in your shell — the generic
+  `OTEL_EXPORTER_OTLP_ENDPOINT` (a base URL; `/v1/<signal>` is appended for
+  http transports) or the per-signal
+  `OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_ENDPOINT` a Claude Code setup
+  already carries — so a machine configured for Claude Code lights up with
+  no extra config (with per-signal endpoints only, exactly those signals
+  export; nothing falls back to a localhost collector), or
 - **workspace settings** (the zero-setup path): a workspace admin sets the
   endpoint, protocol, and any collector headers (e.g. a Datadog API key) once
-  in the web app under Settings → YAGNI Code → Trace export. Every session in
-  the workspace picks it up at launch — nothing to install or configure on
-  developer machines. Header values are encrypted at rest server-side and the
-  launch-time copy is cached at mode `0600`, the same posture as your device
-  token. Or,
-- commit `{ "otel": { "endpoint": "http://<collector>:4317" } }` to the repo's
-  `.pi/settings.json` so one repo's sessions export without per-machine setup.
-
-Standard OTel env vars are honored (`OTEL_EXPORTER_OTLP_PROTOCOL`,
-`OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_SERVICE_NAME` — defaults to `yagni-code`),
-and `PI_OTEL_DISABLED=1` is the kill switch. `yagni doctor` shows the current
-export state and probes the endpoint live (unreachable → a warning with a
-hint, never an exit-code flip).
-
-Two recipes for common collectors:
-
-- **Datadog, direct SaaS (no agent):** endpoint
-  `https://otlp.datadoghq.com/v1/traces` (US1; other sites have their own
-  host — `otlp.us3.datadoghq.com`, `otlp.us5.datadoghq.com`,
-  `otlp.datadoghq.eu`, `otlp.ap1.datadoghq.com`), protocol `http/protobuf`
-  (Datadog's direct trace intake does not accept gRPC), header
-  `dd-api-key=<your Datadog API key>`. Use the full path, not `/v1/` — the
-  endpoint is passed through verbatim, no path is appended for you.
+  in the web app under Settings → YAGNI Code → Telemetry export. Every
+  session in the workspace picks it up at launch — nothing to install or
+  configure on developer machines. Header values are encrypted at rest
+  server-side and the launch-time copy is cached at mode `0600`, the same
+  posture as your device token. Or,
+- commit `{ "otel": { "endpoint": "http://<collector>:4317" } }` (optionally
+  with `protocol`, `headers`, `serviceName`) to the repo's `.pi/settings.json`
+  so one repo's sessions export without per-machine setup. Header values
+  must not contain commas (they travel as a comma-separated list); one that
+  does is dropped.
+
+The rest of the standard OTel env is honored the way Claude Code honors it:
+`OTEL_EXPORTER_OTLP_PROTOCOL` (and per-signal), `OTEL_EXPORTER_OTLP_HEADERS`
+(and per-signal), `OTEL_SERVICE_NAME` (defaults to `yagni-code`),
+`OTEL_RESOURCE_ATTRIBUTES`, `OTEL_{METRICS,LOGS,TRACES}_EXPORTER=none` to
+switch one signal off, `OTEL_METRIC_EXPORT_INTERVAL` /
+`OTEL_LOGS_EXPORT_INTERVAL`, `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`
+(default `delta`), and the `OTEL_METRICS_INCLUDE_*` cardinality flags.
+`YAGNI_OTEL_DISABLED=1` is the kill switch. `yagni doctor` shows the current
+export state and sends one real record per signal, printing the collector's
+own verdict (a 403 is a bad key, a 404 a bad path or site).
+
+Three recipes for common collectors:
+
+- **Datadog, direct SaaS (no agent):** endpoint `https://otlp.datadoghq.com`
+  (US1; other sites have their own host — `otlp.us3.datadoghq.com`,
+  `otlp.us5.datadoghq.com`, `otlp.datadoghq.eu`, `otlp.ap1.datadoghq.com`),
+  protocol `http/protobuf` (Datadog's direct intake does not accept gRPC),
+  header `dd-api-key=<your Datadog API key>`. Add `dd-otlp-source=llmobs`
+  (the workspace preset does) to have the traces routed into LLM
+  Observability as well as APM; the launcher scopes that header to the
+  traces request. Traces show in APM under service `yagni-code`, metrics
+  under `yagni_code.*`, events in Log Explorer as `service:yagni-code`.
 - **Datadog Agent:** endpoint `http://<agent-host>:4317`, protocol `grpc`, no
   key (the agent forwards with its own). OTLP ingest ships in the agent but
   is off by default — enable it with
   `otlp_config.receiver.protocols.grpc.endpoint: 0.0.0.0:4317` in
   `datadog.yaml`.
-- **Grafana Cloud:** endpoint `https://otlp-gateway-prod-…-0.grafana.net:443/otlp`,
-  protocol `http/protobuf`, header `authorization=<the raw MTgx… value>` (the
-  `Basic ` scheme is added for you).
+- **Grafana Cloud:** endpoint `https://otlp-gateway-prod-<region>.grafana.net/otlp`
+  (the base URL from your stack's OTLP page — signals go to `/otlp/v1/traces`
+  and friends), protocol `http/protobuf`, header `authorization=<the raw
+  MTgx… value>` (the `Basic ` scheme is added for you).
 
 Two things are enforced and not configurable:
 
-- **Metadata only.** Token counts, cost, tier, finish reasons, and tool-call
-  ids export; prompt and response text never do — a settings file or env var
-  asking for content capture is overridden.
-- **Cost is your contracted rate.** `pi.cost.usd` is computed from your
+- **Metadata only.** Token counts, cost, tier, durations, tool names, and
+  payload sizes export; prompt text, model output, tool arguments, and tool
+  results never do — `OTEL_LOG_USER_PROMPTS` and `OTEL_LOG_TOOL_DETAILS` are
+  deliberately not honored.
+- **Cost is your contracted rate.** `cost_usd` is computed from your
   workspace's tier rate card, and the exported model name is the opaque tier
   id (`advanced`, `peak`, …), so traces never fingerprint the backing model.
 

package/dist/claudeCompat.d.ts

@@ -34,6 +34,30 @@ export declare const CLAUDE_COMPAT_DISABLE_ENV = "YAGNI_DISABLE_CLAUDE_COMPAT";
 export declare const CLAUDE_AGENT_DIRS_ENV = "YAGNI_CLAUDE_AGENT_DIRS";
 /** `.claude/rules` dirs for the extension's rules injection (delimiter-joined). */
 export declare const CLAUDE_RULES_DIRS_ENV = "YAGNI_CLAUDE_RULES_DIRS";
+/**
+ * Plugin MCP servers for the extension's MCP client: a JSON array of
+ * `{ plugin, sourcePath, gated, servers }`. `${CLAUDE_PLUGIN_ROOT}` is already
+ * expanded to the plugin's install dir; other `${VAR}` references are left for
+ * the extension's normal env expansion. `gated` marks servers that came from
+ * repo config (repo marketplace, project-scope `enabledPlugins`) and must pass
+ * the same approval the repo's `.mcp.json` would.
+ */
+export declare const CLAUDE_PLUGIN_MCP_ENV = "YAGNI_CLAUDE_PLUGIN_MCP";
+/**
+ * `name@marketplace` keys of the plugins wired at launch (delimiter-joined).
+ * `/reload-plugins` diffs a fresh inventory against this baseline: pi already
+ * holds the launch-time plugins through argv, so only newer ones need the
+ * extension's `resources_discover` contribution.
+ */
+export declare const CLAUDE_PLUGIN_KEYS_ENV = "YAGNI_CLAUDE_PLUGIN_KEYS";
+export interface PluginMcpEnvEntry {
+    plugin: string;
+    sourcePath: string;
+    gated: boolean;
+    servers: Record<string, unknown>;
+}
+/** The MCP payload entries for a set of plugins (those without servers are skipped). */
+export declare function pluginMcpEntries(plugins: PluginAssets[], gated: boolean): PluginMcpEnvEntry[];
 export interface ClaudeAssetDirs {
     skills: string | null;
     commands: string | null;
@@ -61,6 +85,9 @@ export interface ClaudeCompatDecision {
     /** `.claude/rules` dirs, user first so project rules win in the prompt. */
     userRulesDirs: string[];
     projectRulesDirs: string[];
+    /** Plugin MCP servers, split by the same trust posture (project ones are approval-gated too). */
+    userMcp: PluginMcpEnvEntry[];
+    projectMcp: PluginMcpEnvEntry[];
     /** Ask the user for a trust decision before wiring any project content. */
     needsPrompt: boolean;
 }
@@ -104,6 +131,38 @@ export interface ClaudeCompatLaunch {
  * compat can only add flags/env, never break a launch.
  */
 export declare function claudeCompatArgs(deps: ClaudeCompatDeps): Promise<ClaudeCompatLaunch>;
+/** One plugin as the in-session `/plugin` panel sees it. */
+export interface InventoryPlugin {
+    key: string;
+    name: string;
+    origin: PluginAssets["origin"];
+    version: string | null;
+    root: string;
+    /** Repo-sourced: its MCP servers ride the project approval gate. */
+    gated: boolean;
+    skillPaths: string[];
+    commandPaths: string[];
+    agentDirs: string[];
+    mcpServers: string[];
+    unsupported: string[];
+}
+export interface PluginInventory {
+    /** Plugins that load for `cwd` right now (trust respected, never prompting). */
+    plugins: InventoryPlugin[];
+    /** The MCP payload those plugins contribute (same shape as YAGNI_CLAUDE_PLUGIN_MCP). */
+    mcp: PluginMcpEnvEntry[];
+    /** Repo-sourced plugins held back because the folder is not trusted yet. */
+    pendingTrust: string[];
+    /** Plugin agent dirs, user first (same order as YAGNI_CLAUDE_AGENT_DIRS). */
+    agentDirs: string[];
+}
+/**
+ * The plugin inventory a launch from `cwd` would wire, computed without
+ * prompting: the user's own plugins always, repo-sourced ones only once the
+ * folder is trusted. Backs `yagni plugin inventory --json`, which the
+ * in-session `/plugin` panel and `/reload-plugins` call.
+ */
+export declare function pluginInventory(deps: Omit<ClaudeCompatDeps, "confirm" | "interactive">): PluginInventory;
 /** Whether pi's trust file exists yet (used only for messaging). */
 export declare function trustFileExists(agentDir: string): boolean;
 //# sourceMappingURL=claudeCompat.d.ts.map

package/dist/claudeCompat.js

@@ -32,11 +32,57 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmdirSyn
 import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { discoverClaudePlugins } from "./claudePlugins.js";
+import { pluginsHome, readLedger } from "./pluginStore.js";
 export const CLAUDE_COMPAT_DISABLE_ENV = "YAGNI_DISABLE_CLAUDE_COMPAT";
 /** Plugin `agents/` dirs for the extension's subagent discovery (delimiter-joined). */
 export const CLAUDE_AGENT_DIRS_ENV = "YAGNI_CLAUDE_AGENT_DIRS";
 /** `.claude/rules` dirs for the extension's rules injection (delimiter-joined). */
 export const CLAUDE_RULES_DIRS_ENV = "YAGNI_CLAUDE_RULES_DIRS";
+/**
+ * Plugin MCP servers for the extension's MCP client: a JSON array of
+ * `{ plugin, sourcePath, gated, servers }`. `${CLAUDE_PLUGIN_ROOT}` is already
+ * expanded to the plugin's install dir; other `${VAR}` references are left for
+ * the extension's normal env expansion. `gated` marks servers that came from
+ * repo config (repo marketplace, project-scope `enabledPlugins`) and must pass
+ * the same approval the repo's `.mcp.json` would.
+ */
+export const CLAUDE_PLUGIN_MCP_ENV = "YAGNI_CLAUDE_PLUGIN_MCP";
+/**
+ * `name@marketplace` keys of the plugins wired at launch (delimiter-joined).
+ * `/reload-plugins` diffs a fresh inventory against this baseline: pi already
+ * holds the launch-time plugins through argv, so only newer ones need the
+ * extension's `resources_discover` contribution.
+ */
+export const CLAUDE_PLUGIN_KEYS_ENV = "YAGNI_CLAUDE_PLUGIN_KEYS";
+const PLUGIN_ROOT_VAR = "${CLAUDE_PLUGIN_ROOT}";
+function expandPluginRoot(value, root) {
+    if (typeof value === "string")
+        return value.split(PLUGIN_ROOT_VAR).join(root);
+    if (Array.isArray(value))
+        return value.map((v) => expandPluginRoot(v, root));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = expandPluginRoot(v, root);
+        return out;
+    }
+    return value;
+}
+/** The MCP payload entries for a set of plugins (those without servers are skipped). */
+export function pluginMcpEntries(plugins, gated) {
+    const out = [];
+    for (const plugin of plugins) {
+        if (!plugin.mcp)
+            continue;
+        out.push({
+            plugin: plugin.key,
+            sourcePath: plugin.mcp.sourcePath,
+            gated,
+            servers: expandPluginRoot(plugin.mcp.servers, plugin.root),
+        });
+    }
+    return out;
+}
 function dirsToArgv(dirs) {
     const argv = [];
     if (dirs.skills)
@@ -60,7 +106,8 @@ export function decideClaudeCompat(probe) {
     const projectArgv = [...dirsToArgv(probe.project), ...pluginsToArgv(probe.projectPlugins)];
     const projectAgentDirs = probe.projectPlugins.flatMap((p) => p.agentDirs);
     const projectRulesDirs = probe.project.rules ? [probe.project.rules] : [];
-    const hasProjectContent = projectArgv.length > 0 || projectAgentDirs.length > 0 || projectRulesDirs.length > 0;
+    const projectMcp = pluginMcpEntries(probe.projectPlugins, true);
+    const hasProjectContent = projectArgv.length > 0 || projectAgentDirs.length > 0 || projectRulesDirs.length > 0 || projectMcp.length > 0;
     return {
         userArgv: [...dirsToArgv(probe.user), ...pluginsToArgv(probe.userPlugins)],
         projectArgv,
@@ -68,6 +115,8 @@ export function decideClaudeCompat(probe) {
         projectAgentDirs,
         userRulesDirs: probe.user.rules ? [probe.user.rules] : [],
         projectRulesDirs,
+        userMcp: pluginMcpEntries(probe.userPlugins, false),
+        projectMcp,
         needsPrompt: probe.interactive && hasProjectContent && probe.projectTrust === null,
     };
 }
@@ -210,7 +259,11 @@ export async function claudeCompatArgs(deps) {
     const projectTrust = readTrustDecision(deps.agentDir, deps.cwd);
     let plugins;
     try {
-        plugins = discoverClaudePlugins({ cwd: deps.cwd, homeDir: home });
+        plugins = discoverClaudePlugins({
+            cwd: deps.cwd,
+            homeDir: home,
+            yagniLedger: readLedger(pluginsHome(env, home)),
+        });
     }
     catch {
         plugins = { user: [], project: [] };
@@ -246,13 +299,67 @@ export async function claudeCompatArgs(deps) {
         ...decision.userRulesDirs,
         ...(trusted === true ? decision.projectRulesDirs : []),
     ];
+    const mcpEntries = [
+        ...decision.userMcp,
+        ...(trusted === true ? decision.projectMcp : []),
+    ];
+    const loadedKeys = [
+        ...plugins.user.map((p) => p.key),
+        ...(trusted === true ? plugins.project.map((p) => p.key) : []),
+    ];
     const extraEnv = {};
     if (agentDirs.length > 0)
         extraEnv[CLAUDE_AGENT_DIRS_ENV] = agentDirs.join(delimiter);
     if (rulesDirs.length > 0)
         extraEnv[CLAUDE_RULES_DIRS_ENV] = rulesDirs.join(delimiter);
+    if (mcpEntries.length > 0)
+        extraEnv[CLAUDE_PLUGIN_MCP_ENV] = JSON.stringify(mcpEntries);
+    if (loadedKeys.length > 0)
+        extraEnv[CLAUDE_PLUGIN_KEYS_ENV] = loadedKeys.join(delimiter);
     return { argv, env: extraEnv };
 }
+function toInventory(plugin, gated) {
+    return {
+        key: plugin.key,
+        name: plugin.name,
+        origin: plugin.origin,
+        version: plugin.version,
+        root: plugin.root,
+        gated,
+        skillPaths: plugin.skillPaths,
+        commandPaths: plugin.commandPaths,
+        agentDirs: plugin.agentDirs,
+        mcpServers: plugin.mcp ? Object.keys(plugin.mcp.servers) : [],
+        unsupported: plugin.unsupported,
+    };
+}
+/**
+ * The plugin inventory a launch from `cwd` would wire, computed without
+ * prompting: the user's own plugins always, repo-sourced ones only once the
+ * folder is trusted. Backs `yagni plugin inventory --json`, which the
+ * in-session `/plugin` panel and `/reload-plugins` call.
+ */
+export function pluginInventory(deps) {
+    const env = deps.env ?? process.env;
+    if (compatDisabled(env))
+        return { plugins: [], mcp: [], pendingTrust: [], agentDirs: [] };
+    const home = deps.homeDir ?? homedir();
+    const trusted = readTrustDecision(deps.agentDir, deps.cwd);
+    let plugins;
+    try {
+        plugins = discoverClaudePlugins({ cwd: deps.cwd, homeDir: home, yagniLedger: readLedger(pluginsHome(env, home)) });
+    }
+    catch {
+        plugins = { user: [], project: [] };
+    }
+    const project = trusted === true ? plugins.project : [];
+    return {
+        plugins: [...plugins.user.map((p) => toInventory(p, false)), ...project.map((p) => toInventory(p, true))],
+        mcp: [...pluginMcpEntries(plugins.user, false), ...pluginMcpEntries(project, true)],
+        pendingTrust: trusted === true ? [] : plugins.project.map((p) => p.key),
+        agentDirs: [...plugins.user, ...project].flatMap((p) => p.agentDirs),
+    };
+}
 /** Whether pi's trust file exists yet (used only for messaging). */
 export function trustFileExists(agentDir) {
     return existsSync(trustPath(agentDir));

package/dist/claudePlugins.d.ts

@@ -17,10 +17,19 @@
  *    relative-path source loads on the project side, unless explicitly
  *    disabled via `enabledPlugins`.
  *
- * Deliberately NOT here: network installation of any kind, plugin hooks, MCP
- * servers (standard MCP support lives in `src/mcpCommand.ts` + the extension's
- * `mcp/` module — see `yagni mcp --help`), LSP servers, themes, output styles.
- * Discovery is read-only.
+ * Three sources, first wins on the same `name@marketplace`:
+ *
+ * 0. YAGNI's own ledger (`~/.yagni-code/plugins`, written by `yagni plugin`;
+ *    see pluginStore.ts) — handed in by the caller as `yagniLedger`.
+ * 1. Claude Code's ledger + `enabledPlugins` (mirrored read-only).
+ * 2. The repo's own `.claude-plugin/marketplace.json`.
+ *
+ * Plugin MCP servers (`.mcp.json` at the plugin root, or the manifest's
+ * `mcpServers`) are collected here and bridged by the launcher into the
+ * extension's MCP client (see claudeCompat.ts). Deliberately NOT here:
+ * network installation (that is pluginStore.ts), plugin hooks, LSP servers,
+ * themes, output styles — those are reported as `unsupported` so `yagni
+ * plugin list` can say so. Discovery is read-only.
  *
  * Everything is fail-soft: malformed JSON, missing dirs, or hostile path
  * entries degrade to "that plugin absent" — never a failed launch. Path
@@ -28,9 +37,21 @@
  * inside the expected root) so a malicious `source` or component override
  * cannot reach outside its repo/plugin.
  */
+import type { PluginLedger } from "./pluginStore.js";
+export type PluginOrigin = "yagni" | "claude-code" | "repo-marketplace";
+export interface PluginMcp {
+    /** File the servers came from (plugin `.mcp.json` or `plugin.json`). */
+    sourcePath: string;
+    /** Raw `mcpServers` map; validated by the extension, `${CLAUDE_PLUGIN_ROOT}` expanded by the launcher. */
+    servers: Record<string, unknown>;
+}
 export interface PluginAssets {
     /** The plugin's name (marketplace-entry name — the `enabledPlugins` key half). */
     name: string;
+    /** `name@marketplace` when the marketplace is known; else the bare name. */
+    key: string;
+    origin: PluginOrigin;
+    version: string | null;
     /** Absolute plugin root directory. */
     root: string;
     /** Dirs (or a lone root SKILL.md file) for pi `--skill`. */
@@ -39,6 +60,14 @@ export interface PluginAssets {
     commandPaths: string[];
     /** Dirs of Claude Code-format agent markdown for subagent discovery. */
     agentDirs: string[];
+    mcp: PluginMcp | null;
+    /** Component kinds present in the plugin that YAGNI Code does not bridge. */
+    unsupported: string[];
+}
+export interface PluginMeta {
+    key?: string;
+    origin?: PluginOrigin;
+    version?: string | null;
 }
 export interface DiscoveredClaudePlugins {
     /** Enabled via the user's own `~/.claude` config; loads without ceremony. */
@@ -71,9 +100,18 @@ export interface EnableState {
 export declare function readEnabledPlugins(cwd: string, homeDir: string): Map<string, EnableState>;
 /** `~/.claude/plugins/known_marketplaces.json` → marketplace name → checkout dir. */
 export declare function readKnownMarketplaces(homeDir: string): Map<string, string>;
+/**
+ * Names and versions from marketplace/plugin JSON become path segments under
+ * the plugin home (`cache/<mp>/<plugin>/<version>`), so they must be plain
+ * single segments: no separators, no `.`/`..`, nothing starting with `-`.
+ */
+export declare const SAFE_SEGMENT: RegExp;
+export declare function isSafeSegment(value: unknown): value is string;
 export interface MarketplaceEntry {
     name: string;
     source: unknown;
+    version?: string;
+    description?: string;
 }
 export interface Marketplace {
     name: string;
@@ -98,10 +136,12 @@ export declare function resolveLocalPluginRoot(mp: Marketplace, entry: Marketpla
  * discovery reads whole dirs), root `SKILL.md` fallback. Null when the plugin
  * has nothing we can bridge.
  */
-export declare function pluginAssets(root: string, name: string): PluginAssets | null;
+export declare function pluginAssets(root: string, name: string, meta?: PluginMeta): PluginAssets | null;
 export interface DiscoverPluginsDeps {
     cwd: string;
     homeDir: string;
+    /** YAGNI's own ledger (`readLedger` from pluginStore.ts); wins over the mirrored Claude Code state. */
+    yagniLedger?: PluginLedger;
 }
 /**
  * All locally-present Claude Code plugin content relevant to `cwd`, split by