@sayknow-cli/coding-agent 0.3.0 → 0.3.2

package/src/extensibility/skc-plugins/schema.ts

@@ -1,6 +1,43 @@
-import { SKC_PLUGIN_KIND, SkcPluginLoadError, type SkcPluginManifest, type SubskillFrontmatter } from "./types";
+import {
+	SKC_PLUGIN_KIND,
+	SKC_SUBSKILL_PARENT_AGENTS,
+	type SkcPluginAgentAppendixManifestEntry,
+	type SkcPluginAppendixManifestEntry,
+	type SkcPluginHookManifestEntry,
+	SkcPluginLoadError,
+	type SkcPluginManifest,
+	type SkcPluginMcpManifestEntry,
+	type SkcPluginMcpTransport,
+	type SkcPluginToolManifestEntry,
+	type SkcSubskillParentAgent,
+	type SubskillFrontmatter,
+} from "./types";
 
-const FORBIDDEN_MANIFEST_KEYS = ["skills", "slash-commands", "commands", "hooks", "mcp", "mcpServers", "agents"];
+/**
+ * Top-level surfaces that may never appear in a SKC plugin bundle: bundles may
+ * only EXTEND existing skills/agents, never register new top-level ones.
+ */
+const FORBIDDEN_MANIFEST_KEYS = ["skills", "slash-commands", "commands", "agents"];
+
+/**
+ * Ambiguous legacy aliases. `mcps` is the only canonical MCP key; these are
+ * rejected as `unsupported_surface` to avoid accidental legacy shape ambiguity.
+ */
+const UNSUPPORTED_ALIAS_KEYS = ["mcp", "mcpServers"];
+
+const KNOWN_MANIFEST_KEYS = new Set([
+	"kind",
+	"name",
+	"version",
+	"subskills",
+	"tools",
+	"hooks",
+	"mcps",
+	"system_appendix",
+	"agent-appendix",
+]);
+
+const MCP_TRANSPORTS: readonly SkcPluginMcpTransport[] = ["stdio", "http", "sse"];
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -16,14 +53,194 @@ function requireNonEmptyString(value: unknown, field: string, filePath: string):
 	return value;
 }
 
