@gajae-code/coding-agent 0.3.2 → 0.4.1

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

@@ -0,0 +1,131 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { parseFrontmatter } from "@gajae-code/utils";
+import { resolveWithinRoot } from "./paths";
+import { parseManifest, parseSubskillFrontmatter } from "./schema";
+import {
+	GJC_PLUGIN_MANIFEST_FILENAME,
+	GjcPluginLoadError,
+	type LoadedGjcPlugin,
+	type LoadedSubskillBinding,
+	type PhaseScopedToolBinding,
+} from "./types";
+import { buildParentArgMap, buildParentPhaseSet, validateBinding } from "./validation";
+
+async function readJsonFile(filePath: string): Promise<unknown> {
+	try {
+		return JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
+	} catch (error) {
+		if (error instanceof SyntaxError) {
+			throw new GjcPluginLoadError("invalid_manifest", `Invalid GJC plugin manifest JSON at ${filePath}`, {
+				cause: error,
+			});
+		}
+		throw new GjcPluginLoadError("missing_file", `Missing GJC plugin manifest at ${filePath}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+}
+
+async function readRequiredText(filePath: string, kind: "sub-skill" | "tool"): Promise<string> {
+	try {
+		return await fs.readFile(filePath, "utf8");
+	} catch (error) {
+		throw new GjcPluginLoadError("missing_file", `Missing GJC plugin ${kind} file at ${filePath}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+}
+
+function parseFrontmatterToolPaths(fm: Record<string, unknown>): string[] {
+	const raw = fm.tools;
+	if (raw === undefined) return [];
+	if (typeof raw === "string") return raw.trim() ? [raw] : [];
+	if (Array.isArray(raw) && raw.every(item => typeof item === "string")) return [...raw];
+	return [];
+}
+
+function pushToolBinding(
+	toolBindings: PhaseScopedToolBinding[],
+	plugin: string,
+	parent: string,
+	phase: string,
+	toolPath: string,
+): void {
+	toolBindings.push({ plugin, parent, phase, toolPath });
+}
+
+export async function loadGjcPlugin(root: string): Promise<LoadedGjcPlugin> {
+	const pluginRoot = path.resolve(root);
+	const manifestPath = path.join(pluginRoot, GJC_PLUGIN_MANIFEST_FILENAME);
+	const manifest = parseManifest(await readJsonFile(manifestPath), manifestPath);
+	const manifestToolPaths = manifest.tools.map(rel => resolveWithinRoot(pluginRoot, rel));
+
+	for (const toolPath of manifestToolPaths) {
+		await readRequiredText(toolPath, "tool");
+	}
+
+	const bindings: LoadedSubskillBinding[] = [];
+	const toolBindings: PhaseScopedToolBinding[] = [];
+
+	for (const rel of manifest.subskills) {
+		const filePath = resolveWithinRoot(pluginRoot, rel);
+		const content = await readRequiredText(filePath, "sub-skill");
+		let parsed: { frontmatter: Record<string, unknown>; body: string };
+		try {
+			parsed = parseFrontmatter(content, { source: filePath, level: "fatal" });
+		} catch (error) {
+			throw new GjcPluginLoadError("invalid_frontmatter", `Invalid GJC sub-skill frontmatter at ${filePath}`, {
+				cause: error instanceof Error ? error : undefined,
+			});
+		}
+		const frontmatter = parseSubskillFrontmatter(parsed.frontmatter, filePath);
+		validateBinding(frontmatter);
+		const frontmatterToolPaths = parseFrontmatterToolPaths(parsed.frontmatter).map(toolRel =>
+			resolveWithinRoot(pluginRoot, toolRel),
+		);
+		for (const toolPath of frontmatterToolPaths) {
+			await readRequiredText(toolPath, "tool");
+		}
+		const toolPaths = [...manifestToolPaths, ...frontmatterToolPaths];
+		const binding: LoadedSubskillBinding = {
+			plugin: manifest.name,
+			subskillName: frontmatter.name,
+			parent: frontmatter.binds_to,
+			bindsTo: frontmatter.binds_to,
+			phase: frontmatter.phase,
+			activationArg: frontmatter.activation_arg,
+			description: frontmatter.description,
+			filePath,
+			body: parsed.body,
+			toolPaths,
+		};
+		bindings.push(binding);
+		for (const toolPath of toolPaths) {
+			pushToolBinding(toolBindings, manifest.name, binding.parent, binding.phase, toolPath);
+		}
+	}
+
+	buildParentArgMap(bindings);
+	buildParentPhaseSet(bindings);
+
+	return {
+		name: manifest.name,
+		version: manifest.version,
+		root: pluginRoot,
+		manifestPath,
+		bindings,
+		toolBindings,
+	};
+}
+
+export async function loadGjcPlugins(roots: readonly string[]): Promise<LoadedGjcPlugin[]> {
+	const plugins: LoadedGjcPlugin[] = [];
+	for (const root of roots) {
+		plugins.push(await loadGjcPlugin(root));
+	}
+	const bindings = plugins.flatMap(plugin => plugin.bindings);
+	buildParentArgMap(bindings);
+	buildParentPhaseSet(bindings);
+	return plugins;
+}

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

@@ -0,0 +1,66 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, pathIsWithin } from "@gajae-code/utils";
+import { GJC_PLUGIN_MANIFEST_FILENAME, GjcPluginLoadError } from "./types";
+
+export function gjcPluginUserRoot(): string {
+	return path.join(getAgentDir(), "gjc-plugins");
+}
+
+export function gjcPluginProjectRoot(cwd: string): string {
+	return path.join(cwd, ".gjc", "gjc-plugins");
+}
+
+function isEnoent(error: unknown): boolean {
+	return (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+export async function rootContainsGjcManifest(dir: string): Promise<boolean> {
+	try {
+		await fs.access(path.join(dir, GJC_PLUGIN_MANIFEST_FILENAME));
+		return true;
+	} catch (error) {
+		if (isEnoent(error)) return false;
+		throw error;
+	}
+}
+
+async function discoverGjcPluginRootsIn(baseDir: string): Promise<string[]> {
+	if (await rootContainsGjcManifest(baseDir)) return [baseDir];
+
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = await fs.readdir(baseDir, { withFileTypes: true });
+	} catch (error) {
+		if (isEnoent(error)) return [];
+		throw error;
+	}
+
+	const roots = await Promise.all(
+		entries
+			.filter(entry => entry.isDirectory() || entry.isSymbolicLink())
+			.map(async entry => {
+				const dir = path.join(baseDir, entry.name);
+				return (await rootContainsGjcManifest(dir)) ? dir : null;
+			}),
+	);
+
+	return roots.filter((root): root is string => root !== null);
+}
+
+export async function discoverGjcPluginRoots({ cwd }: { cwd: string; home?: string }): Promise<string[]> {
+	const roots = await Promise.all([
+		discoverGjcPluginRootsIn(gjcPluginUserRoot()),
+		discoverGjcPluginRootsIn(gjcPluginProjectRoot(cwd)),
+	]);
+	return roots.flat();
+}
+
+export function resolveWithinRoot(root: string, rel: string): string {
+	const resolvedRoot = path.resolve(root);
+	const resolvedPath = path.resolve(resolvedRoot, rel);
+	if (!pathIsWithin(resolvedRoot, resolvedPath)) {
+		throw new GjcPluginLoadError("missing_file", `GJC plugin path escapes root: ${rel}`);
+	}
+	return resolvedPath;
+}

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

@@ -0,0 +1,79 @@
+import { GJC_PLUGIN_KIND, GjcPluginLoadError, type GjcPluginManifest, type SubskillFrontmatter } from "./types";
+
+const FORBIDDEN_MANIFEST_KEYS = ["skills", "slash-commands", "commands", "hooks", "mcp", "mcpServers", "agents"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireNonEmptyString(value: unknown, field: string, filePath: string): string {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new GjcPluginLoadError(
+			"invalid_frontmatter",
+			`Invalid sub-skill frontmatter in ${filePath}: ${field} must be a non-empty string`,
+		);
+	}
+	return value;
+}
+
+function requireStringArray(value: unknown, field: string, manifestPath: string): string[] {
+	if (!Array.isArray(value) || !value.every(item => typeof item === "string")) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: ${field} must be a string array`,
+		);
+	}
+	return [...value];
+}
+
+export function parseManifest(raw: unknown, manifestPath: string): GjcPluginManifest {
+	if (!isRecord(raw)) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: expected object`,
+		);
+	}
+
+	for (const key of FORBIDDEN_MANIFEST_KEYS) {
+		if (Object.hasOwn(raw, key)) {
+			throw new GjcPluginLoadError("forbidden_surface", `Forbidden GJC plugin surface in ${manifestPath}: ${key}`);
+		}
+	}
+
+	if (raw.kind !== GJC_PLUGIN_KIND) {
+		throw new GjcPluginLoadError(
+			"invalid_kind",
+			`Invalid GJC plugin kind in ${manifestPath}: expected ${GJC_PLUGIN_KIND}`,
+		);
+	}
+	if (typeof raw.name !== "string" || raw.name.trim().length === 0) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: name must be a non-empty string`,
+		);
+	}
+	if (typeof raw.version !== "string" || raw.version.trim().length === 0) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: version must be a non-empty string`,
+		);
+	}
+
+	return {
+		name: raw.name,
+		version: raw.version,
+		kind: GJC_PLUGIN_KIND,
+		subskills: requireStringArray(raw.subskills, "subskills", manifestPath),
+		tools: requireStringArray(raw.tools, "tools", manifestPath),
+	};
+}
+
+export function parseSubskillFrontmatter(fm: Record<string, unknown>, filePath: string): SubskillFrontmatter {
+	return {
+		name: requireNonEmptyString(fm.name, "name", filePath),
+		binds_to: requireNonEmptyString(fm.binds_to, "binds_to", filePath),
+		phase: requireNonEmptyString(fm.phase, "phase", filePath),
+		activation_arg: requireNonEmptyString(fm.activation_arg, "activation_arg", filePath),
+		description: requireNonEmptyString(fm.description, "description", filePath),
+	};
+}

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

