@xl0/pi-lovely-agents 0.1.0

package/extensions/lovely-agents/child-session.ts

@@ -0,0 +1,296 @@
+import { lstat, open } from "node:fs/promises"
+import {
+	type AgentSession,
+	type BuildSystemPromptOptions,
+	createAgentSession,
+	DefaultResourceLoader,
+	getAgentDir,
+	type LoadExtensionsResult,
+	type PromptOptions,
+	type ScopedModel,
+	SessionManager,
+	SettingsManager,
+	type Skill
+} from "@earendil-works/pi-coding-agent"
+import { MODEL_ALIASES, type ModelAliasChoice } from "./config.js"
+import { getAgentCoordinator } from "./coordinator.js"
+import type { AgentDefinition, AgentThinkingLevel } from "./definitions.js"
+import type { TaskStoragePaths } from "./state.js"
+
+const PROMPT_EXTENSION_PATH = "<inline:lovely-agent-prompt>"
+const CREATION_TOOL_NAMES = new Set(["agent"])
+
+export type ChildSessionSelection = {
+	model: ScopedModel["model"]
+	thinking: AgentThinkingLevel
+}
+
+export type ChildToolPolicy = {
+	tools?: string[]
+	excludeTools: string[]
+	depth: number
+	allowAgents: boolean
+}
+
+export type CreateChildSessionOptions = {
+	cwd: string
+	paths: TaskStoragePaths
+	definition: AgentDefinition
+	selection: ChildSessionSelection
+	scopedModels: readonly ScopedModel[]
+	parentDepth: number
+	maximumDepth: number
+	allowAgents: boolean
+	projectTrusted: boolean
+	expectedSessionId?: string
+	agentDir?: string
+}
+
+export type ChildSessionHandle = {
+	session: AgentSession
+	extensionsResult: LoadExtensionsResult
+	depth: number
+	allowAgents: boolean
+	dispose(): void
+}
+
+export function childPromptOptions(expandPromptTemplates: boolean): PromptOptions {
+	return { expandPromptTemplates }
+}
+
+export function resolveChildSessionSelection(options: {
+	callModel?: string
+	callThinking?: AgentThinkingLevel
+	definition: AgentDefinition
+	configuredModels: readonly ScopedModel[]
+	aliases?: readonly ModelAliasChoice[]
+	availableModels: readonly ScopedModel["model"][]
+	parentModel: ScopedModel["model"] | undefined
+	parentThinking: AgentThinkingLevel
+}): ChildSessionSelection {
+	let model: ScopedModel["model"] | undefined
+	const reference = options.callModel ?? options.definition.model
+	const alias = options.aliases?.find(alias => alias.name === reference)
+	if (reference && Object.hasOwn(MODEL_ALIASES, reference) && !alias) {
+		throw new Error(`Model alias "${reference}" is not configured or its model is unavailable`)
+	}
+	if (alias) {
+		model = alias.model
+	} else if (options.callModel) {
+		model = options.configuredModels.find(choice => modelId(choice.model) === options.callModel)?.model
+		if (!model) throw new Error(`Model "${options.callModel}" is not an available configured choice`)
+	} else if (options.definition.model) {
+		model = options.availableModels.find(candidate => modelId(candidate) === options.definition.model)
+		if (!model) throw new Error(`Agent Definition model "${options.definition.model}" is not authenticated`)
+	} else {
+		model = options.parentModel
+		if (!model) throw new Error("No parent model is available")
+	}
+	return {
+		model,
+		thinking:
+			options.callThinking ??
+			(options.callModel ? alias?.thinkingLevel : undefined) ??
+			options.definition.thinking ??
+			alias?.thinkingLevel ??
+			options.parentThinking
+	}
+}
+
+export function resolveChildToolPolicy(options: {
+	definitionTools?: readonly string[]
+	parentDepth: number
+	maximumDepth: number
+	allowAgents: boolean
+}): ChildToolPolicy {
+	if (!Number.isSafeInteger(options.parentDepth) || options.parentDepth < 0)
+		throw new Error("Parent depth must be a nonnegative safe integer")
+	if (!Number.isSafeInteger(options.maximumDepth) || options.maximumDepth < 0) {
+		throw new Error("Maximum depth must be a nonnegative safe integer")
+	}
+	const depth = options.parentDepth + 1
+	if (depth > options.maximumDepth) throw new Error(`Agent depth ${depth} exceeds configured maximum ${options.maximumDepth}`)
+	const allowAgents = options.allowAgents && depth < options.maximumDepth
+	const excludeTools = allowAgents ? [] : [...CREATION_TOOL_NAMES]
+	const tools = options.definitionTools?.filter(name => allowAgents || !CREATION_TOOL_NAMES.has(name))
+	return { ...(tools ? { tools } : {}), excludeTools, depth, allowAgents }
+}
+
+export async function createChildSession(options: CreateChildSessionOptions): Promise<ChildSessionHandle> {
+	const policy = resolveChildToolPolicy({
+		...(options.definition.tools ? { definitionTools: options.definition.tools } : {}),
+		parentDepth: options.parentDepth,
+		maximumDepth: options.maximumDepth,
+		allowAgents: options.allowAgents
+	})
+	const agentDir = options.agentDir ?? getAgentDir()
+	const settingsManager = SettingsManager.create(options.cwd, agentDir)
+	settingsManager.setProjectTrusted(options.projectTrusted)
+	const resourceLoader = new DefaultResourceLoader({
+		cwd: options.cwd,
+		agentDir,
+		settingsManager,
+		systemPromptOverride: () => options.definition.systemPrompt,
+		...(options.definition.excludeAgentsMd ? { agentsFilesOverride: () => ({ agentsFiles: [] }) } : {}),
+		extensionFactories: [
+			{
+				name: "lovely-agent-prompt",
+				hidden: true,
+				factory(pi) {
+					pi.on("before_agent_start", event => ({
+						systemPrompt: buildDefinitionSystemPrompt(event.systemPromptOptions)
+					}))
+				}
+			}
+		],
+		extensionsOverride: base => {
+			const composer = base.extensions.find(extension => extension.path === PROMPT_EXTENSION_PATH)
+			if (!composer) return base
+			return { ...base, extensions: [composer, ...base.extensions.filter(extension => extension !== composer)] }
+		}
+	})
+	await resourceLoader.reload()
+	if (!resourceLoader.getExtensions().extensions.some(extension => extension.path === PROMPT_EXTENSION_PATH)) {
+		throw new Error("Could not load the Lovely Agents prompt composer")
+	}
+
+	await reserveSessionFile(options.paths.session)
+	const sessionManager = SessionManager.open(options.paths.session, options.paths.taskDirectory, options.cwd)
+	const result = await createAgentSession({
+		cwd: options.cwd,
+		agentDir,
+		model: options.selection.model,
+		thinkingLevel: options.selection.thinking,
+		scopedModels: [...options.scopedModels],
+		...(policy.tools ? { tools: policy.tools } : {}),
+		excludeTools: policy.excludeTools,
+		resourceLoader,
+		sessionManager,
+		settingsManager
+	})
+	if (options.expectedSessionId && result.session.sessionId !== options.expectedSessionId) {
+		result.session.dispose()
+		throw new Error(`Child session identity mismatch: expected ${options.expectedSessionId}, found ${result.session.sessionId}`)
+	}
+
+	const lifetime = new AbortController()
+	const unbindContext = getAgentCoordinator().bindSessionContext(result.session.sessionId, {
+		depth: policy.depth,
+		allowAgents: policy.allowAgents,
+		disposeSignal: lifetime.signal
+	})
+	try {
+		await result.session.bindExtensions({ mode: "print" })
+	} catch (error) {
+		lifetime.abort()
+		unbindContext()
+		result.session.dispose()
+		throw error
+	}
+	let disposed = false
+	return {
+		session: result.session,
+		extensionsResult: result.extensionsResult,
+		depth: policy.depth,
+		allowAgents: policy.allowAgents,
+		dispose() {
+			if (disposed) return
+			disposed = true
+			lifetime.abort()
+			unbindContext()
+			result.session.dispose()
+		}
+	}
+}
+
+export function buildDefinitionSystemPrompt(options: BuildSystemPromptOptions): string {
+	const body = options.customPrompt?.trim()
+	if (!body) throw new Error("Agent Definition body is empty")
+	const tools = options.selectedTools ?? []
+	const visibleTools = tools.filter(name => options.toolSnippets?.[name])
+	const toolList = visibleTools.length > 0 ? visibleTools.map(name => `- ${name}: ${options.toolSnippets?.[name]}`).join("\n") : "(none)"
+	const guidelines: string[] = []
+	const seen = new Set<string>()
+	const addGuideline = (value: string) => {
+		const guideline = value.trim()
+		if (!guideline || seen.has(guideline)) return
+		seen.add(guideline)
+		guidelines.push(guideline)
+	}
+	const hasBash = tools.includes("bash")
+	const hasPowerShell = tools.includes("powershell")
+	if ((hasBash || hasPowerShell) && !tools.some(name => name === "grep" || name === "find" || name === "ls")) {
+		addGuideline(
+			hasBash && hasPowerShell
+				? "Use bash or PowerShell for file operations like listing, searching, and finding files"
+				: hasPowerShell
+					? "Use PowerShell for file operations like listing, searching, and finding files"
+					: "Use bash for file operations like ls, rg, find"
+		)
+	}
+	for (const guideline of options.promptGuidelines ?? []) addGuideline(guideline)
+	addGuideline("Be concise in your responses")
+	addGuideline("Show file paths clearly when working with files")
+
+	let prompt = `${body}\n\nAvailable tools:\n${toolList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines.map(value => `- ${value}`).join("\n")}`
+	if (options.appendSystemPrompt) prompt += `\n\n${options.appendSystemPrompt}`
+	if (options.contextFiles && options.contextFiles.length > 0) {
+		prompt += "\n\n<project_context>\n\nProject-specific instructions and guidelines:\n\n"
+		for (const file of options.contextFiles) {
+			prompt += `<project_instructions path="${file.path}">\n${file.content}\n</project_instructions>\n\n`
+		}
+		prompt += "</project_context>\n"
+	}
+	const skillReadTool = (["read", "bash"] as const).find(name => tools.includes(name))
+	if (skillReadTool && options.skills && options.skills.length > 0) {
+		prompt += formatSkillsForChild(options.skills, skillReadTool)
+	}
+	prompt += `\nCurrent working directory: ${options.cwd.replace(/\\/g, "/")}\n`
+	return prompt
+}
+
+function modelId(model: ScopedModel["model"]): string {
+	return `${model.provider}/${model.id}`
+}
+
+function formatSkillsForChild(skills: Skill[], fileReadTool: "read" | "bash"): string {
+	const visible = skills.filter(skill => !skill.disableModelInvocation)
+	if (visible.length === 0) return ""
+	const lines = [
+		"",
+		"",
+		"The following skills provide specialized instructions for specific tasks.",
+		`Use the ${fileReadTool} tool to load a skill's file when the task matches its description.`,
+		"When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+		"",
+		"<available_skills>"
+	]
+	for (const skill of visible) {
+		lines.push("  <skill>")
+		lines.push(`    <name>${escapeXml(skill.name)}</name>`)
+		lines.push(`    <description>${escapeXml(skill.description)}</description>`)
+		lines.push(`    <location>${escapeXml(skill.filePath)}</location>`)
+		lines.push("  </skill>")
+	}
+	lines.push("</available_skills>")
+	return lines.join("\n")
+}
+
+function escapeXml(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;")
+}
+
+async function reserveSessionFile(path: string): Promise<void> {
+	try {
+		const file = await open(path, "wx", 0o600)
+		await file.close()
+	} catch (error) {
+		if (!hasCode(error, "EEXIST")) throw error
+		const stats = await lstat(path)
+		if (!stats.isFile() || stats.isSymbolicLink()) throw new Error(`Child session path is not a regular file: ${path}`)
+	}
+}
+
+function hasCode(error: unknown, code: string): boolean {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code
+}