-function requireStringArray(value: unknown, field: string, manifestPath: string): string[] {
+function manifestString(value: unknown, field: string, manifestPath: string): string {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new SkcPluginLoadError(
+			"invalid_manifest",
+			`Invalid SKC plugin manifest at ${manifestPath}: ${field} must be a non-empty string`,
+		);
+	}
+	return value;
+}
+
+function optionalStringArray(value: unknown, field: string, manifestPath: string): string[] {
+	if (value === undefined) return [];
 	if (!Array.isArray(value) || !value.every(item => typeof item === "string")) {
 		throw new SkcPluginLoadError(
 			"invalid_manifest",
 			`Invalid SKC plugin manifest at ${manifestPath}: ${field} must be a string array`,
 		);
 	}
-	return [...value];
+	return [...(value as string[])];
+}
+
+function optionalArray(value: unknown, field: string, manifestPath: string): unknown[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) {
+		throw new SkcPluginLoadError(
+			"invalid_manifest",
+			`Invalid SKC plugin manifest at ${manifestPath}: ${field} must be an array`,
+		);
+	}
+	return value;
+}
+
+function deriveToolName(toolPath: string): string {
+	const base = toolPath.split("/").pop() ?? toolPath;
+	return base.replace(/\.[^.]+$/, "");
+}
+
+function parseTools(value: unknown, manifestPath: string): SkcPluginToolManifestEntry[] {
+	const raw = optionalArray(value, "tools", manifestPath);
+	return raw.map((entry, index) => {
+		// Legacy string shorthand: subskill-scoped tool path only.
+		if (typeof entry === "string") {
+			if (entry.trim().length === 0) {
+				throw new SkcPluginLoadError(
+					"invalid_manifest",
+					`Invalid SKC plugin manifest at ${manifestPath}: tools[${index}] must be a non-empty path`,
+				);
+			}
+			return { name: deriveToolName(entry), path: entry, surface: "subskill" };
+		}
+		if (!isRecord(entry)) {
+			throw new SkcPluginLoadError(
+				"invalid_manifest",
+				`Invalid SKC plugin manifest at ${manifestPath}: tools[${index}] must be a string or object`,
+			);
+		}
+		const name = manifestString(entry.name, `tools[${index}].name`, manifestPath);
+		const path = manifestString(entry.path, `tools[${index}].path`, manifestPath);
+		const description =
+			entry.description === undefined
+				? undefined
+				: manifestString(entry.description, `tools[${index}].description`, manifestPath);
+		const sha256 =
+			entry.sha256 === undefined ? undefined : manifestString(entry.sha256, `tools[${index}].sha256`, manifestPath);
+		return { name, path, description, sha256, surface: "always-on" };
+	});
+}
+
+function parseHooks(value: unknown, manifestPath: string): SkcPluginHookManifestEntry[] {
+	const raw = optionalArray(value, "hooks", manifestPath);
+	return raw.map((entry, index) => {
+		if (!isRecord(entry)) {
+			throw new SkcPluginLoadError(
+				"invalid_manifest",
+				`Invalid SKC plugin manifest at ${manifestPath}: hooks[${index}] must be an object`,
+			);
+		}
+		const name = manifestString(entry.name, `hooks[${index}].name`, manifestPath);
+		const event = manifestString(entry.event, `hooks[${index}].event`, manifestPath);
+		const path = manifestString(entry.path, `hooks[${index}].path`, manifestPath);
+		const target =
+			entry.target === undefined ? undefined : manifestString(entry.target, `hooks[${index}].target`, manifestPath);
+		let phase: "before" | "after" | undefined;
+		if (entry.phase !== undefined) {
+			if (entry.phase !== "before" && entry.phase !== "after") {
+				throw new SkcPluginLoadError(
+					"invalid_manifest",
+					`Invalid SKC plugin manifest at ${manifestPath}: hooks[${index}].phase must be "before" or "after"`,
+				);
+			}
+			phase = entry.phase;
+		}
+		const sha256 =
+			entry.sha256 === undefined ? undefined : manifestString(entry.sha256, `hooks[${index}].sha256`, manifestPath);
+		return { name, event, target, phase, path, sha256 };
+	});
+}
+
+function parseMcps(value: unknown, manifestPath: string): SkcPluginMcpManifestEntry[] {
+	const raw = optionalArray(value, "mcps", manifestPath);
+	return raw.map((entry, index) => {
+		if (!isRecord(entry)) {
+			throw new SkcPluginLoadError(
+				"invalid_manifest",
+				`Invalid SKC plugin manifest at ${manifestPath}: mcps[${index}] must be an object`,
+			);
+		}
+		const name = manifestString(entry.name, `mcps[${index}].name`, manifestPath);
+		const transport = entry.transport;
+		if (typeof transport !== "string" || !MCP_TRANSPORTS.includes(transport as SkcPluginMcpTransport)) {
+			throw new SkcPluginLoadError(
+				"invalid_manifest",
+				`Invalid SKC plugin manifest at ${manifestPath}: mcps[${index}].transport must be one of ${MCP_TRANSPORTS.join(", ")}`,
+			);
+		}
+		const command =
+			entry.command === undefined
+				? undefined
+				: manifestString(entry.command, `mcps[${index}].command`, manifestPath);
+		const url = entry.url === undefined ? undefined : manifestString(entry.url, `mcps[${index}].url`, manifestPath);
+		const cwd = entry.cwd === undefined ? undefined : manifestString(entry.cwd, `mcps[${index}].cwd`, manifestPath);
+		let args: string[] | undefined;
+		if (entry.args !== undefined) {
+			if (!Array.isArray(entry.args) || !entry.args.every(item => typeof item === "string")) {
+				throw new SkcPluginLoadError(
+					"invalid_manifest",
+					`Invalid SKC plugin manifest at ${manifestPath}: mcps[${index}].args must be a string array`,
+				);
+			}
+			args = [...(entry.args as string[])];
+		}
+		let headers: Record<string, string> | undefined;
+		if (entry.headers !== undefined) {
+			if (!isRecord(entry.headers) || !Object.values(entry.headers).every(v => typeof v === "string")) {
+				throw new SkcPluginLoadError(
+					"invalid_manifest",
+					`Invalid SKC plugin manifest at ${manifestPath}: mcps[${index}].headers must be a string map`,
+				);
+			}
+			headers = { ...(entry.headers as Record<string, string>) };
+		}
+		const sha256 =
+			entry.sha256 === undefined ? undefined : manifestString(entry.sha256, `mcps[${index}].sha256`, manifestPath);
+		return { name, transport: transport as SkcPluginMcpTransport, command, args, cwd, url, headers, sha256 };
+	});
+}
+
+function parseAppendixEntry(entry: unknown, field: string, manifestPath: string): SkcPluginAppendixManifestEntry {
+	if (!isRecord(entry)) {
+		throw new SkcPluginLoadError(
+			"invalid_manifest",
+			`Invalid SKC plugin manifest at ${manifestPath}: ${field} must be an object`,
+		);
+	}
+	const name = manifestString(entry.name, `${field}.name`, manifestPath);
+	const path = entry.path === undefined ? undefined : manifestString(entry.path, `${field}.path`, manifestPath);
+	// Content may be empty/whitespace here; the compiler enforces non-empty and
+	// maps emptiness to invalid_appendix (not invalid_manifest).
+	if (entry.content !== undefined && typeof entry.content !== "string") {
+		throw new SkcPluginLoadError(
+			"invalid_manifest",
+			`Invalid SKC plugin manifest at ${manifestPath}: ${field}.content must be a string`,
+		);
+	}
+	const content = entry.content as string | undefined;
+	const sha256 =
+		entry.sha256 === undefined ? undefined : manifestString(entry.sha256, `${field}.sha256`, manifestPath);
+	return { name, path, content, sha256 };
+}
+
+function parseSystemAppendix(value: unknown, manifestPath: string): SkcPluginAppendixManifestEntry[] {
+	const raw = optionalArray(value, "system_appendix", manifestPath);
+	return raw.map((entry, index) => parseAppendixEntry(entry, `system_appendix[${index}]`, manifestPath));
+}
+
+function parseAgentAppendix(value: unknown, manifestPath: string): SkcPluginAgentAppendixManifestEntry[] {
+	const raw = optionalArray(value, "agent-appendix", manifestPath);
+	return raw.map((entry, index) => {
+		const base = parseAppendixEntry(entry, `agent-appendix[${index}]`, manifestPath);
+		const agent = (entry as Record<string, unknown>).agent;
+		if (typeof agent !== "string" || !SKC_SUBSKILL_PARENT_AGENTS.includes(agent as SkcSubskillParentAgent)) {
+			throw new SkcPluginLoadError(
+				"invalid_parent",
+				`Invalid SKC plugin manifest at ${manifestPath}: agent-appendix[${index}].agent must be one of ${SKC_SUBSKILL_PARENT_AGENTS.join(", ")}`,
+			);
+		}
+		return { ...base, agent: agent as SkcSubskillParentAgent };
+	});
 }
 
 export function parseManifest(raw: unknown, manifestPath: string): SkcPluginManifest {
@@ -40,31 +257,44 @@ export function parseManifest(raw: unknown, manifestPath: string): SkcPluginMani
 		}
 	}
 
