oma-coding-agent 1.1.4

package/src/config/model-roles.ts

@@ -0,0 +1,99 @@
+/**
+ * Built-in model roles and role metadata helpers.
+ */
+
+import { isValidThemeColor, type ThemeColor } from "../modes/theme/theme";
+import type { Settings } from "./settings";
+
+export type ModelRole =
+	| "default"
+	| "smol"
+	| "slow"
+	| "vision"
+	| "plan"
+	| "designer"
+	| "commit"
+	| "title"
+	| "task"
+	| "advisor";
+
+export interface ModelRoleInfo {
+	tag?: string;
+	name: string;
+	color?: ThemeColor;
+	/** If true, the role is functional but not shown in the model selector UI. */
+	hidden?: boolean;
+}
+
+export const MODEL_ROLES: Record<ModelRole, ModelRoleInfo> = {
+	default: { tag: "DEFAULT", name: "Default", color: "success" },
+	smol: { tag: "SMOL", name: "Fast", color: "warning" },
+	slow: { tag: "SLOW", name: "Thinking", color: "accent" },
+	vision: { tag: "VISION", name: "Vision", color: "error" },
+	plan: { tag: "PLAN", name: "Architect", color: "muted" },
+	designer: { tag: "DESIGNER", name: "Designer", color: "muted" },
+	commit: { tag: "COMMIT", name: "Commit", color: "dim" },
+	title: { tag: "TITLE", name: "Title", color: "dim", hidden: true },
+	task: { tag: "TASK", name: "Subtask", color: "muted" },
+	advisor: { tag: "ADVISOR", name: "Advisor", color: "accent" },
+};
+
+export const MODEL_ROLE_IDS: ModelRole[] = [
+	"default",
+	"smol",
+	"slow",
+	"vision",
+	"plan",
+	"designer",
+	"commit",
+	"title",
+	"task",
+	"advisor",
+];
+
+export type RoleInfo = ModelRoleInfo;
+
+/**
+ * Return the canonical set of known roles for selector/carousel UI.
+ *
+ * Built-ins always come first. Configured cycle order, model assignments, and
+ * tag metadata can introduce additional custom roles without requiring duplicate
+ * entries across settings.
+ */
+export function getKnownRoleIds(settings: Settings): string[] {
+	const roles = MODEL_ROLE_IDS.filter(role => !MODEL_ROLES[role as ModelRole]?.hidden) as string[];
+	const seen = new Set<string>(roles);
+	const addRole = (role: string) => {
+		if (seen.has(role)) return;
+		seen.add(role);
+		roles.push(role);
+	};
+
+	for (const role of settings.get("cycleOrder")) addRole(role);
+	for (const role in settings.getModelRoles()) addRole(role);
+	for (const role in settings.get("modelTags")) addRole(role);
+
+	return roles;
+}
+
+/**
+ * Get role info for a role name (built-in or custom).
+ * Configured metadata overrides built-in defaults when present.
+ */
+export function getRoleInfo(role: string, settings: Settings): RoleInfo {
+	const builtIn = role in MODEL_ROLES ? MODEL_ROLES[role as ModelRole] : undefined;
+	const configured = settings.get("modelTags")[role];
+
+	if (configured) {
+		return {
+			tag: builtIn?.tag,
+			name: configured.name || builtIn?.name || role,
+			color: configured.color && isValidThemeColor(configured.color) ? configured.color : builtIn?.color,
+			hidden: configured.hidden ?? builtIn?.hidden,
+		};
+	}
+
+	if (builtIn) return builtIn;
+
+	return { name: role, color: "muted" };
+}

package/src/config/models-config-schema.ts