@@ -0,0 +1,29 @@
+import type { ActiveSubskillEntry } from "../../skill-state/active-state";
+import { readVisibleSkillActiveState } from "../../skill-state/active-state";
+import type { LoadedSubskillActivation } from "./types";
+
+export function toActiveSubskillEntry(activation: LoadedSubskillActivation): ActiveSubskillEntry {
+	return {
+		plugin: activation.plugin,
+		subskillName: activation.subskillName,
+		parent: activation.parent,
+		bindsTo: activation.bindsTo,
+		phase: activation.phase,
+		activationArg: activation.activationArg,
+		filePath: activation.filePath,
+		toolPaths: activation.toolPaths,
+	};
+}
+
+export async function readActiveSubskillsForParent(input: {
+	cwd: string;
+	sessionId?: string;
+	parent: string;
+	phase: string;
+}): Promise<ActiveSubskillEntry[]> {
+	const state = await readVisibleSkillActiveState(input.cwd, input.sessionId);
+	const parent = input.parent.trim();
+	const phase = input.phase.trim();
+	if (!state || !parent || !phase) return [];
+	return (state.active_subskills ?? []).filter(entry => entry.parent === parent && entry.phase === phase);
+}

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

@@ -0,0 +1,47 @@
+import { logger } from "@gajae-code/utils";
+import { loadCustomTools } from "../custom-tools/loader";
+import type { CustomTool } from "../custom-tools/types";
+import { readActiveSubskillsForParent } from "./state";
+
+export async function loadActiveSubskillTools(input: {
+	cwd: string;
+	sessionId?: string;
+	parent: string;
+	phase: string;
+	reservedToolNames?: string[];
+}): Promise<CustomTool[]> {
+	const entries = await readActiveSubskillsForParent(input);
+	const toolPaths = [
+		...new Set(entries.flatMap(entry => entry.toolPaths ?? []).filter(path => path.trim().length > 0)),
+	];
+	if (toolPaths.length === 0) return [];
+
+	const reservedToolNames = new Set(input.reservedToolNames ?? []);
+	const result = await loadCustomTools(
+		toolPaths.map(path => ({ path })),
+		input.cwd,
+		input.reservedToolNames ?? [],
+	);
+
+	for (const error of result.errors) {
+		logger.warn("Skipping GJC plugin sub-skill tool", { path: error.path, error: error.error });
+	}
+
+	const tools: CustomTool[] = [];
+	const seenNames = new Set<string>();
+	for (const loadedTool of result.tools) {
+		const name = loadedTool.tool.name;
+		if (reservedToolNames.has(name)) {
+			logger.warn("Skipping GJC plugin sub-skill tool name because it conflicts with a reserved tool", { name });
+			continue;
+		}
+		if (seenNames.has(name)) {
+			logger.warn("Skipping duplicate GJC plugin sub-skill tool name", { name, path: loadedTool.path });
+			continue;
+		}
+		seenNames.add(name);
+		tools.push(loadedTool.tool);
+	}
+
+	return tools;
+}

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

