@gajae-code/coding-agent 0.14.2 → 0.15.0

package/src/extensibility/extensions/loader.ts

@@ -147,26 +147,116 @@ export class ExtensionRuntime implements IExtensionRuntime {
 	}
 }
 
+/**
+ * Per-extension activation transaction over the shared runtime state.
+ *
+ * Registration writes from a factory are staged here (stage); the factory
+ * completing without throwing is the validation step; commit copies the
+ * staged mutations into the shared runtime; rollback discards them, so a
+ * factory that fails midway leaves no registration behind (issue #4718).
+ */
+export class ExtensionActivationScope {
+	readonly #runtime: IExtensionRuntime;
+	readonly #stagedFlagDefaults = new Map<string, boolean | string>();
+	readonly #stagedProviderRegistrations: Array<{
+		name: string;
+		config: import("./types").ProviderConfig;
+		sourceId: string;
+	}> = [];
+	#closed = false;
+
+	/** True while staged writes may still be added or committed. */
+	get open(): boolean {
+		return !this.#closed;
+	}
+
+	constructor(runtime: IExtensionRuntime) {
+		this.#runtime = runtime;
+	}
+
+	get flagValues(): Map<string, boolean | string> {
+		return this.#stagedFlagDefaults;
+	}
+
+	get pendingProviderRegistrations(): Array<{
+		name: string;
+		config: import("./types").ProviderConfig;
+		sourceId: string;
+	}> {
+		return this.#stagedProviderRegistrations;
+	}
+
+	/**
+	 * Publish the staged mutations into the shared runtime as one transaction.
+	 *
+	 * Prior state is journaled before any live mutation so a throw partway
+	 * through publication is undone before it escapes: flag entries that did
+	 * not exist are removed, overwritten entries are restored, and the
+	 * provider queue is truncated to its prior length. The scope only becomes
+	 * terminal once publication has fully succeeded, so a failed commit
+	 * leaves the shared runtime exactly as it was (issue #4718).
+	 */
+	commit(): void {
+		if (this.#closed) return;
+		const priorFlagEntries = new Map<string, { existed: true; value: boolean | string } | { existed: false }>();
+		for (const name of this.#stagedFlagDefaults.keys()) {
+			// Flag values are `boolean | string`, so `undefined` means absent.
+			const current = this.#runtime.flagValues.get(name);
+			priorFlagEntries.set(name, current === undefined ? { existed: false } : { existed: true, value: current });
+		}
+		const priorProviderCount = this.#runtime.pendingProviderRegistrations.length;
+
+		try {
+			for (const [name, value] of this.#stagedFlagDefaults) {
+				this.#runtime.flagValues.set(name, value);
+			}
+			for (const registration of this.#stagedProviderRegistrations) {
+				this.#runtime.pendingProviderRegistrations.push(registration);
+			}
+		} catch (err) {
+			for (const [name, prior] of priorFlagEntries) {
+				if (prior.existed) {
+					this.#runtime.flagValues.set(name, prior.value);
+				} else {
+					this.#runtime.flagValues.delete(name);
+				}
+			}
+			this.#runtime.pendingProviderRegistrations.length = priorProviderCount;
+			this.#close();
+			throw err;
+		}
+
+		this.#closed = true;
+	}
+
+	rollback(): void {
+		if (this.#closed) return;
+		this.#close();
+	}
+
+	/** Mark the scope terminal and drop the staged copies. */
+	#close(): void {
+		this.#closed = true;
+		this.#stagedFlagDefaults.clear();
+		this.#stagedProviderRegistrations.length = 0;
+	}
+}
+
 /**
  * ExtensionAPI implementation for an extension.
  * Registration methods write to the extension object.
  * Action methods delegate to the shared runtime.
  */