@@ -0,0 +1,266 @@
+import { scope } from "arktype";
+
+// Config schemas validate at most a handful of times per process (on config
+// load), so the eager JIT codegen ArkType runs at definition time is pure
+// startup tax. A local jitless scope skips that codegen and falls back to
+// interpreted traversal — ~65% cheaper to construct, validation correctness
+// unchanged. (No `name`: duplicate module instances would collide.)
+const { type } = scope({}, { jitless: true });
+
+const OpenRouterRoutingSchema = type({
+	"only?": "string[]",
+	"order?": "string[]",
+});
+
+const VercelGatewayRoutingSchema = type({
+	"only?": "string[]",
+	"order?": "string[]",
+});
+
+const ReasoningEffortMapSchema = type({
+	"minimal?": "string",
+	"low?": "string",
+	"medium?": "string",
+	"high?": "string",
+	"xhigh?": "string",
+});
+
+const OpenAICompatFields = {
+	"supportsStore?": "boolean",
+	"supportsDeveloperRole?": "boolean",
+	"supportsMultipleSystemMessages?": "boolean",
+	"supportsReasoningEffort?": "boolean",
+	"reasoningEffortMap?": ReasoningEffortMapSchema,
+	"maxTokensField?": '"max_completion_tokens" | "max_tokens"',
+	"supportsUsageInStreaming?": "boolean",
+	"requiresToolResultName?": "boolean",
+	"requiresMistralToolIds?": "boolean",
+	"requiresAssistantAfterToolResult?": "boolean",
+	"requiresThinkingAsText?": "boolean",
+	"reasoningContentField?": '"reasoning_content" | "reasoning" | "reasoning_text"',
+	"requiresReasoningContentForToolCalls?": "boolean",
+	"allowsSyntheticReasoningContentForToolCalls?": "boolean",
+	"requiresAssistantContentForToolCalls?": "boolean",
+	"supportsToolChoice?": "boolean",
+	"supportsForcedToolChoice?": "boolean",
+	"disableReasoningOnForcedToolChoice?": "boolean",
+	"disableReasoningOnToolChoice?": "boolean",
+	"thinkingFormat?": '"openai" | "openrouter" | "zai" | "qwen" | "qwen-chat-template"',
+	"openRouterRouting?": OpenRouterRoutingSchema,
+	"vercelGatewayRouting?": VercelGatewayRoutingSchema,
+	"extraBody?": { "[string]": "unknown" },
+	"cacheControlFormat?": '"anthropic"',
+	"supportsStrictMode?": "boolean",
+	"toolStrictMode?": '"all_strict" | "none"',
+	"streamIdleTimeoutMs?": "number >= 0",
+	"supportsLongPromptCacheRetention?": "boolean",
+	"supportsReasoningParams?": "boolean",
+	"alwaysSendMaxTokens?": "boolean",
+	"strictResponsesPairing?": "boolean",
+	"supportsImageDetailOriginal?": "boolean",
+	// anthropic-messages compat flags (same `compat` slot, per-api interpretation)
+	"requiresToolResultId?": "boolean",
+	"replayUnsignedThinking?": "boolean",
+} as const;
+
+const OpenAICompatFieldsSchema = type(OpenAICompatFields);
+
+export const OpenAICompatSchema = type({
+	...OpenAICompatFields,
+	"whenThinking?": OpenAICompatFieldsSchema,
+});
+
+const EffortSchema = type('"minimal" | "low" | "medium" | "high" | "xhigh"');
+
+const ThinkingControlModeSchema = type(
+	'"effort" | "budget" | "google-level" | "anthropic-adaptive" | "anthropic-budget-effort"',
+);
+
+const EFFORT_ORDER = ["minimal", "low", "medium", "high", "xhigh"] as const;
+
+/**
+ * Accepts the canonical `efforts` vocabulary plus the legacy
+ * `minLevel`/`maxLevel`/`levels` range shape, normalizing both to
+ * `ThinkingConfig` (ordered `efforts`, never empty). Precedence mirrors the
+ * old runtime: explicit `levels` beat the min..max range; `efforts` beats both.
+ */
+const ModelThinkingSchema = type({
+	mode: ThinkingControlModeSchema,
+	"efforts?": EffortSchema.array(),
+	"defaultLevel?": EffortSchema,
+	"effortMap?": ReasoningEffortMapSchema,
+	"supportsDisplay?": "boolean",
+	// Legacy range vocabulary (pre-efforts configs).
+	"minLevel?": EffortSchema,
+	"maxLevel?": EffortSchema,
+	"levels?": EffortSchema.array(),
+})
+	.narrow(
+		(value, ctx) =>
+			value.efforts !== undefined ||
+			value.levels !== undefined ||
+			(value.minLevel !== undefined && value.maxLevel !== undefined) ||
+			ctx.mustBe("thinking with `efforts` (or legacy `levels`/`minLevel`+`maxLevel`)"),
+	)
+	.pipe((value: any) => {
+		let resolved = value.efforts ?? value.levels;
+		if (!resolved) {
+			const minIndex = EFFORT_ORDER.indexOf(value.minLevel!);
+			const maxIndex = EFFORT_ORDER.indexOf(value.maxLevel!);
+			resolved = EFFORT_ORDER.slice(minIndex, Math.max(minIndex, maxIndex) + 1);
+		}
+		return {
+			mode: value.mode,
+			efforts: resolved,
+			...(value.defaultLevel !== undefined && { defaultLevel: value.defaultLevel }),
+			...(value.effortMap !== undefined && { effortMap: value.effortMap }),
+			...(value.supportsDisplay !== undefined && { supportsDisplay: value.supportsDisplay }),
+		};
+	});
+
+const ModelDefinitionSchema = type({
+	id: "string",
+	"name?": "string",
+	"api?":
+		'"openai-completions" | "openai-responses" | "openai-codex-responses" | "azure-openai-responses" | "anthropic-messages" | "google-generative-ai" | "google-gemini-cli" | "google-vertex"',
+	"baseUrl?": "string",
+	"reasoning?": "boolean",
+	"thinking?": ModelThinkingSchema,
+	"input?": '("text" | "image")[]',
+	"supportsTools?": "boolean",
+	"cost?": {
+		input: "number",
+		output: "number",
+		cacheRead: "number",
+		cacheWrite: "number",
+	},
+	"premiumMultiplier?": "number",
+	"contextWindow?": "number",
+	"maxTokens?": "number",
+	"omitMaxOutputTokens?": "boolean",
+	"headers?": { "[string]": "string" },
+	"compat?": OpenAICompatSchema,
+	"contextPromotionTarget?": "string",
+}).narrow((value, ctx) => {
+	// Enforce id non-empty
+	if (typeof value.id === "string" && value.id.length === 0) {
+		return ctx.mustBe("id a non-empty string");
+	}
+	if (value.name !== undefined && typeof value.name === "string" && value.name.length === 0) {
+		return ctx.mustBe("name a non-empty string");
+	}
+	if (value.baseUrl !== undefined && typeof value.baseUrl === "string" && value.baseUrl.length === 0) {
+		return ctx.mustBe("baseUrl a non-empty string");
+	}
+	if (
+		value.contextPromotionTarget !== undefined &&
+		typeof value.contextPromotionTarget === "string" &&
+		value.contextPromotionTarget.length === 0
+	) {
+		return ctx.mustBe("contextPromotionTarget a non-empty string");
+	}
+	return true;
+});
+
+export const ModelOverrideSchema = type({
+	"name?": "string",
+	"reasoning?": "boolean",
+	"thinking?": ModelThinkingSchema,
+	"input?": '("text" | "image")[]',
+	"supportsTools?": "boolean",
+	"cost?": {
+		"input?": "number",
+		"output?": "number",
+		"cacheRead?": "number",
+		"cacheWrite?": "number",
+	},
+	"premiumMultiplier?": "number",
+	"contextWindow?": "number",
+	"maxTokens?": "number",
+	"omitMaxOutputTokens?": "boolean",
+	"headers?": { "[string]": "string" },
+	"compat?": OpenAICompatSchema,
+	"contextPromotionTarget?": "string",
+}).narrow((value, ctx) => {
+	if (value.name !== undefined && typeof value.name === "string" && value.name.length === 0) {
+		return ctx.mustBe("name a non-empty string");
+	}
+	if (
+		value.contextPromotionTarget !== undefined &&
+		typeof value.contextPromotionTarget === "string" &&
+		value.contextPromotionTarget.length === 0
+	) {
+		return ctx.mustBe("contextPromotionTarget a non-empty string");
+	}
+	return true;
+});
+
+export type ModelOverride = typeof ModelOverrideSchema.infer;
+
+export const ProviderDiscoverySchema = type({
+	type: '"ollama" | "llama.cpp" | "lm-studio" | "openai-models-list" | "proxy"',
+});
+
+export const ProviderAuthSchema = type('"apiKey" | "none" | "oauth"');
+
+export type ProviderAuthMode = typeof ProviderAuthSchema.infer;
+export type ProviderDiscovery = typeof ProviderDiscoverySchema.infer;
+
+const ProviderConfigSchema = type({
+	"baseUrl?": "string",
+	"apiKey?": "string",
+	"api?":
+		'"openai-completions" | "openai-responses" | "openai-codex-responses" | "azure-openai-responses" | "anthropic-messages" | "google-generative-ai" | "google-gemini-cli" | "google-vertex"',
+	"headers?": { "[string]": "string" },
+	"compat?": OpenAICompatSchema,
+	"authHeader?": "boolean",
+	"auth?": ProviderAuthSchema,
+	"discovery?": ProviderDiscoverySchema,
+	"models?": ModelDefinitionSchema.array(),
+	"modelOverrides?": { "[string]": ModelOverrideSchema },
+	"disableStrictTools?": "boolean",
+	/**
+	 * Streaming transport override. When set to `"pi-native"`, omp dispatches
+	 * every model under this provider via the auth-gateway's
+	 * `POST /v1/pi/stream` endpoint instead of the per-provider SDK. The
+	 * provider's `baseUrl` must point at a compatible `omp auth-gateway`
+	 * and `apiKey` must carry the gateway bearer.
+	 */
+	"transport?": '"pi-native"',
+}).narrow((value, ctx) => {
+	if (value.baseUrl !== undefined && typeof value.baseUrl === "string" && value.baseUrl.length === 0) {
+		return ctx.mustBe("baseUrl a non-empty string");
+	}
+	if (value.apiKey !== undefined && typeof value.apiKey === "string" && value.apiKey.length === 0) {
+		return ctx.mustBe("apiKey a non-empty string");
+	}
+	return true;
+});
+
+const EquivalenceConfigSchema = type({
+	"overrides?": { "[string]": "string" },
+	"exclude?": "string[]",
+}).narrow((value, ctx) => {
+	if (value.overrides !== undefined) {
+		for (const [, v] of Object.entries(value.overrides)) {
+			if (typeof v === "string" && v.length === 0) {
+				return ctx.mustBe("overrides values non-empty strings");
+			}
+		}
+	}
+	if (value.exclude !== undefined && Array.isArray(value.exclude)) {
+		for (const item of value.exclude) {
+			if (typeof item === "string" && item.length === 0) {
+				return ctx.mustBe("exclude items non-empty strings");
+			}
+		}
+	}
+	return true;
+});
+
+export const ModelsConfigSchema = type({
+	"providers?": { "[string]": ProviderConfigSchema },
+	"equivalence?": EquivalenceConfigSchema,
+});
+
+export type ModelsConfig = typeof ModelsConfigSchema.infer;

