@gajae-code/coding-agent 0.7.3 → 0.7.5

package/src/extensibility/gjc-plugins/compiler.ts

@@ -0,0 +1,351 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { parseFrontmatter, pathIsWithin } from "@gajae-code/utils";
+import { resolveWithinRoot } from "./paths";
+import { parseManifest, parseSubskillFrontmatter } from "./schema";
+import {
+	GJC_PLUGIN_MANIFEST_FILENAME,
+	type GjcPluginAppendixManifestEntry,
+	GjcPluginLoadError,
+	type GjcPluginMcpManifestEntry,
+	type NormalizedAgentAppendixSurface,
+	type NormalizedAppendixSurface,
+	type NormalizedGjcPluginBundle,
+	type NormalizedGjcPluginSurfaces,
+	type NormalizedHookSurface,
+	type NormalizedMcpSurface,
+	type NormalizedSubskillSurface,
+	type NormalizedToolSurface,
+} from "./types";
+import { validateBinding } from "./validation";
+
+function sha256(bytes: Buffer | string): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * Stable surface extension-id builders. Kept here so install, runtime, and
+ * observability all derive identical ids.
+ */
+export const surfaceIds = {
+	tool: (name: string): string => `tool:${name}`,
+	hook: (event: string, phase: string | undefined, target: string | undefined, name: string): string =>
+		`hook:${event}:${phase ?? ""}:${target ?? ""}:${name}`,
+	mcp: (name: string): string => `mcp:${name}`,
+	systemAppendix: (plugin: string, name: string): string => `system-appendix:${plugin}:${name}`,
+	agentAppendix: (agent: string, plugin: string, name: string): string => `agent-appendix:${agent}:${plugin}:${name}`,
+	subskill: (parent: string, phase: string, activationArg: string): string =>
+		`subskill:${parent}:${phase}:${activationArg}`,
+} as const;
+
+async function readManifestJson(filePath: string): Promise<unknown> {
+	let text: string;
+	try {
+		text = await fs.readFile(filePath, "utf8");
+	} catch (error) {
+		throw new GjcPluginLoadError("missing_file", `Missing GJC plugin manifest at ${filePath}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+	try {
+		return JSON.parse(text) as unknown;
+	} catch (error) {
+		throw new GjcPluginLoadError("invalid_manifest", `Invalid GJC plugin manifest JSON at ${filePath}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+}
+
+/**
+ * Resolve a declared relative path, rejecting lexical escapes AND symlink
+ * escapes out of the plugin root. Never imports the file.
+ */
+async function resolveDeclaredFile(pluginRoot: string, rel: string): Promise<string> {
+	const resolved = resolveWithinRoot(pluginRoot, rel);
+	let real: string;
+	try {
+		real = await fs.realpath(resolved);
+	} catch (error) {
+		throw new GjcPluginLoadError("missing_file", `Missing GJC plugin file at ${resolved}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+	const realRoot = await fs.realpath(pluginRoot);
+	if (!pathIsWithin(realRoot, real)) {
+		throw new GjcPluginLoadError("security_policy", `GJC plugin file escapes root via symlink: ${rel}`);
+	}
+	return resolved;
+}
+
+async function hashFile(
+	absPath: string,
+	rel: string,
+	declaredSha?: string,
+): Promise<{ sha256: string; bytes: number }> {
+	let buf: Buffer;
+	try {
+		buf = await fs.readFile(absPath);
+	} catch (error) {
+		throw new GjcPluginLoadError("missing_file", `Missing GJC plugin file at ${absPath}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+	const digest = sha256(buf);
+	if (declaredSha !== undefined && declaredSha.toLowerCase() !== digest) {
+		throw new GjcPluginLoadError("hash_mismatch", `GJC plugin file hash mismatch for ${rel}`);
+	}
+	return { sha256: digest, bytes: buf.byteLength };
+}
+
+function mcpConfigHash(entry: GjcPluginMcpManifestEntry): string {
+	const canonical = JSON.stringify({
+		name: entry.name,
+		transport: entry.transport,
+		command: entry.command ?? null,
+		args: entry.args ?? null,
+		cwd: entry.cwd ?? null,
+		url: entry.url ?? null,
+		headers: entry.headers ?? null,
+	});
+	return sha256(canonical);
+}
+
+async function compileAppendix(
+	pluginRoot: string,
+	entry: GjcPluginAppendixManifestEntry,
+	field: string,
+	files: Map<string, { sha256: string; bytes: number }>,
+): Promise<{ contentHash: string; bytes: number; relativePath?: string; content?: string }> {
+	const hasPath = entry.path !== undefined;
+	const hasContent = entry.content !== undefined;
+	if (hasPath === hasContent) {
+		throw new GjcPluginLoadError(
+			"invalid_appendix",
+			`Invalid GJC plugin ${field}: exactly one of "path" or "content" is required`,
+		);
+	}
+	if (hasContent) {
+		const content = entry.content ?? "";
+		if (content.trim().length === 0) {
+			throw new GjcPluginLoadError("invalid_appendix", `Invalid GJC plugin ${field}: inline content is empty`);
+		}
+		const digest = sha256(content);
+		if (entry.sha256 !== undefined && entry.sha256.toLowerCase() !== digest) {
+			throw new GjcPluginLoadError("hash_mismatch", `GJC plugin ${field} content hash mismatch`);
+		}
+		return { contentHash: digest, bytes: Buffer.byteLength(content), content };
+	}
+	const rel = entry.path as string;
+	const abs = await resolveDeclaredFile(pluginRoot, rel);
+	const { sha256: digest, bytes } = await hashFile(abs, rel, entry.sha256);
+	if (bytes === 0) {
+		throw new GjcPluginLoadError("invalid_appendix", `Invalid GJC plugin ${field}: file is empty`);
+	}
+	files.set(rel, { sha256: digest, bytes });
+	return { contentHash: digest, bytes, relativePath: rel };
+}
+
+/**
+ * Pure compile step: reads only the manifest, subskill frontmatter, and
+ * declared files (as bytes for hashing/existence). It NEVER imports or executes
+ * plugin tool/hook code.
+ */
+export async function compileGjcPluginBundle(root: string): Promise<NormalizedGjcPluginBundle> {
+	const pluginRoot = path.resolve(root);
+	const manifestPath = path.join(pluginRoot, GJC_PLUGIN_MANIFEST_FILENAME);
+	const manifest = parseManifest(await readManifestJson(manifestPath), manifestPath);
+
+	const files = new Map<string, { sha256: string; bytes: number }>();
+
+	const subskills: NormalizedSubskillSurface[] = [];
+	for (const rel of manifest.subskills) {
+		const abs = await resolveDeclaredFile(pluginRoot, rel);
+		const { sha256: digest, bytes } = await hashFile(abs, rel);
+		files.set(rel, { sha256: digest, bytes });
+		let content: string;
+		try {
+			content = await fs.readFile(abs, "utf8");
+		} catch (error) {
+			throw new GjcPluginLoadError("missing_file", `Missing GJC sub-skill file at ${abs}`, {
+				cause: error instanceof Error ? error : undefined,
+			});
+		}
+		let parsed: { frontmatter: Record<string, unknown>; body: string };
+		try {
+			parsed = parseFrontmatter(content, { source: abs, level: "fatal" });
+		} catch (error) {
+			throw new GjcPluginLoadError("invalid_frontmatter", `Invalid GJC sub-skill frontmatter at ${abs}`, {
+				cause: error instanceof Error ? error : undefined,
+			});
+		}
+		const fm = parseSubskillFrontmatter(parsed.frontmatter, abs);
+		validateBinding(fm);
+		// Subskill-scoped frontmatter tools are hashed for copy-ownership and
+		// escape checks (the loader resolves these at runtime).
+		const fmTools = parsed.frontmatter.tools;
+		const fmToolPaths =
+			typeof fmTools === "string"
+				? [fmTools]
+				: Array.isArray(fmTools) && fmTools.every(t => typeof t === "string")
+					? (fmTools as string[])
+					: [];
+		for (const toolRel of fmToolPaths) {
+			if (toolRel.trim().length === 0) continue;
+			const toolAbs = await resolveDeclaredFile(pluginRoot, toolRel);
+			const { sha256: toolDigest, bytes: toolBytes } = await hashFile(toolAbs, toolRel);
+			files.set(toolRel, { sha256: toolDigest, bytes: toolBytes });
+		}
+		subskills.push({
+			extensionId: surfaceIds.subskill(fm.binds_to, fm.phase, fm.activation_arg),
+			name: fm.name,
+			description: fm.description,
+			parent: fm.binds_to,
+			phase: fm.phase,
+			activationArg: fm.activation_arg,
+			relativePath: rel,
+			sha256: digest,
+		});
+	}
+
+	// Every declared tool file is resolved/hashed for copy-ownership and escape
+	// checks, but only object-form ("always-on") tools become a session tool
+	// surface; legacy string shorthand stays subskill-scoped (loader-handled).
+	const tools: NormalizedToolSurface[] = [];
+	for (const tool of manifest.tools) {
+		const abs = await resolveDeclaredFile(pluginRoot, tool.path);
+		const { sha256: digest, bytes } = await hashFile(abs, tool.path, tool.sha256);
+		files.set(tool.path, { sha256: digest, bytes });
+		if (tool.surface !== "always-on") continue;
+		tools.push({
+			extensionId: surfaceIds.tool(tool.name),
+			name: tool.name,
+			relativePath: tool.path,
+			sha256: digest,
+			description: tool.description,
+		});
+	}
+
+	const hooks: NormalizedHookSurface[] = [];
+	for (const hook of manifest.hooks) {
+		// Path safety first: resolve/hash before semantic checks so traversal and
+		// missing-file failures take precedence over contract validation.
+		const abs = await resolveDeclaredFile(pluginRoot, hook.path);
+		const { sha256: digest, bytes } = await hashFile(abs, hook.path, hook.sha256);
+		files.set(hook.path, { sha256: digest, bytes });
+		// Minimal compile-time hook contract: tool_call hooks must name a target
+		// and a before/after phase so the constrained runner (M3/M4) can bind them.
+		if (hook.event === "tool_call") {
+			if (!hook.target) {
+				throw new GjcPluginLoadError("invalid_hook", `GJC plugin hook "${hook.name}": tool_call requires a target`);
+			}
+			if (!hook.phase) {
+				throw new GjcPluginLoadError(
+					"invalid_hook",
+					`GJC plugin hook "${hook.name}": tool_call requires a "before"/"after" phase`,
+				);
+			}
+		}
+		hooks.push({
+			extensionId: surfaceIds.hook(hook.event, hook.phase, hook.target, hook.name),
+			name: hook.name,
+			event: hook.event,
+			target: hook.target,
+			phase: hook.phase,
+			relativePath: hook.path,
+			sha256: digest,
+		});
+	}
+
+	const mcps: NormalizedMcpSurface[] = [];
+	for (const entry of manifest.mcps) {
+		// Minimal compile-time MCP contract: transport-specific endpoint must exist.
+		if (entry.transport === "stdio") {
+			if (!entry.command) {
+				throw new GjcPluginLoadError("invalid_mcp", `GJC plugin MCP "${entry.name}": stdio requires a command`);
+			}
+		} else if (!entry.url) {
+			throw new GjcPluginLoadError(
+				"invalid_mcp",
+				`GJC plugin MCP "${entry.name}": ${entry.transport} requires a url`,
+			);
+		}
+		// Hash bundled stdio script args (relative file paths) so the registry owns
+		// their copied-file boundary. Path/security failures must propagate, not be
+		// swallowed, so traversal/symlink-escape/missing bundled files fail compile.
+		for (const arg of entry.args ?? []) {
+			// Skip flags (e.g. "--port", "-v"); only treat clearly path-like args as
+			// bundled files subject to root confinement.
+			if (arg.startsWith("-")) continue;
+			if (!arg.startsWith(".") && !arg.includes("/")) continue;
+			const abs = await resolveDeclaredFile(pluginRoot, arg);
+			const { sha256: digest, bytes } = await hashFile(abs, arg, undefined);
+			files.set(arg, { sha256: digest, bytes });
+		}
+		mcps.push({
+			extensionId: surfaceIds.mcp(entry.name),
+			name: entry.name,
+			transport: entry.transport,
+			configHash: mcpConfigHash(entry),
+			config: entry,
+		});
+	}
+
+	const systemAppendices: NormalizedAppendixSurface[] = [];
+	for (const entry of manifest.systemAppendix) {
+		const compiled = await compileAppendix(pluginRoot, entry, `system_appendix "${entry.name}"`, files);
+		systemAppendices.push({
+			extensionId: surfaceIds.systemAppendix(manifest.name, entry.name),
+			name: entry.name,
+			relativePath: compiled.relativePath,
+			content: compiled.content,
+			contentHash: compiled.contentHash,
+			bytes: compiled.bytes,
+		});
+	}
+
+	const agentAppendices: NormalizedAgentAppendixSurface[] = [];
+	for (const entry of manifest.agentAppendix) {
+		const compiled = await compileAppendix(pluginRoot, entry, `agent-appendix "${entry.agent}/${entry.name}"`, files);
+		agentAppendices.push({
+			extensionId: surfaceIds.agentAppendix(entry.agent, manifest.name, entry.name),
+			agent: entry.agent,
+			name: entry.name,
+			relativePath: compiled.relativePath,
+			content: compiled.content,
+			contentHash: compiled.contentHash,
+			bytes: compiled.bytes,
+		});
+	}
+
+	const surfaces: NormalizedGjcPluginSurfaces = {
+		subskills,
+		tools,
+		hooks,
+		mcps,
+		systemAppendices,
+		agentAppendices,
+	};
+
+	const manifestBytes = await fs.readFile(manifestPath);
+	const manifestHash = sha256(manifestBytes);
+
+	const copiedFiles = [...files.entries()]
+		.map(([relativePath, info]) => ({ relativePath, sha256: info.sha256, bytes: info.bytes }))
+		.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+	copiedFiles.unshift({
+		relativePath: GJC_PLUGIN_MANIFEST_FILENAME,
+		sha256: manifestHash,
+		bytes: manifestBytes.byteLength,
+	});
+
+	return {
+		name: manifest.name,
+		version: manifest.version,
+		root: pluginRoot,
+		manifestPath,
+		manifestHash,
+		surfaces,
+		files: copiedFiles,
+	};
+}

package/src/extensibility/gjc-plugins/constrained-hooks.ts

@@ -0,0 +1,170 @@
+import { logger } from "@gajae-code/utils";
+
+import { loadEffectiveGjcPluginRegistry } from "./registry";
+import { type SessionQuarantine, validateSessionBundles, verifyEntryHashes } from "./session-validation";
+import { GjcPluginLoadError, type GjcPluginRegistryEntry } from "./types";
+
+/**
+ * Constrained plugin-hook loader.
+ *
+ * Third-party plugin hooks are NOT given the broad first-party HookAPI. They
+ * receive a restricted API that can only register a handler for their declared
+ * event; every session-mutation / command / shell capability throws
+ * security_policy. After the factory runs we verify it registered exactly the
+ * declared event (and nothing else), or the hook is quarantined.
+ */
+
+export interface ConstrainedPluginHook {
+	plugin: string;
+	event: string;
+	target?: string;
+	phase?: "before" | "after";
+	handler: (...args: any[]) => unknown;
+}
+
+export interface ConstrainedHookLoadResult {
+	hooks: ConstrainedPluginHook[];
+	quarantine: SessionQuarantine[];
+}
+
+const DENIED_API_METHODS = [
+	"sendMessage",
+	"appendEntry",
+	"registerMessageRenderer",
+	"registerCommand",
+	"exec",
+] as const;
+
+interface DeclaredHook {
+	plugin: string;
+	event: string;
+	target?: string;
+	phase?: "before" | "after";
+	relativePath: string;
+}
+
+function collectDeclaredHooks(entries: readonly GjcPluginRegistryEntry[]): DeclaredHook[] {
+	const out: DeclaredHook[] = [];
+	for (const entry of entries) {
+		if (!entry.enabled) continue;
+		const disabled = new Set(entry.disabledSurfaceIds);
+		for (const h of entry.surfaces.hooks) {
+			if (disabled.has(h.extensionId)) continue;
+			out.push({
+				plugin: entry.name,
+				event: h.event,
+				target: h.target,
+				phase: h.phase,
+				relativePath: `${entry.pluginRoot}/${h.relativePath}`,
+			});
+		}
+	}
+	return out;
+}
+
+async function loadOneHook(
+	declared: DeclaredHook,
+): Promise<{ hook: ConstrainedPluginHook | null; quarantine: SessionQuarantine | null }> {
+	const registered: { event: string; handler: (...a: any[]) => unknown }[] = [];
+	const deny = (method: string) => () => {
+		throw new GjcPluginLoadError(
+			"security_policy",
+			`Plugin hook "${declared.plugin}" attempted denied API: ${method}`,
+		);
+	};
+	const constrainedApi: Record<string, unknown> = {
+		on(event: string, handler: (...a: any[]) => unknown): void {
+			registered.push({ event, handler });
+		},
+		logger,
+	};
+	for (const method of DENIED_API_METHODS) constrainedApi[method] = deny(method);
+
+	let factory: unknown;
+	try {
+		const mod = await import(declared.relativePath);
+		factory = mod.default ?? mod;
+	} catch (error) {
+		return {
+			hook: null,
+			quarantine: {
+				plugin: declared.plugin,
+				surfaceId: `hook:${declared.event}:${declared.target ?? ""}`,
+				code: "invalid_hook",
+				message: `Failed to import plugin hook: ${error instanceof Error ? error.message : String(error)}`,
+			},
+		};
+	}
+	if (typeof factory !== "function") {
+		return {
+			hook: null,
+			quarantine: {
+				plugin: declared.plugin,
+				surfaceId: `hook:${declared.event}`,
+				code: "invalid_hook",
+				message: "Plugin hook must export a default function",
+			},
+		};
+	}
+	try {
+		await (factory as (api: unknown) => unknown)(constrainedApi);
+	} catch (error) {
+		const code = error instanceof GjcPluginLoadError ? error.code : "security_policy";
+		return {
+			hook: null,
+			quarantine: {
+				plugin: declared.plugin,
+				surfaceId: `hook:${declared.event}`,
+				code,
+				message: error instanceof Error ? error.message : String(error),
+			},
+		};
+	}
+	// Exactly one handler, for the declared event only.
+	if (registered.length !== 1 || registered[0]?.event !== declared.event) {
+		return {
+			hook: null,
+			quarantine: {
+				plugin: declared.plugin,
+				surfaceId: `hook:${declared.event}`,
+				code: "runtime_mismatch",
+				message: `Plugin hook registered ${JSON.stringify(registered.map(r => r.event))}, expected exactly ["${declared.event}"]`,
+			},
+		};
+	}
+	return {
+		hook: {
+			plugin: declared.plugin,
+			event: declared.event,
+			target: declared.target,
+			phase: declared.phase,
+			handler: registered[0].handler,
+		},
+		quarantine: null,
+	};
+}
+
+/**
+ * Load all always-on constrained plugin hooks for the effective registry at
+ * `cwd`, applying hash-drift + collision quarantine first. Returns empty when
+ * no plugins are installed.
+ */
+export async function loadConstrainedPluginHooks(input: { cwd: string }): Promise<ConstrainedHookLoadResult> {
+	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	if (effective.length === 0) return { hooks: [], quarantine: [] };
+	const preQuarantine: SessionQuarantine[] = [];
+	for (const entry of effective) {
+		if (!entry.enabled) continue;
+		const drift = await verifyEntryHashes(entry);
+		if (drift) preQuarantine.push(drift);
+	}
+	const { active, quarantine } = validateSessionBundles(effective, {}, preQuarantine);
+	const declared = collectDeclaredHooks(active);
+	const hooks: ConstrainedPluginHook[] = [];
+	for (const d of declared) {
+		const { hook, quarantine: q } = await loadOneHook(d);
+		if (hook) hooks.push(hook);
+		if (q) quarantine.push(q);
+	}
+	return { hooks, quarantine };
+}

package/src/extensibility/gjc-plugins/index.ts

@@ -1,8 +1,17 @@
 export * from "./activation";
+export * from "./compiler";
+export * from "./constrained-hooks";
 export * from "./injection";
+export * from "./installer";
 export * from "./loader";
+export * from "./mcp-policy";
+export * from "./observability";
 export * from "./paths";
+export * from "./prompt-appendix";
+export * from "./registry";
+export * from "./runtime-adapters";
 export * from "./schema";
+export * from "./session-validation";
 export * from "./state";
 export * from "./tools";
 export * from "./types";

package/src/extensibility/gjc-plugins/injection.ts

@@ -131,3 +131,112 @@ export async function buildAgentSubskillInjection(input: {
 	);
 	return blocks.join("");
 }
+
+// ---------------------------------------------------------------------------
+// Tier-1 sub-skill advertisement (metadata-only, bounded, target-parent scoped)
+// ---------------------------------------------------------------------------
+
+import type { GjcPluginRegistryEntry } from "./types";
+
+const ADVERT_MAX_ITEMS = 12;
+const ADVERT_MAX_DESC = 200;
+const ADVERT_MAX_FIELD = 80;
+const ADVERT_MAX_BYTES = 4 * 1024;
+
+function escapeAdvertAttr(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+interface AdvertItem {
+	plugin: string;
+	name: string;
+	description: string;
+	activationArg: string;
+	phase: string;
+}
+
+function clampField(value: string): string {
+	const v = value.length > ADVERT_MAX_FIELD ? `${value.slice(0, ADVERT_MAX_FIELD - 1)}\u2026` : value;
+	return escapeAdvertAttr(v);
+}
+
+function renderAdvertItem(it: AdvertItem): string {
+	const desc =
+		it.description.length > ADVERT_MAX_DESC
+			? `${it.description.slice(0, ADVERT_MAX_DESC - 1)}\u2026`
+			: it.description;
+	return `  - plugin="${clampField(it.plugin)}" name="${clampField(it.name)}" activation_arg="${clampField(it.activationArg)}" phase="${clampField(it.phase)}": ${escapeAdvertAttr(desc)}`;
+}
+
+function wrapAdvert(kind: "skill" | "agent", parent: string, lines: string[]): string {
+	return `<gjc-plugin-subskill-advertisement parent="${clampField(parent)}" kind="${kind}">\n${lines.join("\n")}\n</gjc-plugin-subskill-advertisement>`;
+}
+
+function renderAdvertisement(items: AdvertItem[], kind: "skill" | "agent", parent: string): string {
+	if (items.length === 0) return "";
+	// Build iteratively against the byte budget so the block is HARD-capped even
+	// if individual items are large; every metadata field is also length-clamped.
+	const candidates = items.slice(0, ADVERT_MAX_ITEMS);
+	const lines: string[] = [];
+	let shownCount = 0;
+	for (const it of candidates) {
+		const next = [...lines, renderAdvertItem(it)];
+		const omittedNote = `  - ${items.length - (shownCount + 1)} additional plugin sub-skill(s) omitted; invoke explicitly with a known activation arg.`;
+		const probe = wrapAdvert(kind, parent, items.length - (shownCount + 1) > 0 ? [...next, omittedNote] : next);
+		if (Buffer.byteLength(probe) > ADVERT_MAX_BYTES) break;
+		lines.push(renderAdvertItem(it));
+		shownCount += 1;
+	}
+	const omitted = items.length - shownCount;
+	if (shownCount === 0) {
+		// Nothing fit: guaranteed-small overflow-only block.
+		return wrapAdvert(kind, parent, [
+			`  - ${items.length} plugin sub-skill(s) available; invoke explicitly with a known activation arg.`,
+		]);
+	}
+	if (omitted > 0) {
+		lines.push(
+			`  - ${omitted} additional plugin sub-skill(s) omitted; invoke explicitly with a known activation arg.`,
+		);
+	}
+	return wrapAdvert(kind, parent, lines);
+}
+
+function collectAdverts(entries: readonly GjcPluginRegistryEntry[], parent: string, phase?: string): AdvertItem[] {
+	const items: AdvertItem[] = [];
+	for (const entry of entries) {
+		if (!entry.enabled) continue;
+		const disabled = new Set(entry.disabledSurfaceIds);
+		for (const s of entry.surfaces.subskills) {
+			if (disabled.has(s.extensionId)) continue;
+			if (s.parent !== parent) continue;
+			if (phase && s.phase !== phase) continue;
+			items.push({
+				plugin: entry.name,
+				name: s.name,
+				description: s.description,
+				activationArg: s.activationArg,
+				phase: s.phase,
+			});
+		}
+	}
+	return items;
+}
+
+/**
+ * Tier-1 advertisement for a workflow parent skill: bounded, metadata-only list
+ * of installed sub-skills bound to `parent`, rendered ONLY in that parent's
+ * prompt (never the global public-workflow-surface). No body content.
+ */
+export function buildSubskillAdvertisement(
+	entries: readonly GjcPluginRegistryEntry[],
+	parent: string,
+	phase?: string,
+): string {
+	return renderAdvertisement(collectAdverts(entries, parent, phase), "skill", parent);
+}
+
+/** Tier-1 advertisement for a role-agent parent. */
+export function buildAgentSubskillAdvertisement(entries: readonly GjcPluginRegistryEntry[], agentName: string): string {
+	return renderAdvertisement(collectAdverts(entries, agentName), "agent", agentName);
+}