refactor(agent): rename resource formatting helpers

packages/agent/src/harness/agent-harness.ts

@@ -4,8 +4,8 @@ import { Agent } from "../agent.js";
 import type { AgentEvent, AgentMessage, AgentTool, ThinkingLevel } from "../types.js";
 import { collectEntriesForBranchSummary, generateBranchSummary } from "./compaction/branch-summarization.js";
 import { compact, DEFAULT_COMPACTION_SETTINGS, prepareCompaction } from "./compaction/compaction.js";
-import { expandPromptTemplate } from "./prompt-templates.js";
+import { formatPromptTemplateInvocation } from "./prompt-templates.js";
-import { expandSkillCommand } from "./skills.js";
+import { formatSkillInvocation } from "./skills.js";
 import type {
 	AbortResult,
 	AgentHarnessContext,
@@ -335,14 +335,14 @@ export class AgentHarness {
 		const resources = await this.resolveResources();
 		const skill = (resources.skills ?? []).find((candidate) => candidate.name === name);
 		if (!skill) throw new Error(`Unknown skill: ${name}`);
-		return await this.prompt(expandSkillCommand(skill, additionalInstructions));
+		return await this.prompt(formatSkillInvocation(skill, additionalInstructions));
 	}
 
 	async promptFromTemplate(name: string, args: string[] = []): Promise<AssistantMessage> {
 		const resources = await this.resolveResources();
 		const template = (resources.promptTemplates ?? []).find((candidate) => candidate.name === name);
 		if (!template) throw new Error(`Unknown prompt template: ${name}`);
-		return await this.prompt(expandPromptTemplate(template, args));
+		return await this.prompt(formatPromptTemplateInvocation(template, args));
 	}
 
 	steer(message: AgentMessage): void {

packages/agent/src/harness/prompt-templates.ts

@@ -211,7 +211,7 @@ export function substituteArgs(content: string, args: string[]): string {
 	return result;
 }
 
-/** Expand a prompt template with positional command arguments. */
+/** Format a prompt template invocation with positional arguments. */
-export function expandPromptTemplate(template: PromptTemplate, args: string[] = []): string {
+export function formatPromptTemplateInvocation(template: PromptTemplate, args: string[] = []): string {
 	return substituteArgs(template.content, args);
 }

packages/agent/src/harness/skills.ts

@@ -25,8 +25,8 @@ interface SkillFrontmatter {
 	[key: string]: unknown;
 }
 
-/** Expand a skill into a prompt, optionally appending additional user instructions. */
+/** Format a skill invocation prompt, optionally appending additional user instructions. */
-export function expandSkillCommand(skill: Skill, additionalInstructions?: string): string {
+export function formatSkillInvocation(skill: Skill, additionalInstructions?: string): string {
 	const skillBlock = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${dirnameEnvPath(skill.filePath)}.\n\n${skill.content}\n</skill>`;
 	return additionalInstructions ? `${skillBlock}\n\n${additionalInstructions}` : skillBlock;
 }

packages/agent/src/harness/types.ts

@@ -22,7 +22,7 @@ export interface PromptTemplate {
 	name: string;
 	/** Optional description for command lists or autocomplete. */
 	description?: string;
-	/** Template content. Argument placeholders are expanded by `expandPromptTemplate`. */
+	/** Template content. Argument placeholders are expanded by `formatPromptTemplateInvocation`. */
 	content: string;
 }
 

packages/agent/test/harness/prompt-templates.test.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { NodeExecutionEnv } from "../../src/harness/execution-env.js";
 import {
-	expandPromptTemplate,
+	formatPromptTemplateInvocation,
 	loadPromptTemplates,
 	loadSourcedPromptTemplates,
 } from "../../src/harness/prompt-templates.js";
@@ -80,10 +80,10 @@ describe("loadPromptTemplates", () => {
 	});
 });
 
-describe("expandPromptTemplate", () => {
+describe("formatPromptTemplateInvocation", () => {
 	it("substitutes command arguments", () => {
 		const content = "$1 $" + "{@:2} $ARGUMENTS";
-		expect(expandPromptTemplate({ name: "one", content }, ["hello world", "test"])).toBe(
+		expect(formatPromptTemplateInvocation({ name: "one", content }, ["hello world", "test"])).toBe(
 			"hello world test hello world test",
 		);
 	});

packages/agent/test/harness/resource-expansion.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, it } from "vitest";
-import { expandPromptTemplate } from "../../src/harness/prompt-templates.js";
+import { formatPromptTemplateInvocation } from "../../src/harness/prompt-templates.js";
-import { expandSkillCommand } from "../../src/harness/skills.js";
+import { formatSkillInvocation } from "../../src/harness/skills.js";
 
-describe("resource expansion helpers", () => {
+describe("resource formatting helpers", () => {
-	it("expands skills with additional instructions", () => {
+	it("formats skill invocations with additional instructions", () => {
 		const skill = {
 			name: "inspect",
 			description: "Inspect things",
@@ -11,14 +11,14 @@ describe("resource expansion helpers", () => {
 			filePath: "/project/.pi/skills/inspect/SKILL.md",
 		};
 
-		expect(expandSkillCommand(skill, "Check errors.")).toBe(
+		expect(formatSkillInvocation(skill, "Check errors.")).toBe(
 			'<skill name="inspect" location="/project/.pi/skills/inspect/SKILL.md">\nReferences are relative to /project/.pi/skills/inspect.\n\nUse inspection tools.\n</skill>\n\nCheck errors.',
 		);
 	});
 
-	it("expands prompt templates with positional arguments", () => {
+	it("formats prompt template invocations with positional arguments", () => {
-		expect(expandPromptTemplate({ name: "review", content: "Review $1 with $ARGUMENTS" }, ["a.ts", "care"])).toBe(
+		expect(
-			"Review a.ts with a.ts care",
+			formatPromptTemplateInvocation({ name: "review", content: "Review $1 with $ARGUMENTS" }, ["a.ts", "care"]),
-		);
+		).toBe("Review a.ts with a.ts care");
 	});
 });