@dungle-scrubs/tallow 0.8.24 → 0.8.26

package/extensions/teams-tool/archive-store.ts

@@ -0,0 +1,200 @@
+/**
+ * Persistent archive storage for teams-tool.
+ *
+ * Archives are stored on disk so `team_resume` survives process restarts and
+ * session shutdown. Runtime state still uses the in-memory store; this module
+ * only handles serialization and persistence of archived snapshots.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileSync } from "../_shared/atomic-write.js";
+import { getTallowPath } from "../_shared/tallow-paths.js";
+import type { ArchivedTeam, TeamMessage } from "./store.js";
+
+interface SerializedTeamMessage {
+	readonly content: string;
+	readonly from: string;
+	readonly readBy: readonly string[];
+	readonly timestamp: number;
+	readonly to: string;
+}
+
+interface SerializedArchivedTeam {
+	readonly archivedAt: number;
+	readonly messages: readonly SerializedTeamMessage[];
+	readonly name: string;
+	readonly taskCounter: number;
+	readonly tasks: ArchivedTeam["tasks"];
+}
+
+/**
+ * Resolve the directory that stores archived teams.
+ *
+ * @returns Absolute archive directory path under the active tallow home
+ */
+export function getTeamArchivesDir(): string {
+	return getTallowPath("team-archives");
+}
+
+/**
+ * Ensure the archive directory exists before reading or writing.
+ *
+ * @returns Archive directory path
+ */
+function ensureTeamArchivesDir(): string {
+	const dir = getTeamArchivesDir();
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+/**
+ * Resolve the archive file path for one team name.
+ *
+ * @param teamName - Team name to encode into a stable file name
+ * @returns Absolute JSON file path
+ */
+function getArchiveFilePath(teamName: string): string {
+	return join(ensureTeamArchivesDir(), `${encodeURIComponent(teamName)}.json`);
+}
+
+/**
+ * Convert a runtime TeamMessage into a JSON-safe form.
+ *
+ * @param message - Runtime message with Set-based read tracking
+ * @returns Serializable message record
+ */
+function serializeTeamMessage(message: TeamMessage): SerializedTeamMessage {
+	return {
+		content: message.content,
+		from: message.from,
+		readBy: [...message.readBy].sort(),
+		timestamp: message.timestamp,
+		to: message.to,
+	};
+}
+
+/**
+ * Convert an archived team into a JSON-safe form.
+ *
+ * @param archived - Archived team snapshot from the runtime store
+ * @returns Serializable archive payload
+ */
+function serializeArchivedTeam(archived: ArchivedTeam): SerializedArchivedTeam {
+	return {
+		archivedAt: archived.archivedAt,
+		messages: archived.messages.map(serializeTeamMessage),
+		name: archived.name,
+		taskCounter: archived.taskCounter,
+		tasks: archived.tasks,
+	};
+}
+
+/**
+ * Convert a serialized message back into the runtime representation.
+ *
+ * @param message - JSON-parsed message payload
+ * @returns Runtime message with Set-based read tracking
+ */
+function deserializeTeamMessage(message: SerializedTeamMessage): TeamMessage {
+	return {
+		content: message.content,
+		from: message.from,
+		readBy: new Set(message.readBy),
+		timestamp: message.timestamp,
+		to: message.to,
+	};
+}
+
+/**
+ * Parse an archived-team JSON payload.
+ *
+ * @param raw - Raw JSON string from disk
+ * @returns Parsed archive, or undefined when malformed
+ */
+function deserializeArchivedTeam(raw: string): ArchivedTeam | undefined {
+	try {
+		const parsed = JSON.parse(raw) as Partial<SerializedArchivedTeam>;
+		if (
+			typeof parsed.name !== "string" ||
+			typeof parsed.archivedAt !== "number" ||
+			typeof parsed.taskCounter !== "number" ||
+			!Array.isArray(parsed.tasks) ||
+			!Array.isArray(parsed.messages)
+		) {
+			return undefined;
+		}
+		return {
+			archivedAt: parsed.archivedAt,
+			messages: parsed.messages.map((message) => deserializeTeamMessage(message)),
+			name: parsed.name,
+			taskCounter: parsed.taskCounter,
+			tasks: parsed.tasks,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Persist one archived team snapshot to disk.
+ *
+ * @param archived - Archived team snapshot to write
+ * @returns Nothing
+ */
+export function writeArchivedTeamToDisk(archived: ArchivedTeam): void {
+	const filePath = getArchiveFilePath(archived.name);
+	atomicWriteFileSync(filePath, JSON.stringify(serializeArchivedTeam(archived), null, 2));
+}
+
+/**
+ * Delete one archived team snapshot from disk.
+ *
+ * @param teamName - Team whose archive should be removed
+ * @returns Nothing
+ */
+export function deleteArchivedTeamFromDisk(teamName: string): void {
+	const filePath = getArchiveFilePath(teamName);
+	if (!existsSync(filePath)) return;
+	unlinkSync(filePath);
+}
+
+/**
+ * Load one archived team snapshot from disk.
+ *
+ * @param teamName - Team whose archive should be read
+ * @returns Archived snapshot, or undefined when missing or malformed
+ */
+export function loadArchivedTeamFromDisk(teamName: string): ArchivedTeam | undefined {
+	const filePath = getArchiveFilePath(teamName);
+	if (!existsSync(filePath)) return undefined;
+	try {
+		return deserializeArchivedTeam(readFileSync(filePath, "utf-8"));
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Load all archived team snapshots from disk.
+ *
+ * Malformed files are skipped rather than crashing archive discovery.
+ * Results are sorted newest-first for status listings.
+ *
+ * @returns Archived team snapshots persisted on disk
+ */
+export function loadAllArchivedTeamsFromDisk(): ArchivedTeam[] {
+	const dir = ensureTeamArchivesDir();
+	const archives: ArchivedTeam[] = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+		try {
+			const archive = deserializeArchivedTeam(readFileSync(join(dir, entry.name), "utf-8"));
+			if (!archive) continue;
+			archives.push(archive);
+		} catch {
+			// Skip unreadable archive files instead of breaking discovery.
+		}
+	}
+	return archives.sort((left, right) => right.archivedAt - left.archivedAt);
+}

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;
 }