package/src/config/models-config.ts

@@ -0,0 +1,131 @@
+/**
+ * models.json config file handle and provider configuration validation.
+ */
+
+import type { Api, ModelSpec } from "@oh-my-pi/pi-ai/types";
+import { ConfigFile } from "./config-file";
+import {
+	type ModelsConfig,
+	ModelsConfigSchema,
+	type ProviderAuthMode,
+	type ProviderDiscovery,
+} from "./models-config-schema";
+
+export type ProviderValidationMode = "models-config" | "runtime-register";
+
+export interface ProviderValidationModel {
+	id: string;
+	api?: Api;
+	contextWindow?: number;
+	supportsTools?: boolean;
+	maxTokens?: number;
+}
+
+export interface ProviderValidationConfig {
+	baseUrl?: string;
+	headers?: Record<string, string>;
+	apiKey?: string;
+	api?: Api;
+	auth?: ProviderAuthMode;
+	oauthConfigured?: boolean;
+	discovery?: ProviderDiscovery;
+	compat?: ModelSpec<Api>["compat"];
+	disableStrictTools?: boolean;
+	modelOverrides?: Record<string, unknown>;
+	models: ProviderValidationModel[];
+}
+
+export function validateProviderConfiguration(
+	providerName: string,
+	config: ProviderValidationConfig,
+	mode: ProviderValidationMode,
+): void {
+	const hasProviderApi = !!config.api;
+	const models = config.models;
+
+	if (models.length === 0) {
+		if (mode === "models-config") {
+			const hasModelOverrides = config.modelOverrides && Object.keys(config.modelOverrides).length > 0;
+			if (
+				!config.baseUrl &&
+				!config.headers &&
+				!config.compat &&
+				!config.apiKey &&
+				config.auth !== "none" &&
+				!config.disableStrictTools &&
+				!hasModelOverrides &&
+				!config.discovery
+			) {
+				throw new Error(
+					`Provider ${providerName}: must specify "baseUrl", "headers", "apiKey", "auth: none", "compat", "disableStrictTools", "modelOverrides", "discovery", or "models"`,
+				);
+			}
+		}
+	} else {
+		if (!config.baseUrl) {
+			throw new Error(`Provider ${providerName}: "baseUrl" is required when defining custom models.`);
+		}
+		const requiresAuth =
+			mode === "runtime-register"
+				? !config.apiKey && !config.oauthConfigured
+				: !config.apiKey && (config.auth ?? "apiKey") !== "none";
+		if (requiresAuth) {
+			throw new Error(
+				mode === "runtime-register"
+					? `Provider ${providerName}: "apiKey" or "oauth" is required when defining models.`
+					: `Provider ${providerName}: "apiKey" is required when defining custom models unless auth is "none".`,
+			);
+		}
+	}
+
+	if (mode === "models-config" && config.discovery && !config.api && config.discovery.type !== "proxy") {
+		throw new Error(`Provider ${providerName}: "api" is required when discovery is enabled at provider level.`);
+	}
+
+	for (const modelDef of models) {
+		if (!hasProviderApi && !modelDef.api) {
+			throw new Error(
+				mode === "runtime-register"
+					? `Provider ${providerName}, model ${modelDef.id}: no "api" specified.`
+					: `Provider ${providerName}, model ${modelDef.id}: no "api" specified. Set at provider or model level.`,
+			);
+		}
+		if (!modelDef.id) {
+			throw new Error(`Provider ${providerName}: model missing "id"`);
+		}
+		if (mode === "models-config") {
+			if (modelDef.contextWindow !== undefined && modelDef.contextWindow <= 0) {
+				throw new Error(`Provider ${providerName}, model ${modelDef.id}: invalid contextWindow`);
+			}
+			if (modelDef.maxTokens !== undefined && modelDef.maxTokens <= 0) {
+				throw new Error(`Provider ${providerName}, model ${modelDef.id}: invalid maxTokens`);
+			}
+		}
+	}
+}
+
+export const ModelsConfigFile = new ConfigFile<ModelsConfig>("models", ModelsConfigSchema).withValidation(
+	"models",
+	config => {
+		const providers = config.providers ?? {};
+		for (const providerName in providers) {
+			const providerConfig = providers[providerName];
+			validateProviderConfiguration(
+				providerName,
+				{
+					baseUrl: providerConfig.baseUrl,
+					headers: providerConfig.headers,
+					apiKey: providerConfig.apiKey,
+					api: providerConfig.api as Api | undefined,
+					auth: (providerConfig.auth ?? "apiKey") as ProviderAuthMode,
+					discovery: providerConfig.discovery as ProviderDiscovery | undefined,
+					compat: providerConfig.compat,
+					disableStrictTools: providerConfig.disableStrictTools,
+					modelOverrides: providerConfig.modelOverrides,
+					models: (providerConfig.models ?? []) as ProviderValidationModel[],
+				},
+				"models-config",
+			);
+		}
+	},
+);