-class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
+class ConcreteExtensionAPI implements ExtensionAPI {
 	readonly logger = logger;
 	readonly typebox = TypeBox;
 	readonly zod = Zod;
-	readonly flagValues = new Map<string, boolean | string>();
-	readonly pendingProviderRegistrations: Array<{
-		name: string;
-		config: import("./types").ProviderConfig;
-		sourceId: string;
-	}> = [];
 
 	constructor(
 		public readonly pi: typeof import("@gajae-code/coding-agent"),
 		private readonly extension: Extension,
 		private readonly runtime: IExtensionRuntime,
+		private readonly activation: ExtensionActivationScope,
 		private readonly cwd: string,
 		public readonly events: EventBus,
 	) {}
@@ -218,7 +308,7 @@ class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
 	): void {
 		this.extension.flags.set(name, { name, extensionPath: this.extension.path, ...options });
 		if (options.default !== undefined) {
-			this.runtime.flagValues.set(name, options.default);
+			this.activation.flagValues.set(name, options.default);
 		}
 	}
 
@@ -228,7 +318,14 @@ class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
 
 	getFlag(name: string): boolean | string | undefined {
 		if (!this.extension.flags.has(name)) return undefined;
-		return this.runtime.flagValues.get(name);
+		if (!this.activation.open) {
+			// Post-commit: the shared runtime is authoritative, so runtime-side
+			// writes (CLI flag overrides, later extensions) stay observable.
+			return this.runtime.flagValues.get(name);
+		}
+		// Activation in flight: prefer this factory's staged default so the
+		// extension reads back what it just registered.
+		return this.activation.flagValues.get(name) ?? this.runtime.flagValues.get(name);
 	}
 
 	sendMessage<T = unknown>(
@@ -338,7 +435,7 @@ class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
 	}
 
 	registerProvider(name: string, config: import("./types").ProviderConfig): void {
-		this.runtime.pendingProviderRegistrations.push({ name, config, sourceId: this.extension.path });
+		this.activation.pendingProviderRegistrations.push({ name, config, sourceId: this.extension.path });
 	}
 }
 
