feat(plugins): expose activation plan reasons

[vincentkoc]

Summary

• add resolveManifestActivationPlan beside the existing ids-only activation planner API
• report explicit activation planner hints separately from manifest ownership fallback reasons
• clarify docs that activation is planner metadata, not lifecycle API, and document compatibility/deprecation policy

Validation

• pnpm test src/plugins/activation-planner.test.ts
• pnpm format:check src/plugins/activation-planner.ts src/plugins/activation-planner.test.ts src/plugins/manifest.ts docs/plugins/manifest.md docs/plugins/architecture.md docs/plugins/architecture-internals.md docs/plugins/sdk-migration.md
• pnpm test:contracts:plugins
• filtered pnpm tsgo:core check found no touched-file errors

Known failures

• pnpm check:changed fails in src/agents/openai-transport-stream.ts on existing OpenAI transport type errors (supportsStore, supportsReasoningEffort, etc.)
• pnpm build reaches build:plugin-sdk:dts and fails on the same unrelated OpenAI transport type errors

Notes

• AI-assisted: yes

[greptile-apps]

Greptile Summary

This PR introduces resolveManifestActivationPlan, a richer companion to the existing resolveManifestActivationPluginIds API that exposes per-plugin activation reasons, distinguishing explicit activation.* planner hints from manifest ownership fallbacks. The existing function is refactored to delegate to the new one, preserving backward compatibility, and accompanying docs + tests are updated throughout.

Confidence Score: 5/5

Safe to merge — additive API, backward-compatible delegation, and well-covered by tests.

The new resolveManifestActivationPlan function is purely additive. The refactored resolveManifestActivationPluginIds delegates cleanly to it and produces an identical sorted result. Logic for each trigger kind mirrors the old boolean checks and the exhaustiveness pattern is preserved. All remaining observations are P2 style suggestions.

No files require special attention.

_{Reviews (1): Last reviewed commit: "Merge branch 'main' into feat/plugin-act..." | Re-trigger Greptile}

[aisle-research-bot]

🔒 Aisle Security Analysis

We found 1 potential security issue(s) in this PR:

#	Severity	Title
1	🟡 Medium	Potential information disclosure: activation plan returns raw manifest registry diagnostics (includes local file paths and error details)

1. 🟡 Potential information disclosure: activation plan returns raw manifest registry diagnostics (includes local file paths and error details)

Property	Value
Severity	Medium
CWE	CWE-200
Location	src/plugins/activation-planner.ts:61-99

Description

resolveManifestActivationPlan() returns registry.diagnostics verbatim as part of the activation planning output. These diagnostics are populated while discovering/loading plugin manifests and may include sensitive internal metadata such as absolute/local filesystem paths (e.g., manifest path, package.json path, plugin source path) and detailed parse/validation errors.

If the activation plan object is ever surfaced to untrusted contexts (CLI output, UI, logs, API responses), this can leak internal directory layout and other environment details.

Vulnerable behavior:

return {
  trigger: params.trigger,
  pluginIds: [...new Set(entries.map((entry) => entry.pluginId))],
  entries,
  diagnostics: registry.diagnostics,
};

Diagnostics can contain paths and detailed error strings, for example:

diagnostics.push({
  level: "error",
  message: manifestRes.error,
  source: manifestRes.manifestPath,
});

Recommendation

Avoid returning raw diagnostics to callers by default. Options:

• Do not include diagnostics in the returned plan unless an explicit includeDiagnostics: true / debug flag is set.
• Redact/sanitize diagnostic fields before returning (e.g., strip/relativize paths, remove nested error details).

Example (gated + sanitized):

export function resolveManifestActivationPlan(params: ResolveManifestActivationPlanParams & { includeDiagnostics?: boolean }): PluginActivationPlan {
  ​// ...
  const diagnostics = params.includeDiagnostics
    ? registry.diagnostics.map(d => ({
        level: d.level,
        pluginId: d.pluginId,
        ​// omit/relativize path-like values
        source: d.source ? path.basename(d.source) : undefined,
        ​// ensure message does not include absolute paths (apply your redaction rules)
        message: redactPaths(d.message),
      }))
    : [];

  return { trigger: params.trigger, pluginIds, entries, diagnostics };
}

Also ensure any CLI/UI/API layer treats diagnostics as debug-only and never exposes them to untrusted users/tenants.

---

Analyzed PR: #70943 at commit 548e92a

_{Last updated on: 2026-04-24T05:09:22Z}