@@ -0,0 +1,97 @@
+import type { CanonicalGjcWorkflowSkill } from "../../skill-state/active-state";
+import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../../skill-state/active-state";
+
+export const GJC_PLUGIN_MANIFEST_FILENAME = "gajae-plugin.json";
+export const GJC_PLUGIN_KIND = "gajae-code-plugin";
+
+export const GJC_SUBSKILL_PARENT_SKILLS = CANONICAL_GJC_WORKFLOW_SKILLS;
+export type GjcSubskillParentSkill = CanonicalGjcWorkflowSkill;
+
+export const GJC_SUBSKILL_PARENT_AGENTS = ["executor", "architect", "planner", "critic"] as const;
+export type GjcSubskillParentAgent = (typeof GJC_SUBSKILL_PARENT_AGENTS)[number];
+
+export type GjcSubskillParent = GjcSubskillParentSkill | GjcSubskillParentAgent;
+
+export const GJC_AGENT_SUBSKILL_PHASES: Record<GjcSubskillParentAgent, string[]> = {
+	executor: ["prompt"],
+	architect: ["prompt"],
+	planner: ["prompt"],
+	critic: ["prompt"],
+};
+
+export interface GjcPluginManifest {
+	name: string;
+	version: string;
+	kind: "gajae-code-plugin";
+	subskills: string[];
+	tools: string[];
+}
+
+export interface SubskillFrontmatter {
+	name: string;
+	binds_to: string;
+	phase: string;
+	activation_arg: string;
+	description: string;
+}
+
+export interface LoadedSubskillBinding {
+	plugin: string;
+	subskillName: string;
+	parent: string;
+	bindsTo: string;
+	phase: string;
+	activationArg: string;
+	description: string;
+	filePath: string;
+	body: string;
+	toolPaths: string[];
+}
+
+export interface LoadedSubskillActivation {
+	activationArg: string;
+	plugin: string;
+	subskillName: string;
+	parent: string;
+	bindsTo: string;
+	phase: string;
+	filePath: string;
+	toolPaths: string[];
+}
+
+export interface PhaseScopedToolBinding {
+	plugin: string;
+	parent: string;
+	phase: string;
+	toolPath: string;
+}
+
+export interface LoadedGjcPlugin {
+	name: string;
+	version: string;
+	root: string;
+	manifestPath: string;
+	bindings: LoadedSubskillBinding[];
+	toolBindings: PhaseScopedToolBinding[];
+}
+
+export type GjcPluginLoadErrorCode =
+	| "forbidden_surface"
+	| "invalid_manifest"
+	| "invalid_frontmatter"
+	| "invalid_parent"
+	| "invalid_phase"
+	| "duplicate_arg"
+	| "duplicate_parent_phase"
+	| "missing_file"
+	| "invalid_kind";
+
+export class GjcPluginLoadError extends Error {
+	readonly code: GjcPluginLoadErrorCode;
+
+	constructor(code: GjcPluginLoadErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "GjcPluginLoadError";
+		this.code = code;
+	}
+}

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