+	for (const key of UNSUPPORTED_ALIAS_KEYS) {
+		if (Object.hasOwn(raw, key)) {
+			throw new SkcPluginLoadError(
+				"unsupported_surface",
+				`Unsupported SKC plugin surface in ${manifestPath}: ${key} (use the canonical "mcps" key)`,
+			);
+		}
+	}
+
+	for (const key of Object.keys(raw)) {
+		if (!KNOWN_MANIFEST_KEYS.has(key)) {
+			throw new SkcPluginLoadError(
+				"unsupported_surface",
+				`Unsupported SKC plugin surface in ${manifestPath}: ${key}`,
+			);
+		}
+	}
+
 	if (raw.kind !== SKC_PLUGIN_KIND) {
 		throw new SkcPluginLoadError(
 			"invalid_kind",
 			`Invalid SKC plugin kind in ${manifestPath}: expected ${SKC_PLUGIN_KIND}`,
 		);
 	}
-	if (typeof raw.name !== "string" || raw.name.trim().length === 0) {
-		throw new SkcPluginLoadError(
-			"invalid_manifest",
-			`Invalid SKC plugin manifest at ${manifestPath}: name must be a non-empty string`,
-		);
-	}
-	if (typeof raw.version !== "string" || raw.version.trim().length === 0) {
-		throw new SkcPluginLoadError(
-			"invalid_manifest",
-			`Invalid SKC plugin manifest at ${manifestPath}: version must be a non-empty string`,
-		);
-	}
+
+	const name = manifestString(raw.name, "name", manifestPath);
+	const version = manifestString(raw.version, "version", manifestPath);
 
 	return {
-		name: raw.name,
-		version: raw.version,
+		name,
+		version,
 		kind: SKC_PLUGIN_KIND,
-		subskills: requireStringArray(raw.subskills, "subskills", manifestPath),
-		tools: requireStringArray(raw.tools, "tools", manifestPath),
+		subskills: optionalStringArray(raw.subskills, "subskills", manifestPath),
+		tools: parseTools(raw.tools, manifestPath),
+		hooks: parseHooks(raw.hooks, manifestPath),
+		mcps: parseMcps(raw.mcps, manifestPath),
+		systemAppendix: parseSystemAppendix(raw.system_appendix, manifestPath),
+		agentAppendix: parseAgentAppendix(raw["agent-appendix"], manifestPath),
 	};
 }
 