package/src/config/prompt-templates.ts

@@ -0,0 +1,185 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+	getProjectDir,
+	getProjectPromptsDir,
+	getPromptsDir,
+	logger,
+	parseFrontmatter,
+	prompt,
+} from "@oh-my-pi/pi-utils";
+import { jtdToTypeScript } from "../tools/jtd-to-typescript";
+import { parseCommandArgs, substituteArgs } from "../utils/command-args";
+
+/**
+ * Represents a prompt template loaded from a markdown file
+ */
+export interface PromptTemplate {
+	name: string;
+	description: string;
+	content: string;
+	source: string; // e.g., "(user)", "(project)", "(project:frontend)"
+}
+
+prompt.registerHelper("jtdToTypeScript", (schema: unknown): string => {
+	try {
+		return jtdToTypeScript(schema);
+	} catch {
+		return "unknown";
+	}
+});
+
+const INLINE_ARG_SHELL_PATTERN = /\$(?:ARGUMENTS|@(?:\[\d+(?::\d*)?\])?|\d+)/;
+const INLINE_ARG_TEMPLATE_PATTERN = /\{\{[\s\S]*?(?:\b(?:arguments|ARGUMENTS|args)\b|\barg\s+[^}]+)[\s\S]*?\}\}/;
+
+/**
+ * Keep the check source-level and cheap: if the template text contains any explicit
+ * inline-arg placeholder syntax, do not append the fallback text again.
+ */
+export function templateUsesInlineArgPlaceholders(templateSource: string): boolean {
+	return INLINE_ARG_SHELL_PATTERN.test(templateSource) || INLINE_ARG_TEMPLATE_PATTERN.test(templateSource);
+}
+
+export function appendInlineArgsFallback(
+	rendered: string,
+	argsText: string,
+	usesInlineArgPlaceholders: boolean,
+): string {
+	if (argsText.length === 0 || usesInlineArgPlaceholders) return rendered;
+	if (rendered.length === 0) return argsText;
+
+	return `${rendered}\n\n${argsText}`;
+}
+
+/**
+ * Recursively scan a directory for .md files (and symlinks to .md files) and load them as prompt templates
+ */
+async function loadTemplatesFromDir(
+	dir: string,
+	source: "user" | "project",
+	subdir: string = "",
+): Promise<PromptTemplate[]> {
+	const templates: PromptTemplate[] = [];
+	try {
+		const glob = new Bun.Glob("**/*");
+		const entries = [];
+		for await (const entry of glob.scan({ cwd: dir, absolute: false, onlyFiles: false })) {
+			entries.push(entry);
+		}
+
+		// Group by path depth to process directories before deeply nested files
+		entries.sort((a, b) => a.split("/").length - b.split("/").length);
+
+		for (const entry of entries) {
+			const fullPath = path.join(dir, entry);
+			const file = Bun.file(fullPath);
+
+			try {
+				const stat = await file.exists();
+				if (!stat) continue;
+
+				if (entry.endsWith(".md")) {
+					const rawContent = await file.text();
+					const { frontmatter, body } = parseFrontmatter(rawContent, { source: fullPath });
+
+					const name = entry.split("/").pop()!.slice(0, -3); // Remove .md extension
+
+					// Build source string based on subdirectory structure
+					const entryDir = entry.includes("/") ? entry.split("/").slice(0, -1).join(":") : "";
+					const fullSubdir = subdir && entryDir ? `${subdir}:${entryDir}` : entryDir || subdir;
+
+					let sourceStr: string;
+					if (source === "user") {
+						sourceStr = fullSubdir ? `(user:${fullSubdir})` : "(user)";
+					} else {
+						sourceStr = fullSubdir ? `(project:${fullSubdir})` : "(project)";
+					}
+
+					// Get description from frontmatter or first non-empty line
+					let description = String(frontmatter.description || "");
+					if (!description) {
+						const firstLine = body.split("\n").find(line => line.trim());
+						if (firstLine) {
+							// Truncate if too long
+							description = firstLine.slice(0, 60);
+							if (firstLine.length > 60) description += "...";
+						}
+					}
+
+					// Append source to description
+					description = description ? `${description} ${sourceStr}` : sourceStr;
+
+					templates.push({
+						name,
+						description,
+						content: body,
+						source: sourceStr,
+					});
+				}
+			} catch (error) {
+				logger.warn("Failed to load prompt template", { path: fullPath, error: String(error) });
+			}
+		}
+	} catch (error) {
+		if (!fs.existsSync(dir)) {
+			return [];
+		}
+		logger.warn("Failed to scan prompt templates directory", { dir, error: String(error) });
+	}
+
+	return templates;
+}
+
+export interface LoadPromptTemplatesOptions {
+	/** Working directory for project-local templates. Default: getProjectDir() */
+	cwd?: string;
+	/** Agent config directory for global templates. Default: from getPromptsDir() */
+	agentDir?: string;
+}
+
+/**
+ * Load all prompt templates from:
+ * 1. Global: agentDir/prompts/
+ * 2. Project: cwd/.omp/prompts/
+ */
+export async function loadPromptTemplates(options: LoadPromptTemplatesOptions = {}): Promise<PromptTemplate[]> {
+	const resolvedCwd = options.cwd ?? getProjectDir();
+	const resolvedAgentDir = options.agentDir ?? getPromptsDir();
+
+	const templates: PromptTemplate[] = [];
+
+	// 1. Load global templates from agentDir/prompts/
+	// Note: if agentDir is provided, it should be the agent dir, not the prompts dir
+	const globalPromptsDir = options.agentDir ? path.join(options.agentDir, "prompts") : resolvedAgentDir;
+	templates.push(...(await loadTemplatesFromDir(globalPromptsDir, "user")));
+
+	// 2. Load project templates from cwd/.omp/prompts/
+	const projectPromptsDir = getProjectPromptsDir(resolvedCwd);
+	templates.push(...(await loadTemplatesFromDir(projectPromptsDir, "project")));
+
+	return templates;
+}
+
+/**
+ * Expand a prompt template if it matches a template name.
+ * Returns the expanded content or the original text if not a template.
+ */
+export function expandPromptTemplate(text: string, templates: PromptTemplate[]): string {
+	if (!text.startsWith("/")) return text;
+
+	const spaceIndex = text.indexOf(" ");
+	const templateName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+	const argsString = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1);
+
+	const template = templates.find(t => t.name === templateName);
+	if (template) {
+		const args = parseCommandArgs(argsString);
+		const argsText = args.join(" ");
+		const usesInlineArgPlaceholders = templateUsesInlineArgPlaceholders(template.content);
+		const substituted = substituteArgs(template.content, args);
+		const rendered = prompt.render(substituted, { args, ARGUMENTS: argsText, arguments: argsText });
+		return appendInlineArgsFallback(rendered, argsText, usesInlineArgPlaceholders);
+	}
+
+	return text;
+}