cyber-agentkit 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,652 @@
+import { A as skillFoldersVerified, B as isRecord, C as userReferencesDir, D as adminSkillFolders, F as packageDir, H as stripJsonComments, I as detectHarness, L as installedPlugins, M as pluginManifestName, N as pluginManifestPaths, O as harnessSkillFolders, P as declaredDependencies, R as enabledPlugins, T as skillsIn, U as managedPolicyLocations, V as readText, b as projectReferencesDir, d as parseReferenceName, j as skillsDirectories, k as pluginSkillFolders, l as referenceNames, n as referenceImplementations, o as listReferences, r as checkReferences, s as searchReferences, t as whereReference, u as resolveReference, w as skillName, x as referenceLayers, y as defaultLayer, z as pluginStorage } from "./reference-where-BhymfNgA.js";
+import { join } from "node:path";
+import { homedir } from "node:os";
+//#region src/plugins/plugin-dependencies.ts
+/**
+* Whether a harness lets a plugin declare other plugins it depends on. Only Claude Code does, via
+* `dependencies` in `plugin.json` (E-CC-X1). The other harnesses' manifests have no such field
+* (E-CUR-X1, E-CODEX-X1, E-COPILOT-X1, E-OC-X1, E-KILO-X1, E-GEM-P4, E-QWEN-P3, E-VSC-X1,
+* E-CLINE-X1, E-CRUSH-X1, E-OH-X1, E-AUG-X1).
+*/
+function supportsPluginDependencies(harness) {
+	return harness === "claude-code";
+}
+//#endregion
+//#region src/dependencies/plugin-dependencies.ts
+/**
+* Read the `dependencies` array of a Claude Code `plugin.json`: `"name"`, `"name@marketplace"`, or
+* `{ name, marketplace, version }` entries (E-DEP-1, E-CC-X1). Entries of any other shape are skipped.
+*/
+function declaredPluginDependencies(manifest) {
+	const entries = isRecord(manifest) ? manifest.dependencies : void 0;
+	if (!Array.isArray(entries)) return [];
+	const dependencies = [];
+	for (const entry of entries) {
+		const raw = typeof entry === "string" ? entry : isRecord(entry) ? entry.name : void 0;
+		if (typeof raw !== "string" || raw === "") continue;
+		const [name, inline] = raw.split("@");
+		if (name === "") continue;
+		const object = isRecord(entry) ? entry : {};
+		const marketplace = nonEmpty(object.marketplace) ?? nonEmpty(inline);
+		const version = nonEmpty(object.version);
+		dependencies.push({
+			name,
+			...marketplace && { marketplace },
+			...version && { version }
+		});
+	}
+	return dependencies;
+}
+const nonEmpty = (value) => typeof value === "string" && value !== "" ? value : void 0;
+/** The extension namespaces a root `plugin.json` may author its dependency list under, newest first (E-DEP-6, E-DEP-7). */
+const extensionNamespaces = ["io.github.cyber-uni.plugin-manager", "org.cyberuni.universal-plugin"];
+/**
+* Read what the plugin at `pluginRoot` declares: `dependencies` under `extensions["io.github.cyber-uni.plugin-manager"]`,
+* else under `extensions["org.cyberuni.universal-plugin"]` in the root `plugin.json`, else `dependencies` in
+* `.claude-plugin/plugin.json` (E-DEP-1, E-DEP-6, E-DEP-7).
+*/
+async function readPluginDependencies(pluginRoot) {
+	const root = join(pluginRoot, "plugin.json");
+	const sources = [...extensionNamespaces.map((namespace) => ({
+		path: root,
+		pick: (manifest) => {
+			const extensions = isRecord(manifest) ? manifest.extensions : void 0;
+			return isRecord(extensions) ? extensions[namespace] : void 0;
+		}
+	})), {
+		path: join(pluginRoot, ".claude-plugin", "plugin.json"),
+		pick: (manifest) => manifest
+	}];
+	let error;
+	for (const { path, pick } of sources) try {
+		const text = await readText(path);
+		if (text === void 0) continue;
+		const dependencies = declaredPluginDependencies(pick(JSON.parse(stripJsonComments(text))));
+		if (dependencies.length > 0) return {
+			dependencies,
+			path
+		};
+	} catch (cause) {
+		error ??= `${path}: ${String(cause)}`;
+	}
+	return {
+		dependencies: [],
+		path: sources.at(-1)?.path ?? pluginRoot,
+		...error && { error }
+	};
+}
+const rank = {
+	enabled: 3,
+	installed: 2,
+	disabled: 1,
+	missing: 0,
+	unknown: 0
+};
+/**
+* Check which declared dependencies the harness has installed and enabled, and return the steps
+* that settle the rest. Nothing is installed.
+*/
+async function checkPluginDependencies(harness, options = {}) {
+	const read = options.dependencies ? {
+		dependencies: options.dependencies,
+		error: void 0
+	} : options.pluginRoot ? await readPluginDependencies(options.pluginRoot) : {
+		dependencies: [],
+		error: void 0
+	};
+	const [installed, enabled] = await Promise.all([installedPlugins(harness, options), enabledPlugins(harness, options)]);
+	const enablement = new Map(enabled.plugins.map((plugin) => [plugin.id, plugin.enabled]));
+	const dependencies = read.dependencies.map((dependency) => {
+		if (!installed.supported) return {
+			...dependency,
+			state: "unknown"
+		};
+		const ids = installed.plugins.map((plugin) => plugin.id).filter((id) => dependency.marketplace ? id === `${dependency.name}@${dependency.marketplace}` : id.split("@")[0] === dependency.name);
+		let best = {
+			...dependency,
+			state: "missing"
+		};
+		for (const id of new Set(ids)) {
+			const flag = enablement.get(id);
+			const state = flag === true ? "enabled" : flag === false ? "disabled" : "installed";
+			if (rank[state] > rank[best.state]) best = {
+				...dependency,
+				state,
+				id
+			};
+		}
+		return best;
+	});
+	const supported = supportsPluginDependencies(harness);
+	return {
+		harness,
+		supported,
+		autoResolved: supported,
+		dependencies,
+		steps: supported ? claudeCodeSteps(dependencies) : manualSteps(harness, read.dependencies),
+		...read.error && { error: read.error },
+		research: [
+			"E-DEP-1",
+			"E-DEP-2",
+			"E-DEP-3",
+			"E-DEP-4",
+			"E-DEP-5",
+			"E-DEP-6",
+			"E-DEP-7",
+			"E-CC-X1"
+		]
+	};
+}
+const label = (dependency) => dependency.marketplace ? `${dependency.name}@${dependency.marketplace}` : dependency.name;
+/** E-DEP-2: `plugin install` installs missing dependencies; E-DEP-3: cross-marketplace needs a root allow-list. */
+function claudeCodeSteps(dependencies) {
+	const steps = [];
+	for (const dependency of dependencies) if (dependency.state === "missing" || dependency.state === "unknown") {
+		steps.push(`Install ${label(dependency)}: claude plugin install ${label(dependency)}`);
+		if (dependency.marketplace) steps.push(`If ${label(dependency)} is not in the declaring plugin's marketplace, that marketplace's root must list ${dependency.marketplace} in allowCrossMarketplaceDependenciesOn, or you must already have it enabled.`);
+	} else if (dependency.state === "disabled") steps.push(`Enable ${dependency.id ?? label(dependency)}: set it to true in enabledPlugins.`);
+	if (steps.length > 0) steps.push("Run /reload-plugins.");
+	return steps;
+}
+/** E-DEP-4, E-DEP-5, E-CC-X1: no other harness's manifest declares dependencies. */
+function manualSteps(harness, dependencies) {
+	if (dependencies.length === 0) return [];
+	return [`${harness} has no plugin dependency field, so nothing is resolved for you. Install and enable each plugin yourself.`, ...dependencies.map((dependency) => `Install ${dependency.name}${dependency.marketplace ? ` from ${dependency.marketplace}` : ""} through ${harness}'s plugin install flow, then enable it.`)];
+}
+//#endregion
+//#region src/harness/harness-id.ts
+const harnessIds = [
+	"claude-code",
+	"cursor",
+	"codex",
+	"copilot-cli",
+	"opencode",
+	"kilo",
+	"gemini-cli",
+	"qwen-code",
+	"vscode-copilot",
+	"cline",
+	"crush",
+	"openhands",
+	"augment"
+];
+//#endregion
+//#region src/headless/headless-invocation.ts
+const claudeUsage = {
+	event: "result",
+	tokens: "usage",
+	costUsd: "total_cost_usd",
+	accumulate: "last"
+};
+const qwenUsage = {
+	event: "result",
+	tokens: "usage",
+	accumulate: "last"
+};
+const unverified = "has a documented one-shot mode, but its flags were not read directly from a vendor page, so they are not encoded";
+/**
+* How to run a harness non-interactively on one prompt: the command, how to choose the model and
+* permission mode, the output formats and where usage appears in them, the transcript location,
+* and the exit codes.
+*
+* Returns `supported: false` for Copilot in VS Code, which documents no headless mode (E-VSC-H1).
+* Returns `supported: 'unknown'` for OpenCode, Kilo Code, Cline, Crush, OpenHands, and the Auggie
+* CLI: each has a one-shot mode, but the research read it only through a summarizing fetch or from
+* source (E-OC-H1, E-KILO-H1, E-CLINE-H1, E-CRUSH-H1, E-OH-H1, E-AUG-H1).
+*/
+function headlessInvocation(harness) {
+	switch (harness) {
+		case "claude-code": return {
+			harness,
+			supported: true,
+			executable: "claude",
+			oneShot: ["-p"],
+			modelFlag: "--model",
+			permission: {
+				flag: "--permission-mode",
+				values: [
+					"acceptEdits",
+					"auto",
+					"bypassPermissions",
+					"manual",
+					"dontAsk",
+					"plan"
+				],
+				unattended: ["--permission-mode", "bypassPermissions"]
+			},
+			outputFormats: [
+				{
+					name: "text",
+					args: []
+				},
+				{
+					name: "json",
+					args: ["--output-format", "json"],
+					usage: claudeUsage
+				},
+				{
+					name: "stream-json",
+					args: [
+						"--output-format",
+						"stream-json",
+						"--verbose"
+					],
+					usage: claudeUsage
+				}
+			],
+			transcript: {
+				path: "~/.claude/projects/<project>/<session-id>.jsonl",
+				baseDirEnv: "CLAUDE_CONFIG_DIR",
+				disable: ["--no-session-persistence"]
+			},
+			exitCodes: [{
+				code: 0,
+				meaning: "success"
+			}, {
+				code: 143,
+				meaning: "terminated by SIGTERM"
+			}],
+			research: [
+				"E-CC-H1",
+				"E-CC-H2",
+				"E-CC-H3",
+				"E-CC-H4",
+				"E-CC-H5",
+				"E-CC-H6"
+			]
+		};
+		case "codex": return {
+			harness,
+			supported: true,
+			executable: "codex",
+			oneShot: ["exec"],
+			modelFlag: "--model",
+			permission: {
+				flag: "--sandbox",
+				values: [
+					"read-only",
+					"workspace-write",
+					"danger-full-access"
+				],
+				unattended: ["--dangerously-bypass-approvals-and-sandbox"]
+			},
+			outputFormats: [{
+				name: "text",
+				args: []
+			}, {
+				name: "jsonl",
+				args: ["--json"],
+				usage: {
+					event: "turn.completed",
+					tokens: "usage",
+					accumulate: "sum"
+				}
+			}],
+			transcript: {
+				path: "~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-<timestamp>-<thread-id>.jsonl",
+				baseDirEnv: "CODEX_HOME",
+				disable: ["--ephemeral"]
+			},
+			exitCodes: [{
+				code: 0,
+				meaning: "success"
+			}, {
+				code: 1,
+				meaning: "the run reported a fatal error, or the prompt or options were invalid"
+			}],
+			research: [
+				"E-CODEX-H1",
+				"E-CODEX-H2",
+				"E-CODEX-H3",
+				"E-CODEX-H4",
+				"E-CODEX-H5"
+			]
+		};
+		case "copilot-cli": return {
+			harness,
+			supported: true,
+			executable: "copilot",
+			oneShot: [],
+			promptFlag: "-p",
+			modelFlag: "--model",
+			permission: {
+				values: [],
+				unattended: ["--allow-all"]
+			},
+			outputFormats: [{
+				name: "text",
+				args: []
+			}, {
+				name: "json",
+				args: ["--output-format", "json"]
+			}],
+			transcript: {
+				path: "~/.copilot/session-state/<session-id>/events.jsonl",
+				baseDirEnv: "COPILOT_HOME"
+			},
+			exitCodes: [],
+			research: [
+				"E-COPILOT-H1",
+				"E-COPILOT-H2",
+				"E-COPILOT-H3"
+			]
+		};
+		case "cursor": return {
+			harness,
+			supported: true,
+			executable: "cursor-agent",
+			oneShot: ["-p"],
+			modelFlag: "--model",
+			permission: {
+				values: [],
+				unattended: ["--force"]
+			},
+			outputFormats: [
+				{
+					name: "text",
+					args: []
+				},
+				{
+					name: "json",
+					args: ["--output-format", "json"]
+				},
+				{
+					name: "stream-json",
+					args: ["--output-format", "stream-json"]
+				}
+			],
+			exitCodes: [{
+				code: 0,
+				meaning: "success"
+			}, {
+				code: 1,
+				meaning: "failure"
+			}],
+			research: [
+				"E-CUR-H1",
+				"E-CUR-H2",
+				"E-CUR-H3"
+			]
+		};
+		case "gemini-cli": return {
+			harness,
+			supported: true,
+			executable: "gemini",
+			oneShot: [],
+			promptFlag: "-p",
+			modelFlag: "--model",
+			permission: {
+				flag: "--approval-mode",
+				values: [
+					"default",
+					"auto_edit",
+					"yolo",
+					"plan"
+				],
+				unattended: ["--approval-mode", "yolo"]
+			},
+			outputFormats: [
+				{
+					name: "text",
+					args: []
+				},
+				{
+					name: "json",
+					args: ["--output-format", "json"],
+					usage: {
+						tokens: "stats",
+						accumulate: "last"
+					}
+				},
+				{
+					name: "stream-json",
+					args: ["--output-format", "stream-json"],
+					usage: {
+						event: "result",
+						tokens: "stats",
+						accumulate: "last"
+					}
+				}
+			],
+			transcript: { path: "~/.gemini/tmp/<project_hash>/chats/" },
+			exitCodes: [
+				{
+					code: 0,
+					meaning: "success"
+				},
+				{
+					code: 1,
+					meaning: "general error or API failure"
+				},
+				{
+					code: 42,
+					meaning: "input error: an invalid prompt or arguments"
+				},
+				{
+					code: 53,
+					meaning: "turn limit exceeded"
+				}
+			],
+			research: [
+				"E-GEM-H1",
+				"E-GEM-H2",
+				"E-GEM-H3"
+			]
+		};
+		case "qwen-code": return {
+			harness,
+			supported: true,
+			executable: "qwen",
+			oneShot: [],
+			promptFlag: "-p",
+			modelFlag: "--model",
+			permission: {
+				flag: "--approval-mode",
+				values: [
+					"plan",
+					"default",
+					"auto-edit",
+					"auto",
+					"yolo"
+				],
+				unattended: ["--approval-mode", "yolo"]
+			},
+			outputFormats: [
+				{
+					name: "text",
+					args: []
+				},
+				{
+					name: "json",
+					args: ["--output-format", "json"],
+					usage: qwenUsage
+				},
+				{
+					name: "stream-json",
+					args: ["--output-format", "stream-json"],
+					usage: qwenUsage
+				}
+			],
+			transcript: { path: "~/.qwen/projects/<sanitized-cwd>/chats/" },
+			exitCodes: [
+				{
+					code: 53,
+					meaning: "turn limit exceeded"
+				},
+				{
+					code: 55,
+					meaning: "tool-call or wall-time budget exceeded"
+				},
+				{
+					code: 130,
+					meaning: "interrupted by SIGINT"
+				}
+			],
+			research: ["E-QWEN-H1", "E-QWEN-H2"]
+		};
+		case "vscode-copilot": return {
+			harness,
+			supported: false,
+			reason: "agent mode runs inside the editor; the docs point terminal use to the Copilot CLI",
+			research: ["E-VSC-H1"]
+		};
+		case "opencode": return {
+			harness,
+			supported: "unknown",
+			reason: `\`opencode run\` ${unverified}`,
+			research: ["E-OC-H1"]
+		};
+		case "kilo": return {
+			harness,
+			supported: "unknown",
+			reason: `\`kilo run\` ${unverified}`,
+			research: ["E-KILO-H1"]
+		};
+		case "cline": return {
+			harness,
+			supported: "unknown",
+			reason: `the Cline CLI ${unverified}`,
+			research: ["E-CLINE-H1"]
+		};
+		case "crush": return {
+			harness,
+			supported: "unknown",
+			reason: `\`crush run\` ${unverified}`,
+			research: ["E-CRUSH-H1"]
+		};
+		case "openhands": return {
+			harness,
+			supported: "unknown",
+			reason: `\`openhands --headless\` ${unverified}`,
+			research: ["E-OH-H1"]
+		};
+		case "augment": return {
+			harness,
+			supported: "unknown",
+			reason: `\`auggie --print\` ${unverified}`,
+			research: ["E-AUG-H1"]
+		};
+	}
+}
+/**
+* The command line for one headless run, built from `headlessInvocation()`. It does not run it.
+*
+* Returns `undefined` when the harness's headless mode is not supported or not verified. Throws
+* when `outputFormat` names a format the harness lacks, or `permission` names a mode the harness
+* has no flag for.
+*/
+function headlessCommand(harness, options) {
+	const mode = headlessInvocation(harness);
+	if (mode.supported !== true) return void 0;
+	const args = [...mode.oneShot];
+	if (options.model !== void 0) args.push(mode.modelFlag, options.model);
+	if (options.permission === "unattended") args.push(...mode.permission.unattended);
+	else if (options.permission !== void 0) {
+		const { flag, values } = mode.permission;
+		if (flag === void 0 || !values.includes(options.permission)) throw new Error(`${harness} has no permission mode "${options.permission}"`);
+		args.push(flag, options.permission);
+	}
+	if (options.outputFormat !== void 0) {
+		const format = mode.outputFormats.find((f) => f.name === options.outputFormat);
+		if (format === void 0) throw new Error(`${harness} has no output format "${options.outputFormat}"`);
+		args.push(...format.args);
+	}
+	if (mode.promptFlag === void 0) args.push(options.prompt);
+	else args.push(mode.promptFlag, options.prompt);
+	return {
+		executable: mode.executable,
+		args
+	};
+}
+//#endregion
+//#region src/references/load-reference.ts
+/**
+* Resolves one reference for `root` the way `reference show` does, returning the full record: every
+* field `show` prints with `--metadata` and `--trace`. A name that is not a reference name comes back
+* `invalid`, and one no contribution answers `missing`; neither throws.
+*/
+async function loadReference(name, options) {
+	const layers = await referenceLayers({
+		...options,
+		home: options.home ?? homedir(),
+		platform: options.platform ?? process.platform
+	});
+	return resolveReference(name, layers);
+}
+//#endregion
+//#region src/skills/skill-invocation.ts
+/**
+* How a user invokes a plugin's skill in a harness.
+*
+* Claude Code, Codex, and Copilot in VS Code namespace by plugin; elsewhere two plugins' skills with
+* the same name collide. Codex names a plugin skill `<plugin>:<skill>`, and its `$` mention takes the
+* whole name (E-SR-CODEX-5, E-SR-CODEX-18). Copilot CLI lists `<plugin>:<skill>` only while two
+* enabled plugins share the name (E-SR-COPILOT-8); whether that form can be typed is not verified,
+* so it returns the bare `/<skill>`.
+*
+* Kilo Code returns `/<skill>` in both the CLI and the VS Code extension; when a custom command or
+* MCP prompt has the same name, the skill is typed `/<skill>:skill` instead (E-KILO-S3).
+*
+* OpenCode returns `/<skill>` too, but when a built-in (`init`, `review`), config command, or MCP
+* prompt has the same name, that one wins and the skill has no command (E-OC-S3).
+*
+* Returns `undefined` for Gemini CLI, Qwen Code, and Crush, which document no typed form: the model
+* loads a skill through a tool call when its description matches the task (E-GEM-S2, E-QWEN-S1,
+* E-CRUSH-S1). Crush can also list a skill in its command
+* palette, which is picked, not typed (E-CRUSH-S2). OpenHands triggers skills from the model too;
+* only a plugin's commands take a `/<plugin>:<command>` form (E-OH-S2, E-OH-S3).
+*
+* Also returns `undefined` for the Auggie CLI: a plugin skill's internal name is `<plugin>:<skill>`,
+* but what the user types for it is not confirmed (E-AUG-S3).
+*/
+function skillInvocation(harness, { plugin, skill }) {
+	switch (harness) {
+		case "claude-code": return {
+			text: `/${plugin}:${skill}`,
+			namespaced: true,
+			research: "E-CC-S1"
+		};
+		case "cursor": return {
+			text: `/${skill}`,
+			namespaced: false,
+			research: "E-CUR-S1"
+		};
+		case "codex": return {
+			text: `$${plugin}:${skill}`,
+			namespaced: true,
+			research: "E-SR-CODEX-18"
+		};
+		case "copilot-cli": return {
+			text: `/${skill}`,
+			namespaced: false,
+			research: "E-COPILOT-S6"
+		};
+		case "vscode-copilot": return {
+			text: `/${plugin}:${skill}`,
+			namespaced: true,
+			research: "E-VSC-S1"
+		};
+		case "cline": return {
+			text: `/${skill}`,
+			namespaced: false,
+			research: "E-CLINE-S2"
+		};
+		case "kilo": return {
+			text: `/${skill}`,
+			namespaced: false,
+			research: "E-KILO-S3"
+		};
+		case "opencode": return {
+			text: `/${skill}`,
+			namespaced: false,
+			research: "E-OC-S3"
+		};
+		case "gemini-cli":
+		case "qwen-code":
+		case "crush":
+		case "openhands":
+		case "augment": return;
+	}
+}
+//#endregion
+export { adminSkillFolders, checkPluginDependencies, checkReferences, declaredDependencies, declaredPluginDependencies, defaultLayer, detectHarness, enabledPlugins, harnessIds, harnessSkillFolders, headlessCommand, headlessInvocation, installedPlugins, listReferences, loadReference, managedPolicyLocations, packageDir, parseReferenceName, pluginManifestName, pluginManifestPaths, pluginSkillFolders, pluginStorage, projectReferencesDir, readPluginDependencies, referenceImplementations, referenceLayers, referenceNames, resolveReference, searchReferences, skillFoldersVerified, skillInvocation, skillName, skillsDirectories, skillsIn, supportsPluginDependencies, userReferencesDir, whereReference };