package/src/extensibility/skc-plugins/session-validation.ts

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { SkcPluginLoadErrorCode, SkcPluginRegistryEntry } from "./types";
+
+/**
+ * Session-start validation: the registry is the collision authority. Capability
+ * provider output is supplied as EVIDENCE only; plugin surfaces are never
+ * resolved by capability first-wins. Offending surfaces are quarantined
+ * fail-closed with a stable error code rather than silently shadowed.
+ */
+
+export interface SessionCapabilityEvidence {
+	/** Built-in + provider tool names already present before plugin insertion. */
+	toolNames?: Iterable<string>;
+	/** Non-plugin MCP server names from providers/built-ins. */
+	mcpNames?: Iterable<string>;
+	/** Non-plugin hook keys (event:phase:target:name) from providers/built-ins. */
+	hookKeys?: Iterable<string>;
+	/** Existing appendix extension ids already present. */
+	appendixIds?: Iterable<string>;
+}
+
+export interface SessionQuarantine {
+	plugin: string;
+	surfaceId: string;
+	code: SkcPluginLoadErrorCode;
+	message: string;
+}
+
+export interface SessionValidationResult {
+	/** Registry entries (enabled, non-quarantined) whose surfaces may activate. */
+	active: SkcPluginRegistryEntry[];
+	/** Per-surface quarantine records (fail-closed). */
+	quarantine: SessionQuarantine[];
+}
+
+function sha256(buf: Buffer): string {
+	return createHash("sha256").update(buf).digest("hex");
+}
+
+/**
+ * Re-verify that the installed files still match the registry's recorded hashes.
+ * Drift (manual edits, partial writes) quarantines the whole plugin with
+ * runtime_mismatch.
+ */
+export async function verifyEntryHashes(entry: SkcPluginRegistryEntry): Promise<SessionQuarantine | null> {
+	for (const file of entry.copiedFiles) {
+		const abs = path.join(entry.pluginRoot, file.relativePath);
+		let buf: Buffer;
+		try {
+			buf = await fs.readFile(abs);
+		} catch {
+			return {
+				plugin: entry.name,
+				surfaceId: `plugin:${entry.name}`,
+				code: "runtime_mismatch",
+				message: `Installed file missing: ${file.relativePath}`,
+			};
+		}
+		if (sha256(buf) !== file.sha256) {
+			return {
+				plugin: entry.name,
+				surfaceId: `plugin:${entry.name}`,
+				code: "runtime_mismatch",
+				message: `Installed file hash drift: ${file.relativePath}`,
+			};
+		}
+	}
+	return null;
+}
+
+function activeSurfaceIds(entry: SkcPluginRegistryEntry): {
+	tools: { id: string; name: string }[];
+	mcps: { id: string; name: string }[];
+	hooks: { id: string }[];
+	appendices: { id: string }[];
+} {
+	const disabled = new Set(entry.disabledSurfaceIds);
+	return {
+		tools: entry.surfaces.tools
+			.filter(t => !disabled.has(t.extensionId))
+			.map(t => ({ id: t.extensionId, name: t.name })),
+		mcps: entry.surfaces.mcps
+			.filter(m => !disabled.has(m.extensionId))
+			.map(m => ({ id: m.extensionId, name: m.name })),
+		hooks: entry.surfaces.hooks.filter(h => !disabled.has(h.extensionId)).map(h => ({ id: h.extensionId })),
+		appendices: [...entry.surfaces.systemAppendices, ...entry.surfaces.agentAppendices]
+			.filter(a => !disabled.has(a.extensionId))
+			.map(a => ({ id: a.extensionId })),
+	};
+}
+
+/**
+ * Validate the effective installed registry against the current capability
+ * universe (evidence) and across plugins. Returns the entries that may activate
+ * plus per-surface quarantine records. Disabled entries/surfaces are skipped
+ * (not an error).
+ */
+export function validateSessionBundles(
+	entries: readonly SkcPluginRegistryEntry[],
+	evidence: SessionCapabilityEvidence = {},
+	preQuarantined: readonly SessionQuarantine[] = [],
+): SessionValidationResult {
+	const quarantine: SessionQuarantine[] = [...preQuarantined];
+	const quarantinedPlugins = new Set(preQuarantined.map(q => q.plugin));
+
+	const seenTools = new Set<string>(evidence.toolNames ?? []);
+	const seenMcps = new Set<string>(evidence.mcpNames ?? []);
+	const seenHooks = new Set<string>(evidence.hookKeys ?? []);
+	const seenAppendices = new Set<string>(evidence.appendixIds ?? []);
+
+	const active: SkcPluginRegistryEntry[] = [];
+	for (const entry of entries) {
+		if (!entry.enabled) continue; // user-disabled, not an error
+		if (quarantinedPlugins.has(entry.name)) continue;
+		const surfaces = activeSurfaceIds(entry);
+		let collided = false;
+		const recordCollision = (surfaceId: string, what: string): void => {
+			collided = true;
+			quarantine.push({
+				plugin: entry.name,
+				surfaceId,
+				code: "session_collision",
+				message: `${what} collides with an existing capability/plugin; fail-closed (no shadowing)`,
+			});
+		};
+		for (const t of surfaces.tools) if (seenTools.has(t.name)) recordCollision(t.id, `tool "${t.name}"`);
+		for (const m of surfaces.mcps) if (seenMcps.has(m.name)) recordCollision(m.id, `mcp "${m.name}"`);
+		for (const h of surfaces.hooks) if (seenHooks.has(h.id)) recordCollision(h.id, `hook "${h.id}"`);
+		for (const a of surfaces.appendices) if (seenAppendices.has(a.id)) recordCollision(a.id, `appendix "${a.id}"`);
+
+		if (collided) {
+			// Fail-closed for the whole plugin entry so partial activation cannot
+			// leave a half-applied bundle.
+			continue;
+		}
+		// Reserve this plugin's surfaces so a later plugin colliding with it is
+		// also caught (deterministic order => earlier plugin wins reservation).
+		for (const t of surfaces.tools) seenTools.add(t.name);
+		for (const m of surfaces.mcps) seenMcps.add(m.name);
+		for (const h of surfaces.hooks) seenHooks.add(h.id);
+		for (const a of surfaces.appendices) seenAppendices.add(a.id);
+		active.push(entry);
+	}
+	return { active, quarantine };
+}