@@ -0,0 +1,76 @@
+import { isKnownWorkflowState } from "../../gjc-runtime/workflow-manifest";
+import type { CanonicalGjcWorkflowSkill } from "../../skill-state/active-state";
+import {
+	GJC_AGENT_SUBSKILL_PHASES,
+	GJC_SUBSKILL_PARENT_AGENTS,
+	GJC_SUBSKILL_PARENT_SKILLS,
+	GjcPluginLoadError,
+	type GjcSubskillParentAgent,
+	type LoadedSubskillBinding,
+	type SubskillFrontmatter,
+} from "./types";
+
+function isParentSkill(value: string): value is CanonicalGjcWorkflowSkill {
+	return (GJC_SUBSKILL_PARENT_SKILLS as readonly string[]).includes(value);
+}
+
+function isParentAgent(value: string): value is GjcSubskillParentAgent {
+	return (GJC_SUBSKILL_PARENT_AGENTS as readonly string[]).includes(value);
+}
+
+export function validateBinding(fm: SubskillFrontmatter): void {
+	const parent = fm.binds_to;
+	if (isParentSkill(parent)) {
+		if (!isKnownWorkflowState(parent, fm.phase)) {
+			throw new GjcPluginLoadError("invalid_phase", `Invalid GJC sub-skill phase for ${parent}: ${fm.phase}`);
+		}
+		return;
+	}
+
+	if (isParentAgent(parent)) {
+		if (!GJC_AGENT_SUBSKILL_PHASES[parent].includes(fm.phase)) {
+			throw new GjcPluginLoadError("invalid_phase", `Invalid GJC sub-skill phase for ${parent}: ${fm.phase}`);
+		}
+		return;
+	}
+
+	throw new GjcPluginLoadError("invalid_parent", `Invalid GJC sub-skill parent: ${parent}`);
+}
+
+export function buildParentArgMap(
+	bindings: readonly LoadedSubskillBinding[],
+): Map<string, Map<string, LoadedSubskillBinding>> {
+	const byParent = new Map<string, Map<string, LoadedSubskillBinding>>();
+	for (const binding of bindings) {
+		let byArg = byParent.get(binding.parent);
+		if (!byArg) {
+			byArg = new Map<string, LoadedSubskillBinding>();
+			byParent.set(binding.parent, byArg);
+		}
+		const existing = byArg.get(binding.activationArg);
+		if (existing) {
+			throw new GjcPluginLoadError(
+				"duplicate_arg",
+				`Duplicate GJC sub-skill activation_arg for ${binding.parent}: ${binding.activationArg} (${existing.filePath}, ${binding.filePath})`,
+			);
+		}
+		byArg.set(binding.activationArg, binding);
+	}
+	return byParent;
+}
+
+export function buildParentPhaseSet(bindings: readonly LoadedSubskillBinding[]): Set<string> {
+	const seen = new Map<string, LoadedSubskillBinding>();
+	for (const binding of bindings) {
+		const key = `${binding.parent}\u0000${binding.phase}`;
+		const existing = seen.get(key);
+		if (existing) {
+			throw new GjcPluginLoadError(
+				"duplicate_parent_phase",
+				`Duplicate GJC sub-skill parent/phase binding for ${binding.parent}/${binding.phase} (${existing.filePath}, ${binding.filePath})`,
+			);
+		}
+		seen.set(key, binding);
+	}
+	return new Set(seen.keys());
+}

