@dungle-scrubs/tallow 0.8.25 → 0.8.26

package/extensions/teams-tool/sessions/spawn.ts

@@ -10,70 +10,100 @@ import {
 	AuthStorage,
 	createAgentSession,
 	createExtensionRuntime,
+	DefaultResourceLoader,
 	ModelRegistry,
-	type ResourceLoader,
 	SessionManager,
 	SettingsManager,
 } from "@mariozechner/pi-coding-agent";
-import { getTallowPath } from "../../_shared/tallow-paths.js";
+import { applyKnownModelMetadataOverrides } from "../../../src/model-metadata-overrides.js";
+import { getTallowHomeDir, getTallowPath } from "../../_shared/tallow-paths.js";
+import {
+	type AgentConfig,
+	computeEffectiveTools,
+	discoverAgents,
+	resolveAgentForExecution,
+} from "../../subagent-tool/agents.js";
 import { type RoutingHints, routeModel } from "../../subagent-tool/model-router.js";
 import { resolveStandardTools } from "../state/team-view.js";
 import type { Teammate } from "../state/types.js";
 import type { Team } from "../store.js";
 import { createTeammateTools } from "../tools/teammate-tools.js";
 
+interface SpawnTeammateSessionOptions {
+	readonly agentName?: string;
+	readonly cwd: string;
+	readonly hints?: RoutingHints;
+	readonly modelOverride?: string;
+	readonly name: string;
+	readonly parentModelId?: string;
+	readonly piEvents?: ExtensionAPI["events"];
+	readonly role?: string;
+	readonly team: Team<Teammate>;
+	readonly thinkingLevel?: string;
+	readonly toolNames?: string[];
+}
+
+type TeammateThinkingLevel = "high" | "low" | "medium" | "off";
+
 /**
- * Spawn a teammate as an in-process AgentSession with shared team tools.
+ * Coerce an arbitrary string into a supported teammate thinking level.
  *
- * Model selection follows the same routing as subagents:
- * - modelOverride set → explicit fuzzy resolution (best match)
- * - modelScope set → auto-route within that model family
- * - neither → full auto-route based on role complexity and cost preference
- *
- * @param cwd - Working directory
- * @param team - Team to add the teammate to
- * @param name - Teammate name
- * @param role - Role description (used for task classification + system prompt)
- * @param modelOverride - Explicit model name (fuzzy matched). Skips auto-routing.
- * @param toolNames - Standard tool names (defaults to all coding tools)
- * @param piEvents - Event emitter for lifecycle events
- * @param hints - Optional routing hints (modelScope, costPreference, etc.)
- * @param parentModelId - Parent model ID for fallback inheritance
- * @returns The created Teammate
- * @throws If model not found or session creation fails
+ * @param value - Raw level string from caller context or tool params
+ * @returns Supported thinking level, or undefined when unsupported
  */