package/src/extensibility/skc-plugins/types.ts

@@ -19,12 +19,62 @@ export const SKC_AGENT_SUBSKILL_PHASES: Record<SkcSubskillParentAgent, string[]>
 	critic: ["prompt"],
 };
 
+export interface SkcPluginToolManifestEntry {
+	name: string;
+	path: string;
+	description?: string;
+	sha256?: string;
+	/**
+	 * "always-on" object entries are activated for the whole session; legacy
+	 * string shorthand stays "subskill"-scoped and is only attached to subskill
+	 * bindings (never registered as an always-on tool surface).
+	 */
+	surface: "subskill" | "always-on";
+}
+
+export interface SkcPluginHookManifestEntry {
+	name: string;
+	event: string;
+	target?: string;
+	phase?: "before" | "after";
+	path: string;
+	sha256?: string;
+}
+
+export type SkcPluginMcpTransport = "stdio" | "http" | "sse";
+
+export interface SkcPluginMcpManifestEntry {
+	name: string;
+	transport: SkcPluginMcpTransport;
+	command?: string;
+	args?: string[];
+	cwd?: string;
+	url?: string;
+	headers?: Record<string, string>;
+	sha256?: string;
+}
+
+export interface SkcPluginAppendixManifestEntry {
+	name: string;
+	path?: string;
+	content?: string;
+	sha256?: string;
+}
+
+export interface SkcPluginAgentAppendixManifestEntry extends SkcPluginAppendixManifestEntry {
+	agent: SkcSubskillParentAgent;
+}
+
 export interface SkcPluginManifest {
 	name: string;
 	version: string;
 	kind: "sayknow-cli-plugin";
 	subskills: string[];
-	tools: string[];
+	tools: SkcPluginToolManifestEntry[];
+	hooks: SkcPluginHookManifestEntry[];
+	mcps: SkcPluginMcpManifestEntry[];
+	systemAppendix: SkcPluginAppendixManifestEntry[];
+	agentAppendix: SkcPluginAgentAppendixManifestEntry[];
 }
 
 export interface SubskillFrontmatter {
@@ -76,15 +126,33 @@ export interface LoadedSkcPlugin {
 }
 
 export type SkcPluginLoadErrorCode =
+	// Parse-time
 	| "forbidden_surface"
 	| "invalid_manifest"
+	| "invalid_kind"
+	| "unsupported_surface"
+	// Compile-time
 	| "invalid_frontmatter"
 	| "invalid_parent"
 	| "invalid_phase"
+	| "missing_file"
+	| "hash_mismatch"
+	| "invalid_appendix"
+	| "invalid_hook"
+	| "invalid_mcp"
+	// Install-time
 	| "duplicate_arg"
 	| "duplicate_parent_phase"
-	| "missing_file"
-	| "invalid_kind";
+	| "duplicate_tool"
+	| "duplicate_hook"
+	| "duplicate_mcp"
+	| "duplicate_appendix"
+	| "security_policy"
+	| "install_conflict"
+	// Session-start / runtime
+	| "session_collision"
+	| "runtime_mismatch"
+	| "quarantined_surface";
 
 export class SkcPluginLoadError extends Error {
 	readonly code: SkcPluginLoadErrorCode;
@@ -95,3 +163,131 @@ export class SkcPluginLoadError extends Error {
 		this.code = code;
 	}
 }
+
+export type SkcPluginScope = "user" | "project";
+
+export type SkcPluginSourceKind = "path" | "git" | "tarball";
+
+export interface SkcPluginCopiedFile {
+	relativePath: string;
+	sha256: string;
+	bytes: number;
+}
+
+export interface NormalizedSubskillSurface {
+	extensionId: string;
+	name: string;
+	description: string;
+	parent: string;
+	phase: string;
+	activationArg: string;
+	relativePath: string;
+	sha256: string;
+}
+
+export interface NormalizedToolSurface {
+	extensionId: string;
+	name: string;
+	relativePath: string;
+	sha256: string;
+	description?: string;
+}
+
+export interface NormalizedHookSurface {
+	extensionId: string;
+	name: string;
+	event: string;
+	target?: string;
+	phase?: "before" | "after";
+	relativePath: string;
+	sha256: string;
+}
+
+export interface NormalizedMcpSurface {
+	extensionId: string;
+	name: string;
+	transport: SkcPluginMcpTransport;
+	configHash: string;
+	config: SkcPluginMcpManifestEntry;
+}
+
+export interface NormalizedAppendixSurface {
+	extensionId: string;
+	name: string;
+	relativePath?: string;
+	/** Inline appendix body (when the manifest used `content` instead of `path`). */
+	content?: string;
+	contentHash: string;
+	bytes: number;
+}
+
+export interface NormalizedAgentAppendixSurface extends NormalizedAppendixSurface {
+	agent: SkcSubskillParentAgent;
+}
+
+export interface NormalizedSkcPluginSurfaces {
+	subskills: NormalizedSubskillSurface[];
+	tools: NormalizedToolSurface[];
+	hooks: NormalizedHookSurface[];
+	mcps: NormalizedMcpSurface[];
+	systemAppendices: NormalizedAppendixSurface[];
+	agentAppendices: NormalizedAgentAppendixSurface[];
+}
+
+/**
+ * Result of the pure compile step. Computed from manifest, frontmatter, and
+ * declared files read as bytes only — never by importing plugin code.
+ */
+export interface NormalizedSkcPluginBundle {
+	name: string;
+	version: string;
+	root: string;
+	manifestPath: string;
+	manifestHash: string;
+	surfaces: NormalizedSkcPluginSurfaces;
+	files: SkcPluginCopiedFile[];
+}
+
+export interface SkcPluginQuarantineEntry {
+	surfaceId: string;
+	code: SkcPluginLoadErrorCode;
+	message: string;
+	detectedAt: string;
+}
+
+export interface SkcPluginRegistrySource {
+	kind: SkcPluginSourceKind;
+	uri: string;
+	ref?: string;
+	sha?: string;
+	resolvedAt: string;
+}
+
+export interface SkcPluginRegistryEntry {
+	name: string;
+	version: string;
+	scope: SkcPluginScope;
+	enabled: boolean;
+	pluginRoot: string;
+	manifestPath: string;
+	manifestHash: string;
+	source: SkcPluginRegistrySource;
+	installedAt: string;
+	updatedAt: string;
+	copiedFiles: SkcPluginCopiedFile[];
+	surfaces: NormalizedSkcPluginSurfaces;
+	disabledSurfaceIds: string[];
+	quarantine?: SkcPluginQuarantineEntry[];
+}
+
+export interface SkcPluginRegistry {
+	version: 1;
+	scope: SkcPluginScope;
+	plugins: SkcPluginRegistryEntry[];
+}
+
+/**
+ * Stable identifiers for plugin-contributed surfaces used by observability,
+ * disabledSurfaceIds, and quarantine bookkeeping.
+ */
+export type SkcPluginSurfaceExtensionId = string;