package/extensions/lovely-agents/config.ts

@@ -0,0 +1,221 @@
+import type { ExtensionContext, ScopedModel } from "@earendil-works/pi-coding-agent"
+import { type ConfigFromSchema, defineScopedConfig, field, type ScopedConfig } from "@xl0/pi-lovely-config"
+
+const NO_MODELS = "(no authenticated models)"
+const DISABLED_MODEL = "disabled"
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const
+export const MODEL_ALIASES = {
+	fast: "Cheap, low-latency model for straightforward tasks.",
+	smart: "Most capable model for difficult reasoning and complex work.",
+	workhorse: "Balanced cost and capability for routine coding and research."
+} as const
+export type ModelAliasName = keyof typeof MODEL_ALIASES
+/** A user-selected preset, resolved to an authenticated model before creation. */
+export type ModelAliasChoice = {
+	name: ModelAliasName
+	model: ScopedModel["model"]
+	thinkingLevel: NonNullable<ScopedModel["thinkingLevel"]>
+}
+type ModelConfigContext = Pick<ExtensionContext, "model" | "modelRegistry">
+
+function createConfigSchema(ctx?: ModelConfigContext) {
+	const availableModels = ctx?.modelRegistry.getAvailable() ?? []
+	const modelIds = [...new Set(availableModels.map(model => `${model.provider}/${model.id}`))]
+	const modelValues = (modelIds.length > 0 ? modelIds : [NO_MODELS]) as [string, ...string[]]
+	const valueDescriptions = Object.fromEntries(availableModels.map(model => [`${model.provider}/${model.id}`, model.name || model.id]))
+	const aliasModel = (name: ModelAliasName) =>
+		field.enum([DISABLED_MODEL, ...modelIds] as [string, ...string[]], DISABLED_MODEL, {
+			label: `${name} model`,
+			description: MODEL_ALIASES[name],
+			search: true,
+			valueDescriptions: { [DISABLED_MODEL]: "Do not expose this alias", ...valueDescriptions }
+		})
+	const aliasThinking = (name: ModelAliasName, level: ModelAliasChoice["thinkingLevel"]) =>
+		field.enum(THINKING_LEVELS, level, {
+			label: `${name} thinking`,
+			description: "Preset effort; an explicit thinking argument overrides it.",
+			depth: 1,
+			visibleWhen: ctx => ctx.get(`${name}Model`) !== DISABLED_MODEL
+		})
+	return {
+		backgroundAgents: field.boolean(true, {
+			label: "Background agents",
+			description: "Allow detached agents and asynchronous Follow-ups. Off keeps agents in the foreground."
+		}),
+		backgroundBash: field.boolean(true, {
+			label: "Background Bash",
+			description: "Run Bash commands as managed background tasks."
+		}),
+		models: field.multiEnum(modelValues, [], {
+			label: "Models",
+			description: "Additional model IDs available for agent selection. Empty includes the parent. Alias targets are always included.",
+			valueDescriptions
+		}),
+		fastModel: aliasModel("fast"),
+		fastThinking: aliasThinking("fast", "low"),
+		smartModel: aliasModel("smart"),
+		smartThinking: aliasThinking("smart", "high"),
+		workhorseModel: aliasModel("workhorse"),
+		workhorseThinking: aliasThinking("workhorse", "medium"),
+		maxConcurrency: field.number(4, {
+			label: "Max concurrency",
+			description: "Maximum agent runs executing in this process.",
+			min: 1,
+			step: 1
+		}),
+		maxBashConcurrency: field.number(4, {
+			label: "Bash concurrency",
+			description: "Maximum background Bash processes, separate from agent permits.",
+			min: 1,
+			step: 1,
+			visibleWhen: ctx => ctx.get("backgroundBash") === true
+		}),
+		maxDepth: field.number(2, {
+			label: "Max depth",
+			description: "Maximum agent delegation depth. The root session is depth 0.",
+			min: 0,
+			step: 1
+		}),
+		waitMs: field.number(30_000, {
+			label: "Initial wait (ms)",
+			description: "How long agent creation waits before detaching.",
+			min: 0,
+			step: 1000,
+			visibleWhen: ctx => ctx.get("backgroundAgents") === true
+		}),
+		expandPromptTemplates: field.boolean(false, {
+			label: "Expand prompt templates",
+			description: "Interpret child skill commands, prompt templates, and extension commands."
+		})
+	} as const
+}
+
+const configSchema = createConfigSchema()
+type RawAgentsConfig = ConfigFromSchema<typeof configSchema>
+type ConfigScope = "user" | "workspace"
+
+export type AgentsConfig = RawAgentsConfig
+
+export type AgentsConfigWarning = {
+	scope: ConfigScope
+	path: string
+	key?: string
+	message: string
+}
+
+export type ModelChoice = ScopedModel
+
+export type ModelChoiceDiagnostic = {
+	type: "warning"
+	code: "no-match"
+	message: string
+	pattern: string
+}
+
+export const defaultAgentsConfig: AgentsConfig = {
+	...createAgentsConfigSpec().defaults
+}
+
+export function createAgentsConfigSpec(ctx?: ModelConfigContext): ScopedConfig<RawAgentsConfig> {
+	return defineScopedConfig({
+		fileName: "xl0-pi-lovely-agents.json",
+		schema: createConfigSchema(ctx)
+	}) as ScopedConfig<RawAgentsConfig>
+}
+
+export function resolveAgentsConfig(config: ScopedConfig<RawAgentsConfig>): {
+	value: AgentsConfig
+	warnings: AgentsConfigWarning[]
+} {
+	const scoped = {
+		user: { ...config.scoped.user },
+		workspace: { ...config.scoped.workspace }
+	}
+	const warnings: AgentsConfigWarning[] = [...config.warnings]
+
+	for (const scope of config.scopes) {
+		for (const key of ["maxConcurrency", "maxBashConcurrency", "maxDepth", "waitMs"] as const) {
+			const value = scoped[scope][key]
+			if (typeof value !== "number" || Number.isInteger(value)) continue
+			delete scoped[scope][key]
+			warnings.push({
+				scope,
+				path: config.path(scope),
+				key,
+				message: `/${key} must be an integer; value is ignored while resolving`
+			})
+		}
+	}
+
+	return { value: config.resolve(scoped), warnings }
+}
+
+export function loadAgentsConfig(
+	cwd: string,
+	ctx?: ModelConfigContext
+): {
+	value: AgentsConfig
+	warnings: AgentsConfigWarning[]
+} {
+	return resolveAgentsConfig(createAgentsConfigSpec(ctx).load(cwd))
+}
+
+export function resolveModelChoices(options: {
+	selections: readonly string[]
+	availableModels: readonly ScopedModel["model"][]
+	parentModel: ScopedModel["model"] | undefined
+}): { models: ModelChoice[]; diagnostics: ModelChoiceDiagnostic[] } {
+	if (options.selections.length === 0) {
+		return options.parentModel
+			? { models: [{ model: options.parentModel }], diagnostics: [] }
+			: {
+					models: [],
+					diagnostics: [{ type: "warning", code: "no-match", message: "No current parent model is available", pattern: "" }]
+				}
+	}
+
+	const models: ModelChoice[] = []
+	const diagnostics: ModelChoiceDiagnostic[] = []
+	for (const selection of options.selections) {
+		const model = options.availableModels.find(model => `${model.provider}/${model.id}` === selection)
+		if (model) models.push({ model })
+		else {
+			diagnostics.push({
+				type: "warning",
+				code: "no-match",
+				message: `Configured model "${selection}" is not available`,
+				pattern: selection
+			})
+		}
+	}
+	return { models, diagnostics }
+}
+
+export function resolveConfiguredModels(config: AgentsConfig, ctx: ExtensionContext) {
+	const availableModels = ctx.modelRegistry.getAvailable()
+	const resolved = resolveModelChoices({
+		selections: config.models,
+		availableModels,
+		parentModel: ctx.model
+	})
+	const aliases: ModelAliasChoice[] = []
+	for (const name of Object.keys(MODEL_ALIASES) as ModelAliasName[]) {
+		const target = config[`${name}Model`]
+		if (target === DISABLED_MODEL) continue
+		const model = availableModels.find(model => `${model.provider}/${model.id}` === target)
+		if (!model) {
+			resolved.diagnostics.push({
+				type: "warning",
+				code: "no-match",
+				pattern: target,
+				message: `Model alias "${name}" targets unavailable model "${target}"`
+			})
+			continue
+		}
+		aliases.push({ name, model, thinkingLevel: config[`${name}Thinking`] })
+		if (!resolved.models.some(choice => choice.model.provider === model.provider && choice.model.id === model.id)) {
+			resolved.models.push({ model })
+		}
+	}
+	return { ...resolved, aliases }
+}