package/src/extensibility/skills.ts

@@ -8,6 +8,8 @@ import { type Skill as CapabilitySkill, loadCapability } from "../discovery";
 import { compareSkillOrder, scanSkillsFromDir } from "../discovery/helpers";
 import type { SkillPromptDetails } from "../session/messages";
 import { expandTilde } from "../tools/path-utils";
+import type { LoadedSubskillActivation } from "./gjc-plugins";
+import { buildSubskillInjection } from "./gjc-plugins/injection";
 export interface Skill {
 	name: string;
 	description: string;
@@ -280,6 +282,14 @@ export interface BuiltSkillPromptMessage {
 	details: SkillPromptDetails;
 }
 
+export interface BuildSkillPromptMessageContext {
+	subskillActivation?: LoadedSubskillActivation;
+	subskillActivationSet?: LoadedSubskillActivation[];
+	currentPhase?: string;
+	cwd?: string;
+	sessionId?: string;
+}
+
 export function getSkillSlashCommandName(skill: Pick<Skill, "name">): string {
 	return `skill:${skill.name}`;
 }
@@ -370,6 +380,7 @@ export function resolveSkillSlashCommands(
 export async function buildSkillPromptMessage(
 	skill: Pick<Skill, "name" | "filePath" | "content">,
 	args: string,
+	context?: BuildSkillPromptMessageContext,
 ): Promise<BuiltSkillPromptMessage> {
 	const content = typeof skill.content === "string" ? skill.content : await Bun.file(skill.filePath).text();
 	const body = content.replace(/^---\n[\s\S]*?\n---\n/, "").trim();
@@ -378,14 +389,35 @@ export async function buildSkillPromptMessage(
 	if (trimmedArgs) {
 		metaLines.push(`User: ${trimmedArgs}`);
 	}
-	const message = `${body}\n\n---\n\n${metaLines.join("\n")}`;
+	let message = `${body}\n\n---\n\n${metaLines.join("\n")}`;
+	const details: SkillPromptDetails = {
+		name: skill.name,
+		path: skill.filePath,
+		args: trimmedArgs || undefined,
+		lineCount: body ? body.split("\n").length : 0,
+	};
+	if (context?.subskillActivationSet) {
+		details.subskillActivationSet = context.subskillActivationSet;
+	}
+	if (context) {
+		const injection = context.cwd
+			? await buildSubskillInjection({
+					cwd: context.cwd,
+					sessionId: context.sessionId,
+					skillName: skill.name,
+					activation: context.subskillActivation,
+					currentPhase: context.currentPhase,
+				})
+			: null;
+		if (injection) {
+			message += injection.block;
+			details.subskillActivation = injection.details ?? context.subskillActivation;
+		} else if (context.subskillActivation) {
+			details.subskillActivation = context.subskillActivation;
+		}
+	}
 	return {
 		message,
-		details: {
-			name: skill.name,
-			path: skill.filePath,
-			args: trimmedArgs || undefined,
-			lineCount: body ? body.split("\n").length : 0,
-		},
+		details,
 	};
 }