@@ -365,6 +462,7 @@ async function loadExtension(
 	runtime: IExtensionRuntime,
 ): Promise<{ extension: Extension | null; error: string | null }> {
 	const resolvedPath = resolvePath(extensionPath, cwd);
+	let activation: ExtensionActivationScope | undefined;
 	try {
 		const module = (await loadLegacyPiModule(resolvedPath)) as LoadedExtensionModule;
 		const factory = getExtensionFactory(module);
@@ -377,11 +475,21 @@ async function loadExtension(
 		}
 
 		const extension = createExtension(extensionPath, resolvedPath);
-		const api = new ConcreteExtensionAPI(await import("@gajae-code/coding-agent"), extension, runtime, cwd, eventBus);
+		activation = new ExtensionActivationScope(runtime);
+		const api = new ConcreteExtensionAPI(
+			await import("@gajae-code/coding-agent"),
+			extension,
+			runtime,
+			activation,
+			cwd,
+			eventBus,
+		);
 		await factory(api);
+		activation.commit();
 
 		return { extension, error: null };
 	} catch (err) {
+		activation?.rollback();
 		const message = err instanceof Error ? err.message : String(err);
 		return { extension: null, error: `Failed to load extension: ${message}` };
 	}
@@ -398,8 +506,22 @@ export async function loadExtensionFromFactory(
 	name = "<inline>",
 ): Promise<Extension> {
 	const extension = createExtension(name, name);
-	const api = new ConcreteExtensionAPI(await import("@gajae-code/coding-agent"), extension, runtime, cwd, eventBus);
-	await factory(api);
+	const activation = new ExtensionActivationScope(runtime);
+	const api = new ConcreteExtensionAPI(
+		await import("@gajae-code/coding-agent"),
+		extension,
+		runtime,
+		activation,
+		cwd,
+		eventBus,
+	);
+	try {
+		await factory(api);
+	} catch (err) {
+		activation.rollback();
+		throw err;
+	}
+	activation.commit();
 	return extension;
 }
 

package/src/extensibility/extensions/wrapper.ts

@@ -26,8 +26,6 @@ export class RegisteredToolAdapter implements AgentTool<any, any, any> {
 		private registeredTool: RegisteredTool,
 		private runner: ExtensionRunner,
 	) {
-		applyToolProxy(registeredTool.definition, this);
-
 		// Only define render methods when the underlying definition provides them.
 		// If these exist unconditionally on the prototype, ToolExecutionComponent
 		// enters the custom-renderer path, gets undefined back, and silently
@@ -45,6 +43,7 @@ export class RegisteredToolAdapter implements AgentTool<any, any, any> {
 					args,
 				);
 		}
+		applyToolProxy(registeredTool.definition, this);
 	}
 
 	async execute(

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

@@ -26,7 +26,7 @@ const FORBIDDEN_MANIFEST_KEYS = ["skills", "slash-commands", "commands", "agents
 type ForbiddenManifestKey = (typeof FORBIDDEN_MANIFEST_KEYS)[number];
 
 const FORBIDDEN_SURFACE_DIAGNOSTICS: Record<ForbiddenManifestKey, string> = {
-	skills: `Forbidden GJC plugin surface "skills": bundles may only EXTEND the four bundled workflow skills (deep-interview, ralplan, ultragoal, team) and the four role agents (executor, architect, planner, critic), never register a new top-level skill. Bind an inline sub-skill with the canonical "subskills" surface (frontmatter binds_to/phase/activation_arg), or drop the manifest and use the loose surface .gjc/skills/<name>/SKILL.md (project) / ~/.gjc/agent/skills/<name>/SKILL.md (user).`,
+	skills: `Forbidden GJC plugin surface "skills": bundles may only EXTEND the four bundled workflow skills (deep-interview, ralplan, ultragoal, autoresearch) and the four role agents (executor, architect, planner, critic), never register a new top-level skill. Bind an inline sub-skill with the canonical "subskills" surface (frontmatter binds_to/phase/activation_arg), or drop the manifest and use the loose surface .gjc/skills/<name>/SKILL.md (project) / ~/.gjc/agent/skills/<name>/SKILL.md (user).`,
 	"slash-commands": `Forbidden GJC plugin surface "slash-commands": bundles cannot register slash commands. Use the loose surface .gjc/commands/<name> (TypeScript module) or a markdown slash-command file instead.`,
 	commands: `Forbidden GJC plugin surface "commands" (Claude Code plugin.json vocabulary): bundles cannot register slash commands. Use the loose surface .gjc/commands/<name> (TypeScript module) or a markdown slash-command file instead.`,
 	agents: `Forbidden GJC plugin surface "agents" (Claude Code plugin.json vocabulary): bundles cannot register top-level agents; executor/architect/planner/critic are protected. Bind a sub-skill to an existing agent with the canonical "subskills" surface (frontmatter binds_to: one of executor|architect|planner|critic, phase, activation_arg) instead.`,

package/src/extensibility/runtime-skill-discovery.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
-import * as os from "node:os";
 import * as path from "node:path";
+import { getTrustedHomeDir } from "@gajae-code/utils";
 import { findRepoRoot } from "../capability/fs";
 import type { Skill as CapabilitySkill } from "../capability/skill";
 import type { SkillsSettings } from "../config/settings-schema";
@@ -47,7 +47,7 @@ export interface DiscoverRuntimeSkillsOptions {
 }
 
 function getRuntimeHome(): string {
-	return process.env.HOME || os.homedir();
+	return getTrustedHomeDir();
 }
 
 const DEFAULT_LIMIT = 20;

package/src/extensibility/skill-management.ts

@@ -13,9 +13,8 @@
  * preview/apply transaction and the UI itself are owned by #4291.
  */
 import * as fs from "node:fs/promises";
-import * as os from "node:os";
 import * as path from "node:path";
-import { parseFrontmatter } from "@gajae-code/utils";
+import { getTrustedHomeDir, parseFrontmatter } from "@gajae-code/utils";
 import { findRepoRoot } from "../capability/fs";
 import type { Skill as CapabilitySkill } from "../capability/skill";
 import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
@@ -97,7 +96,7 @@ export class SkillFrontmatterError extends Error {
 const BUILT_IN_SKILL_NAMES = new Set<string>(CANONICAL_GJC_WORKFLOW_SKILLS);
 
 function getRuntimeHome(): string {
-	return process.env.HOME || os.homedir();
+	return getTrustedHomeDir();
 }
 
 /** Ancestor directories from `cwd` (inclusive) up to `stop` (inclusive), excluding `home`. */

package/src/extensibility/skills.ts

@@ -1,11 +1,11 @@
 import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import { getProjectDir } from "@gajae-code/utils";
+import { getProjectDir, getTrustedHomeDir } from "@gajae-code/utils";
+import { findRepoRoot } from "../capability/fs";
 import { skillCapability } from "../capability/skill";
 import type { SourceMeta } from "../capability/types";
 import type { SkillsSettings } from "../config/settings";
 import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
-import { type Skill as CapabilitySkill, loadCapability } from "../discovery";
+import { type Skill as CapabilitySkill, getCapability } from "../discovery";
 import { compareSkillOrder, scanSkillsFromDir } from "../discovery/helpers";
 import type { SkillPromptDetails } from "../session/messages";
 import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
@@ -77,11 +77,12 @@ export interface LoadSkillsFromDirOptions {
 }
 
 export async function loadSkillsFromDir(options: LoadSkillsFromDirOptions): Promise<LoadSkillsResult> {
+	const home = getTrustedHomeDir();
 	const [rawProviderId, rawLevel] = options.source.split(":", 2);
 	const providerId = rawProviderId || "custom";
 	const level: "user" | "project" = rawLevel === "project" ? "project" : "user";
 	const result = await scanSkillsFromDir(
-		{ cwd: getProjectDir(), home: os.homedir(), repoRoot: null },
+		{ cwd: getProjectDir(), home, repoRoot: null },
 		{
 			dir: options.dir,
 			providerId,
@@ -108,6 +109,8 @@ export async function loadSkillsFromDir(options: LoadSkillsFromDirOptions): Prom
 export interface LoadSkillsOptions extends SkillsSettings {
 	/** Working directory for project-local skills. Default: getProjectDir() */
 	cwd?: string;
+	/** Explicit user home for skill discovery. Default: getTrustedHomeDir(). */
+	home?: string;
 }
 
 /**
@@ -137,6 +140,7 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	if (!enabled) {
 		return { skills: [], warnings: [] };
 	}
+	const home = options.home ?? getTrustedHomeDir();
 
 	const projectTrusted = resolveSkillScopeTrust(options, "project");
 	const userTrusted = resolveSkillScopeTrust(options, "user");
@@ -156,7 +160,11 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	// Use capability API to load all skills. `all` (rather than `items`) keeps
 	// shadowed duplicates so this function can apply the documented precedence
 	// itself: project scope beats user scope.
-	const result = await loadCapability<CapabilitySkill>(skillCapability.id, { cwd, disabledExtensions });
+	const nativeProvider = getCapability<CapabilitySkill>(skillCapability.id)?.providers.find(
+		provider => provider.id === "native",
+	);
+	if (!nativeProvider) throw new Error("Native skill provider is unavailable");
+	const result = await nativeProvider.load({ cwd, home, repoRoot: await findRepoRoot(cwd) });
 
 	const skillMap = new Map<string, Skill>();
 	const realPathSet = new Set<string>();
@@ -182,7 +190,7 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	// precedence. `all` is already in native provider order with project dirs
 	// before user dirs; a stable sort by level lifts every project item above
 	// every user item, giving: project `.gjc/skills` > user roots.
-	const filteredSkills = result.all
+	const filteredSkills = result.items
 		.filter(capSkill => {
 			if (!isSourceEnabled(capSkill._source)) return false;
 			if (disabledSkillNames.has(capSkill.name)) return false;
@@ -250,9 +258,9 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 
 	const customDirectoryResults = await Promise.all(
 		customDirectories.map(async dir => {
-			const expandedDir = expandTilde(dir);
+			const expandedDir = expandTilde(dir, home);
 			const scanResult = await scanSkillsFromDir(
-				{ cwd, home: os.homedir(), repoRoot: null },
+				{ cwd, home, repoRoot: null },
 				{
 					dir: expandedDir,
 					providerId: "custom",