@gajae-code/coding-agent 0.2.2 → 0.2.4

package/src/tools/index.ts

@@ -1,5 +1,5 @@
 import type { AgentTelemetryConfig, AgentTool } from "@gajae-code/agent-core";
-import type { ToolChoice } from "@gajae-code/ai";
+import type { Model, ToolChoice } from "@gajae-code/ai";
 import { $env, $flag, logger } from "@gajae-code/utils";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
@@ -12,10 +12,12 @@ import type { HindsightSessionState } from "../hindsight/state";
 import { LspTool } from "../lsp";
 import type { PlanModeState } from "../plan-mode/state";
 import type { AgentRegistry } from "../registry/agent-registry";
+import type { ForkContextSeed, ForkContextSeedOptions } from "../session/agent-session";
 import type { ArtifactManager } from "../session/artifacts";
 import type { ClientBridge } from "../session/client-bridge";
 import type { CustomMessage } from "../session/messages";
 import type { ToolChoiceQueue } from "../session/tool-choice-queue";
+import type { SkillActiveEntry } from "../skill-state/active-state";
 import { TaskTool } from "../task";
 import type { AgentOutputManager } from "../task/output-manager";
 import type { DiscoverableTool, DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
@@ -47,6 +49,7 @@ import { ResolveTool } from "./resolve";
 import { reportFindingTool } from "./review";
 import { SearchTool } from "./search";
 import { SearchToolBm25Tool } from "./search-tool-bm25";
+import { SkillTool } from "./skill";
 import { loadSshTool } from "./ssh";
 import { SubagentTool } from "./subagent";
 import { type TodoPhase, TodoWriteTool } from "./todo-write";
@@ -84,6 +87,7 @@ export * from "./resolve";
 export * from "./review";
 export * from "./search";
 export * from "./search-tool-bm25";
+export * from "./skill";
 export * from "./ssh";
 export * from "./subagent";
 export * from "./todo-write";
@@ -122,6 +126,12 @@ export interface ToolSession {
 	workspaceTree?: WorkspaceTree;
 	/** Pre-loaded skills */
 	skills?: Skill[];
+	/** Currently executing skill prompt, when this tool session is inside one. */
+	getActiveSkillState?: () => Pick<SkillActiveEntry, "skill" | "session_id"> | undefined;
+	/** Get the active skill prompt's current phase so the skill tool can apply
+	 *  its terminal-phase chain guard. Returns the raw phase string or undefined
+	 *  when no active skill (or accessor) is available. */
+	getActiveSkillPhase?: () => string | undefined;
 	/** Pre-loaded prompt templates */
 	promptTemplates?: PromptTemplate[];
 	/** Whether LSP integrations are enabled */
@@ -164,6 +174,8 @@ export interface ToolSession {
 	getSessionSpawns: () => string | null;
 	/** Get resolved model string if explicitly set for this session */
 	getModelString?: () => string | undefined;
+	/** Current model, when selected. */
+	model?: Model;
 	/** Get the current session model string, regardless of how it was chosen */
 	getActiveModelString?: () => string | undefined;
 	/** Auth storage for passing to subagents (avoids re-discovery) */
@@ -246,9 +258,17 @@ export interface ToolSession {
 
 	/** Queue a hidden message to be injected at the next agent turn. */
 	queueDeferredMessage?(message: CustomMessage): void;
+	/** Dispatch a custom message through the active session. Used by the `skill`
+	 *  tool to dispatch another skill prompt same-turn after recording a handoff. */
+	sendCustomMessage?(
+		message: Pick<CustomMessage, "customType" | "content" | "display" | "details" | "attribution">,
+		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+	): Promise<void>;
 	/** Get the active OpenTelemetry config so subagent dispatch can forward
 	 *  the parent's tracer/hooks with the subagent's own identity stamped. */
 	getTelemetry?: () => AgentTelemetryConfig | undefined;
+	/** Build a sanitized fork-context seed for task subagents. */
+	buildForkContextSeed?: (options: ForkContextSeedOptions) => Promise<ForkContextSeed>;
 }
 
 export type ToolFactory = (session: ToolSession) => Tool | null | Promise<Tool | null>;
@@ -308,6 +328,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	retain: HindsightRetainTool.createIf,
 	recall: HindsightRecallTool.createIf,
 	reflect: HindsightReflectTool.createIf,
+	skill: SkillTool.createIf,
 	goal: s => new GoalTool(s),
 };
 
@@ -464,6 +485,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		// search_tool_bm25 is allowed when either legacy mcp.discoveryMode or new tools.discoveryMode is active.
 		if (name === "search_tool_bm25") return discoveryActive;
 		if (name === "calc") return session.settings.get("calc.enabled");
+		if (name === "skill") return session.settings.get("skill.enabled");
 		if (name === "browser") return session.settings.get("browser.enabled");
 		if (name === "checkpoint" || name === "rewind") return session.settings.get("checkpoint.enabled");
 		if (name === "irc") {

package/src/tools/skill.ts

@@ -0,0 +1,153 @@
+/**
+ * Skill Tool — agent-initiated skill chaining.
+ *
+ * Lets the agent hand off to another available skill in the current turn. The
+ * callee's SKILL.md is dispatched through the same custom-message path used by
+ * `/skill:<name>` typing, as a user-attribution message delivered same-turn
+ * (without `deliverAs: "nextTurn"`). Before dispatch, the tool calls
+ * `gjc state <caller> handoff --to <callee>` in-process via the state-runtime
+ * function so caller and callee mode-states plus `skill-active-state.json`
+ * transition atomically.
+ *
+ * Chaining is refused unless the caller's `current_phase` is in
+ * `{complete, completed, handoff, failed, cancelled, canceled, inactive}`. The
+ * agent declares readiness either by writing `current_phase: "handoff"` to its
+ * mode-state or by running the handoff verb directly.
+ */
+
+import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
+import { prompt, untilAborted } from "@gajae-code/utils";
+import * as z from "zod/v4";
+import { buildSkillPromptMessage } from "../extensibility/skills";
+import { runNativeStateCommand } from "../gjc-runtime/state-runtime";
+import skillDescription from "../prompts/tools/skill.md" with { type: "text" };
+import { SKILL_PROMPT_MESSAGE_TYPE } from "../session/messages";
+import type { ToolSession } from ".";
+import { ToolError } from "./tool-errors";
+
+const TERMINAL_PHASES = new Set(["complete", "completed", "handoff", "failed", "cancelled", "canceled", "inactive"]);
+
+const skillSchema = z.object({
+	name: z.string().describe("skill name as it appears in /skill:<name>"),
+	args: z.string().describe("argument string passed to the skill").optional(),
+});
+
+function normalizeSkillName(name: string | undefined): string {
+	return (name ?? "").trim();
+}
+
+type SkillToolInput = z.infer<typeof skillSchema>;
+
+export interface SkillToolDetails {
+	name: string;
+	path: string;
+	args?: string;
+	lineCount: number;
+}
+
+export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails> {
+	readonly name = "skill";
+	readonly label = "Skill";
+	readonly summary = "Chain into another available skill in the current turn";
+	readonly loadMode = "discoverable";
+	readonly description: string;
+	readonly parameters = skillSchema;
+	readonly strict = true;
+
+	readonly #session: ToolSession;
+
+	constructor(session: ToolSession) {
+		this.#session = session;
+		this.description = prompt.render(skillDescription);
+	}
+
+	static createIf(session: ToolSession): SkillTool | null {
+		// The tool can only chain when the session can deliver the same-turn
+		// custom message. Without `sendCustomMessage` (e.g. minimal tool
+		// harnesses in tests) there is nothing useful to do.
+		if (!session.sendCustomMessage) return null;
+		const skills = session.skills ?? [];
+		if (skills.length === 0) return null;
+		return new SkillTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		input: SkillToolInput,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<SkillToolDetails>> {
+		return untilAborted(signal, async () => {
+			const sendCustomMessage = this.#session.sendCustomMessage;
+			if (!sendCustomMessage) {
+				throw new ToolError("skill tool: session has no custom-message bridge");
+			}
+			const skills = this.#session.skills ?? [];
+			const requestedName = normalizeSkillName(input.name);
+			if (!requestedName) {
+				throw new ToolError("skill tool: `name` is required");
+			}
+			const activeState = this.#session.getActiveSkillState?.();
+			const activeSkill = normalizeSkillName(activeState?.skill);
+			if (activeSkill && requestedName === activeSkill) {
+				throw new ToolError(
+					`skill tool: refusing to chain into currently active skill "${requestedName}". Follow the active skill instructions instead of invoking it recursively.`,
+				);
+			}
+
+			const skill = skills.find(s => s.name === requestedName);
+			if (!skill) {
+				const available = skills.map(s => s.name).sort();
+				const hint = available.length > 0 ? ` Available: ${available.join(", ")}` : "";
+				throw new ToolError(`skill tool: unknown skill "${requestedName}".${hint}`);
+			}
+
+			// Phase guard + atomic handoff. Only runs when transitioning between
+			// distinct skills (same-skill recursion was already refused above).
+			if (activeSkill) {
+				const phase = (this.#session.getActiveSkillPhase?.() ?? "running").trim().toLowerCase();
+				if (!TERMINAL_PHASES.has(phase)) {
+					throw new ToolError(
+						`skill tool: refusing to chain from "${activeSkill}" (phase=${phase}) into "${requestedName}". Finalize the current skill (gjc state ${activeSkill} write --input '{"current_phase":"handoff"}' --json) or run gjc state ${activeSkill} handoff --to ${requestedName} --json directly before chaining.`,
+					);
+				}
+				const cwd = this.#session.cwd;
+				const sessionId = activeState?.session_id?.trim();
+				const handoffArgs = ["handoff", "--mode", activeSkill, "--to", requestedName, "--json"];
+				if (sessionId) {
+					handoffArgs.push("--session-id", sessionId);
+				}
+				const handoff = await runNativeStateCommand(handoffArgs, cwd);
+				if (handoff.status !== 0) {
+					throw new ToolError(
+						`skill tool: handoff failed (status=${handoff.status}): ${(handoff.stderr ?? "").trim() || "no detail"}`,
+					);
+				}
+			}
+
+			const args = (input.args ?? "").trim();
+			const built = await buildSkillPromptMessage(skill, args);
+
+			await sendCustomMessage(
+				{
+					customType: SKILL_PROMPT_MESSAGE_TYPE,
+					content: built.message,
+					display: true,
+					details: built.details,
+					attribution: "user",
+				},
+				{ triggerTurn: false },
+			);
+
+			const summary = args ? `Handed off to /skill:${skill.name} ${args}.` : `Handed off to /skill:${skill.name}.`;
+			return {
+				content: [{ type: "text", text: summary }],
+				details: {
+					name: skill.name,
+					path: skill.filePath,
+					args: args || undefined,
+					lineCount: built.details.lineCount,
+				},
+			};
+		});
+	}
+}

package/src/utils/changelog.ts

@@ -1,4 +1,5 @@
 import { isEnoent, logger } from "@gajae-code/utils";
+import CHANGELOG_TEXT from "../../CHANGELOG.md" with { type: "text" };
 
 export interface ChangelogEntry {
 	major: number;
@@ -8,58 +9,67 @@ export interface ChangelogEntry {
 }
 
 /**
- * Parse changelog entries from CHANGELOG.md
- * Scans for ## lines and collects content until next ## or EOF
+ * Parse changelog entries from a CHANGELOG.md text body.
+ * Scans for ## lines and collects content until next ## or EOF.
+ * Pure and synchronous so it can be reused by the embedded display path.
  */
-export async function parseChangelog(changelogPath: string): Promise<ChangelogEntry[]> {
-	try {
-		const content = await Bun.file(changelogPath).text();
-		const lines = content.split("\n");
-		const entries: ChangelogEntry[] = [];
+export function parseChangelogContent(content: string): ChangelogEntry[] {
+	const lines = content.split("\n");
+	const entries: ChangelogEntry[] = [];
 
-		let currentLines: string[] = [];
-		let currentVersion: { major: number; minor: number; patch: number } | null = null;
+	let currentLines: string[] = [];
+	let currentVersion: { major: number; minor: number; patch: number } | null = null;
 
-		for (const line of lines) {
-			// Check if this is a version header (## [x.y.z] ...)
-			if (line.startsWith("## ")) {
-				// Save previous entry if exists
-				if (currentVersion && currentLines.length > 0) {
-					entries.push({
-						...currentVersion,
-						content: currentLines.join("\n").trim(),
-					});
-				}
+	for (const line of lines) {
+		// Check if this is a version header (## [x.y.z] ...)
+		if (line.startsWith("## ")) {
+			// Save previous entry if exists
+			if (currentVersion && currentLines.length > 0) {
+				entries.push({
+					...currentVersion,
+					content: currentLines.join("\n").trim(),
+				});
+			}
 
-				// Try to parse version from this line
-				const versionMatch = line.match(/##\s+\[?(\d+)\.(\d+)\.(\d+)\]?/);
-				if (versionMatch) {
-					currentVersion = {
-						major: Number.parseInt(versionMatch[1], 10),
-						minor: Number.parseInt(versionMatch[2], 10),
-						patch: Number.parseInt(versionMatch[3], 10),
-					};
-					currentLines = [line];
-				} else {
-					// Reset if we can't parse version
-					currentVersion = null;
-					currentLines = [];
-				}
-			} else if (currentVersion) {
-				// Collect lines for current version
-				currentLines.push(line);
+			// Try to parse version from this line
+			const versionMatch = line.match(/##\s+\[?(\d+)\.(\d+)\.(\d+)\]?/);
+			if (versionMatch) {
+				currentVersion = {
+					major: Number.parseInt(versionMatch[1], 10),
+					minor: Number.parseInt(versionMatch[2], 10),
+					patch: Number.parseInt(versionMatch[3], 10),
+				};
+				currentLines = [line];
+			} else {
+				// Reset if we can't parse version
+				currentVersion = null;
+				currentLines = [];
 			}
+		} else if (currentVersion) {
+			// Collect lines for current version
+			currentLines.push(line);
 		}
+	}
 
-		// Save last entry
-		if (currentVersion && currentLines.length > 0) {
-			entries.push({
-				...currentVersion,
-				content: currentLines.join("\n").trim(),
-			});
-		}
+	// Save last entry
+	if (currentVersion && currentLines.length > 0) {
+		entries.push({
+			...currentVersion,
+			content: currentLines.join("\n").trim(),
+		});
+	}
+
+	return entries;
+}
 
-		return entries;
+/**
+ * Parse changelog entries from a CHANGELOG.md file on disk.
+ * Returns [] on ENOENT; logs and returns [] on other read/parse errors.
+ */
+export async function parseChangelog(changelogPath: string): Promise<ChangelogEntry[]> {
+	try {
+		const content = await Bun.file(changelogPath).text();
+		return parseChangelogContent(content);
 	} catch (error) {
 		if (isEnoent(error)) {
 			return [];
@@ -69,6 +79,19 @@ export async function parseChangelog(changelogPath: string): Promise<ChangelogEn
 	}
 }
 
+/**
+ * Return changelog entries from the CHANGELOG.md that shipped with this binary.
+ *
+ * The text is embedded at build time via `with { type: "text" }`, so the
+ * displayed changelog is deterministic across compiled binaries, source-tree
+ * dev runs, and `GJC_PACKAGE_DIR` / `PI_PACKAGE_DIR` overrides (which scope to
+ * optional package assets like docs/examples and do not influence the
+ * binary-identity changelog).
+ */
+export function getDisplayChangelogEntries(): ChangelogEntry[] {
+	return parseChangelogContent(CHANGELOG_TEXT);
+}
+
 /**
  * Compare versions. Returns: -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
  */