-export async function spawnTeammateSession(
-	cwd: string,
-	team: Team<Teammate>,
-	name: string,
-	role: string,
-	modelOverride: string | undefined,
-	toolNames?: string[],
-	piEvents?: ExtensionAPI["events"],
-	hints?: RoutingHints,
-	parentModelId?: string
-): Promise<Teammate> {
-	const routing = await routeModel(role, modelOverride, undefined, parentModelId, role, hints, cwd);
-	if (!routing.ok) {
-		const available = listAvailableModels().slice(0, 20).join(", ");
-		throw new Error(`Model not found: "${routing.query}". Available: ${available}`);
+function coerceThinkingLevel(value: string | undefined): TeammateThinkingLevel | undefined {
+	if (!value) return undefined;
+	const normalized = value.trim().toLowerCase();
+	if (
+		normalized === "off" ||
+		normalized === "low" ||
+		normalized === "medium" ||
+		normalized === "high"
+	) {
+		return normalized;
 	}
-	const resolved = routing.model;
-
-	// Use the user's tallow auth and model config so teammates inherit
-	// API keys and custom model definitions from the main session.
-	const authStorage = AuthStorage.create(getTallowPath("auth.json"));
-	const modelRegistry = new ModelRegistry(authStorage, getTallowPath("models.json"));
+	return undefined;
+}
 
-	const model = modelRegistry.find(resolved.provider, resolved.id);
-	if (!model) {
+/**
+ * Resolve an optional teammate agent template from the shared agent directories.
+ *
+ * Team teammates should not silently fall back to an ephemeral template when the
+ * caller explicitly requested a named agent. Typos must fail closed.
+ *
+ * @param cwd - Working directory used for project-agent discovery
+ * @param agentName - Optional template name requested by the caller
+ * @returns Resolved agent template, or undefined when no template was requested
+ * @throws {Error} When a named template cannot be found
+ */
+function resolveTeammateAgentTemplate(
+	cwd: string,
+	agentName: string | undefined
+): AgentConfig | undefined {
+	if (!agentName) return undefined;
+	const discovery = discoverAgents(cwd, "both");
+	const resolved = resolveAgentForExecution(agentName, discovery.agents, discovery.defaults);
+	if (resolved.resolution === "ephemeral") {
 		throw new Error(
-			`Model resolved to "${resolved.id}" (provider: ${resolved.provider}) but not found in registry`
+			`Teammate agent template "${agentName}" was not found in user or project agent directories.`
 		);
 	}
+	return resolved.agent;
+}
 
-	const otherNames = Array.from(team.teammates.keys()).filter((n) => n !== name);
-	const systemPrompt = [
+/**
+ * Build the coordination prompt appended to every teammate.
+ *
+ * @param team - Runtime team container
+ * @param name - Teammate name
+ * @param role - Effective teammate role text
+ * @returns Coordination instructions shared by all teammates
+ */
+function buildCoordinationPrompt(team: Team<Teammate>, name: string, role: string): string {
+	const otherNames = Array.from(team.teammates.keys()).filter(
+		(teammateName) => teammateName !== name
+	);
+	return [
 		`You are "${name}", a teammate in team "${team.name}".`,
 		`Your role: ${role}`,
 		"",
@@ -95,40 +125,183 @@ export async function spawnTeammateSession(
 		"",
 		"Communicate with teammates via team_message when you need their input.",
 	].join("\n");
+}
 
-	const resourceLoader: ResourceLoader = {
-		getExtensions: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
-		getSkills: () => ({ skills: [], diagnostics: [] }),
-		getPrompts: () => ({ prompts: [], diagnostics: [] }),
-		getThemes: () => ({ themes: [], diagnostics: [] }),
-		getAgentsFiles: () => ({ agentsFiles: [] }),
-		getSystemPrompt: () => systemPrompt,
-		getAppendSystemPrompt: () => [],
-		getPathMetadata: () => new Map(),
-		extendResources: () => {},
-		reload: async () => {},
-	};
+/**
+ * Merge teammate coordination with an optional agent template system prompt.
+ *
+ * @param team - Runtime team container
+ * @param name - Teammate name
+ * @param role - Effective teammate role text
+ * @param templateAgent - Optional resolved agent template
+ * @returns Final system prompt text for the teammate session
+ */
+function buildTeammateSystemPrompt(
+	team: Team<Teammate>,
+	name: string,
+	role: string,
+	templateAgent: AgentConfig | undefined
+): string {
+	const sections = [buildCoordinationPrompt(team, name, role)];
+	if (templateAgent?.systemPrompt.trim()) {
+		sections.push(
+			[`Base agent template: ${templateAgent.name}`, templateAgent.systemPrompt.trim()].join("\n\n")
+		);
+	}
+	if (templateAgent?.maxTurns) {
+		sections.unshift(
+			`You have a maximum of ${templateAgent.maxTurns} tool-use turns for this task. Plan accordingly and return your best partial result before hitting the limit.`
+		);
+	}
+	return sections.join("\n\n");
+}
 
-	const teammateCustomTools = createTeammateTools(team, name, piEvents);
+/**
+ * Resolve the standard tool allowlist for a teammate.
+ *
+ * Explicit tool names passed to `team_spawn` win. Otherwise agent-template
+ * allow/deny lists are applied when present.
+ *
+ * @param explicitToolNames - Tools passed directly to team_spawn
+ * @param templateAgent - Optional resolved agent template
+ * @returns Effective tool names, or undefined to allow the default coding set
+ */
+function resolveTeammateToolNames(
+	explicitToolNames: string[] | undefined,
+	templateAgent: AgentConfig | undefined
+): string[] | undefined {
+	if (explicitToolNames) return explicitToolNames;
+	if (!templateAgent) return undefined;
+	return computeEffectiveTools(templateAgent.tools, templateAgent.disallowedTools);
+}
 
-	const { session } = await createAgentSession({
+/**
+ * Create a loader that only exposes the requested teammate skills/system prompt.
+ *
+ * Extensions are disabled on purpose — teammates get only the explicitly passed
+ * standard tools plus the injected team coordination tools.
+ *
+ * @param cwd - Working directory
+ * @param settingsManager - Shared in-memory settings for the teammate session
+ * @param systemPrompt - Final system prompt text
+ * @param templateAgent - Optional resolved agent template
+ * @returns Reloaded resource loader ready for createAgentSession
+ */
+async function createTeammateResourceLoader(
+	cwd: string,
+	settingsManager: SettingsManager,
+	systemPrompt: string,
+	templateAgent: AgentConfig | undefined
+): Promise<DefaultResourceLoader> {
+	const requestedSkills = new Set(templateAgent?.skills ?? []);
+	const loader = new DefaultResourceLoader({
+		agentDir: getTallowHomeDir(),
 		cwd,
-		agentDir: path.join(os.tmpdir(), `pi-team-${team.name}-${name}`),
-		model,
-		thinkingLevel: "off",
+		extensionsOverride: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
+		promptsOverride: () => ({ diagnostics: [], prompts: [] }),
+		settingsManager,
+		skillsOverride: (base) => ({
+			diagnostics: base.diagnostics,
+			skills:
+				requestedSkills.size === 0
+					? []
+					: base.skills.filter((skill) => requestedSkills.has(skill.name)),
+		}),
+		systemPromptOverride: () => systemPrompt,
+	});
+	await loader.reload();
+	return loader;
+}
+
+/**
+ * Spawn a teammate as an in-process AgentSession with shared team tools.
+ *
+ * Model selection follows the same routing as subagents:
+ * - modelOverride set → explicit fuzzy resolution (best match)
+ * - template agent model set → explicit or auto-routing keyword from frontmatter
+ * - neither → full auto-route based on role complexity and cost preference
+ *
+ * @param options - Session spawn options
+ * @returns The created Teammate
+ * @throws {Error} If model or agent template resolution fails
+ */
+export async function spawnTeammateSession(
+	options: SpawnTeammateSessionOptions
+): Promise<Teammate> {
+	const templateAgent = resolveTeammateAgentTemplate(options.cwd, options.agentName);
+	const role = options.role?.trim() || templateAgent?.description?.trim();
+	if (!role) {
+		throw new Error("team_spawn requires either a role or an agent template.");
+	}
+
+	const routingTask = templateAgent?.systemPrompt?.trim()
+		? `${role}\n\n${templateAgent.systemPrompt.trim()}`
+		: role;
+	const routing = await routeModel(
+		routingTask,
+		options.modelOverride,
+		templateAgent?.model,
+		options.parentModelId,
+		role,
+		options.hints,
+		options.cwd
+	);
+	if (!routing.ok) {
+		const available = listAvailableModels().slice(0, 20).join(", ");
+		throw new Error(`Model not found: "${routing.query}". Available: ${available}`);
+	}
+	const resolvedModel = routing.model;
+
+	// Use the user's tallow auth and model config so teammates inherit
+	// API keys and custom model definitions from the main session.
+	const authStorage = AuthStorage.create(getTallowPath("auth.json"));
+	const modelRegistry = new ModelRegistry(authStorage, getTallowPath("models.json"));
+	applyKnownModelMetadataOverrides(modelRegistry);
+	const model = modelRegistry.find(resolvedModel.provider, resolvedModel.id);
+	if (!model) {
+		throw new Error(
+			`Model resolved to "${resolvedModel.id}" (provider: ${resolvedModel.provider}) but not found in registry`
+		);
+	}
+
+	const systemPrompt = buildTeammateSystemPrompt(options.team, options.name, role, templateAgent);
+	const settingsManager = SettingsManager.inMemory({
+		compaction: { enabled: true },
+		retry: { enabled: true, maxRetries: 2 },
+	});
+	const resourceLoader = await createTeammateResourceLoader(
+		options.cwd,
+		settingsManager,
+		systemPrompt,
+		templateAgent
+	);
+	const teammateCustomTools = createTeammateTools(options.team, options.name, options.piEvents);
+	const thinkingLevel = coerceThinkingLevel(options.thinkingLevel) ?? "off";
+	const toolNames = resolveTeammateToolNames(options.toolNames, templateAgent);
+	const standardTools =
+		toolNames && toolNames.length === 0 ? [] : resolveStandardTools(options.cwd, toolNames);
+
+	const { session } = await createAgentSession({
 		authStorage,
+		customTools: teammateCustomTools,
+		cwd: options.cwd,
+		agentDir: path.join(os.tmpdir(), `pi-team-${options.team.name}-${options.name}`),
+		model,
 		modelRegistry,
 		resourceLoader,
-		tools: resolveStandardTools(cwd, toolNames),
-		customTools: teammateCustomTools,
 		sessionManager: SessionManager.inMemory(),
-		settingsManager: SettingsManager.inMemory({
-			compaction: { enabled: true },
-			retry: { enabled: true, maxRetries: 2 },
-		}),
+		settingsManager,
+		thinkingLevel,
+		tools: standardTools,
 	});
 
-	const mate: Teammate = { name, role, model: resolved.id, session, status: "idle" };
-	team.teammates.set(name, mate);
-	return mate;
+	const teammate: Teammate = {
+		model: resolvedModel.id,
+		name: options.name,
+		role,
+		session,
+		status: "idle",
+	};
+	options.team.teammates.set(options.name, teammate);
+	return teammate;
 }