repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

extensions/ultra/implementation.ts

Raw
// ultra runtime: loaded only when the human invokes or completes /ultra.

import { existsSync, readFileSync } from "node:fs";
import { resolve } from "node:path";
import { fileURLToPath } from "node:url";
import {
	createAgentSession,
	DefaultResourceLoader,
	type ExtensionAPI,
	type ExtensionCommandContext,
	type ExtensionContext,
	getAgentDir,
	SessionManager,
	SettingsManager,
} from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
import { createActionSummarizer } from "./action-summarizer.ts";
import {
	BUILTIN_TOOL_NAMES,
	makeResolveModel,
	makeSessionFactory,
	makeSubagentSessionManager,
	type SessionFactoryDeps,
} from "./drivers.ts";
import type { DynamicExtensionResolver } from "./dynamic-types.ts";
import { runWorkflow, type WorkflowResult } from "./engine.ts";
import {
	createSessionWorkflowJournal,
	type SessionWorkflowJournal,
} from "./journal.ts";
import { initialReducerState } from "./progress.ts";
import {
	type BaseStepOptions,
	makeStepRunner,
	type RunnerContext,
	type StepDrivers,
	type StepRunner,
} from "./runner.ts";
import { loadUltraSettings, type UltraSettings } from "./settings.ts";
import {
	type DiscoveredWorkflow,
	DYNAMIC_EXTENSION_TOOL_NAMES,
	discoverWorkflows,
	missingWorkflowTools,
	type WorkflowSpec,
	WorkflowSpecSchema,
	workflowUsesDynamicExtensions,
} from "./spec.ts";
import { renderUltraResult, UltraOverlayComponent } from "./ui.ts";
import {
	completeUltraCommand,
	formatWorkflowResultMessage,
	makeToolProgressSink,
	parseCommandLine,
	parseUltraCommand,
	resolveWorkflowInput,
} from "./wire.ts";

interface SubagentExtensionSelection {
	all: boolean;
	paths: string[];
	pathKeys: Set<string>;
}

function pathKey(path: string): string {
	const absolute = resolve(path).replaceAll("\\", "/");
	return process.platform === "win32" ? absolute.toLowerCase() : absolute;
}

export function resolveSubagentExtensions(
	setting: UltraSettings["subagentExtensions"],
): SubagentExtensionSelection {
	if (setting === "all") return { all: true, paths: [], pathKeys: new Set() };
	if (setting === "none") return { all: false, paths: [], pathKeys: new Set() };

	const paths = setting.map((name) => {
		if (!/^[a-z0-9][a-z0-9-]*$/u.test(name))
			throw new Error(`ultra: invalid sub-agent extension name: ${name}`);
		const path = fileURLToPath(new URL(`../${name}/index.ts`, import.meta.url));
		if (!existsSync(path))
			throw new Error(`ultra: unknown sub-agent extension: ${name}`);
		return path;
	});
	return { all: false, paths, pathKeys: new Set(paths.map(pathKey)) };
}

export function createUltraRuntime(pi: ExtensionAPI) {
	const settings = (cwd: string): UltraSettings => {
		const manager = SettingsManager.create(cwd);
		return loadUltraSettings({
			global: manager.getGlobalSettings(),
			project: manager.getProjectSettings(),
		});
	};

	// Workflow files are tiny and human-authored during live sessions. Rescan at
	// each use so a newly saved workflow immediately works without `/reload`.
	const discover = (cwd: string): DiscoveredWorkflow[] =>
		discoverWorkflows(cwd);

	let authoringPrompt: string | undefined;
	const loadAuthoringPrompt = (): string => {
		if (!authoringPrompt) {
			const guide = readFileSync(
				new URL("./prompts/authoring-workflows.md", import.meta.url),
				"utf8",
			).trim();
			const reference = readFileSync(
				new URL("./prompts/references/spec-format.md", import.meta.url),
				"utf8",
			).trim();
			authoringPrompt = `${guide}\n\n# Ultra workflow spec reference\n\n${reference}`;
		}
		return authoringPrompt;
	};

	const activateWorkflowTool = () => {
		const active = pi.getActiveTools();
		if (!active.includes("run_workflow")) {
			pi.setActiveTools([...active, "run_workflow"]);
		}
	};

	const deactivateWorkflowTool = () => {
		const active = pi.getActiveTools();
		if (active.includes("run_workflow")) {
			pi.setActiveTools(active.filter((name) => name !== "run_workflow"));
		}
	};

	const availableSubagentTools = (
		extensions: SubagentExtensionSelection,
	): string[] =>
		pi
			.getAllTools()
			.filter(
				(tool) =>
					tool.name !== "run_workflow" &&
					(extensions.all ||
						BUILTIN_TOOL_NAMES.has(tool.name) ||
						tool.sourceInfo.source === "builtin" ||
						extensions.pathKeys.has(pathKey(tool.sourceInfo.path))),
			)
			.map((tool) => tool.name);

	const unavailableToolError = (
		spec: WorkflowSpec,
		extensions: SubagentExtensionSelection,
	): string | undefined => {
		const available = [
			...availableSubagentTools(extensions),
			...DYNAMIC_EXTENSION_TOOL_NAMES,
		];
		const missing = missingWorkflowTools(spec, available);
		return missing.length > 0
			? `ultra: workflow "${spec.name}" requires unavailable tools: ${missing.join(", ")}`
			: undefined;
	};

	const createJournal = (
		ctx: ExtensionContext,
		spec: WorkflowSpec,
		args?: Record<string, unknown>,
	) =>
		createSessionWorkflowJournal({
			cwd: ctx.cwd,
			spec,
			args,
			entries: ctx.sessionManager.getBranch(),
			appendEntry: (customType, data) => pi.appendEntry(customType, data),
		});

	// Assemble a real `StepRunner` from the injected SDK drivers + this ctx.
	const buildStepRunner = (
		ctx: ExtensionContext,
		spec: WorkflowSpec,
		cfg: UltraSettings,
		journal: SessionWorkflowJournal,
		extensions: SubagentExtensionSelection,
		dynamicExtensions?: DynamicExtensionResolver,
	): StepRunner => {
		// The injected-dep types are deliberately broader than the SDK's specific
		// signatures (so the factories unit-test with simple fakes); the real SDK
		// values are adapted to them here at the boundary. Runtime correctness of
		// these calls is the Task-10 live gate.
		const drivers: StepDrivers = {
			sessionFactory: makeSessionFactory({
				createAgentSession:
					createAgentSession as unknown as SessionFactoryDeps["createAgentSession"],
				DefaultResourceLoader:
					DefaultResourceLoader as unknown as SessionFactoryDeps["DefaultResourceLoader"],
				getAgentDir,
				cwd: ctx.cwd,
				loadExtensions: extensions.all,
				extensionPaths: extensions.paths,
				loadSkills: cfg.subagentSkills === "all",
			}),
			resolveModel: makeResolveModel({
				modelRegistry: ctx.modelRegistry,
				defaultModel: ctx.model,
			}),
		};
		const manageSubagentSession = makeSubagentSessionManager({
			SessionManager,
			cwd: ctx.cwd,
			parentSession: ctx.sessionManager.getSessionFile(),
			retention: cfg.subagentSessionRetention,
		});
		const ctxLike: RunnerContext = {
			newSessionManager(sessionKey, agentId) {
				const retained = journal.getSession(sessionKey);
				const child = manageSubagentSession({
					name: `ultra ${spec.name} ${journal.id.slice(0, 8)} ${agentId}`,
					retained,
				});
				if (
					child.ref &&
					(!retained ||
						child.ref.id !== retained.id ||
						child.ref.path !== retained.path)
				)
					journal.setSession(sessionKey, child.ref);
				return child;
			},
		};
		const baseOpts: BaseStepOptions = {
			maxRetries: cfg.maxRetries,
			schemas: spec.schemas,
			modelTiers: cfg.modelTiers,
			actionSummarizer: createActionSummarizer(ctx, cfg.actionSummarizerModel),
			dynamicExtensionResolver: dynamicExtensions,
		};
		return makeStepRunner(drivers, ctxLike, baseOpts);
	};

	const dynamicResolver = async (
		ctx: ExtensionContext,
		spec: WorkflowSpec,
		journal: SessionWorkflowJournal,
		extensions: SubagentExtensionSelection,
	): Promise<DynamicExtensionResolver | undefined> => {
		if (!workflowUsesDynamicExtensions(spec)) return undefined;
		const { createDynamicExtensionCoordinator } = await import(
			"./dynamic-catalog.ts"
		);
		return createDynamicExtensionCoordinator({
			agentDir: getAgentDir(),
			parentSessionId: ctx.sessionManager.getSessionId(),
			workflowRunId: journal.id,
			availableTools: availableSubagentTools(extensions),
		});
	};

	// ── `run_workflow` tool (model-callable, mid-turn, read-only onUpdate surface) ──
	pi.registerTool({
		name: "run_workflow",
		label: "run_workflow",
		description:
			"Run one complete saved or inline Ultra multi-agent workflow. " +
			"Use it when independent parallel work, staged agent handoffs, or isolated specialist contexts materially improve the result; otherwise work directly. " +
			"It returns one aggregate of structured step results, validating each declared output schema.",
		promptSnippet:
			"Run one complete saved or inline multi-agent workflow and return its validated aggregate result.",
		promptGuidelines: [
			"Use run_workflow only when independent parallel work, staged agent handoffs, isolated specialist contexts, or a reusable purpose-built dynamic extension materially improve the result; otherwise work directly.",
			"Use run_workflow builder phases for dynamic-extension discovery, creation, improvement, stale validation, or repair; known validated names may load directly in consumer steps.",
			"After run_workflow returns, synthesize its aggregate result into the user-facing response.",
		],
		parameters: Type.Object({
			name: Type.Optional(
				Type.String({
					description: "Name of a saved workflow (project / global / bundled).",
				}),
			),
			spec: Type.Optional(WorkflowSpecSchema),
			args: Type.Optional(
				Type.Record(Type.String(), Type.Unknown(), {
					description:
						"Workflow input values exposed to prompts and selectors as {args.NAME}.",
				}),
			),
		}),
		renderResult: renderUltraResult,
		async execute(_toolCallId, params, signal, onUpdate, ctx) {
			const cfg = settings(ctx.cwd);
			if (!cfg.enabled) {
				return {
					content: [
						{
							type: "text",
							text: "ultra is disabled (ultra.enabled = false).",
						},
					],
					details: initialReducerState(),
				};
			}
			const { spec, args } = resolveWorkflowInput(params, discover(ctx.cwd));
			const extensions = resolveSubagentExtensions(cfg.subagentExtensions);
			const toolError = unavailableToolError(spec, extensions);
			if (toolError) throw new Error(toolError);
			const journal = createJournal(ctx, spec, args);
			const dynamicExtensions = await dynamicResolver(
				ctx,
				spec,
				journal,
				extensions,
			);
			const stepRunner = buildStepRunner(
				ctx,
				spec,
				cfg,
				journal,
				extensions,
				dynamicExtensions,
			);
			// onProgress folds into the reducer + pushes through `onUpdate`; headless
			// (no `onUpdate`) degrades to a no-op sink that still tracks final state.
			const progress = makeToolProgressSink(onUpdate ?? (() => {}), {
				workflowName: spec.name,
				workflowDescription: spec.description,
			});
			const result = await runWorkflow(spec, args, {
				stepRunner,
				concurrency: cfg.concurrency,
				journal,
				dynamicExtensions,
				signal, // the SDK execute() signal: stops the pool + fans session.abort()
				onProgress: progress.sink,
			});
			return {
				content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
				details: progress.finish(result),
				terminate: false, // the agent keeps reasoning over the results
			};
		},
	});

	deactivateWorkflowTool();

	const sendAuthoringPrompt = (request: string) => {
		activateWorkflowTool();
		pi.sendUserMessage(
			`${loadAuthoringPrompt()}\n\n# User request\n\n${request}`,
		);
	};

	// ── `/ultra [exec | run]` command ──
	return {
		activateWorkflowTool,
		getArgumentCompletions: (prefix: string) =>
			completeUltraCommand(discover(process.cwd()), prefix),
		handleCommand: async (argString: string, ctx: ExtensionCommandContext) => {
			const cfg = settings(ctx.cwd);
			if (!cfg.enabled) {
				if (ctx.hasUI)
					ctx.ui.notify(
						"ultra is disabled (ultra.enabled = false).",
						"warning",
					);
				return;
			}
			// The command surface is the focus-grabbing overlay — interactive only.
			// Headless / non-UI callers use the `run_workflow` tool instead.
			if (!ctx.hasUI) {
				return;
			}
			const command = parseUltraCommand(argString);
			if (command.subcommand === "activate") {
				activateWorkflowTool();
				ctx.ui.notify("ultra: run_workflow tool enabled.", "info");
				return;
			}
			if (command.subcommand === "exec") {
				sendAuthoringPrompt(command.instructions);
				return;
			}
			if (command.subcommand === "invalid") {
				ctx.ui.notify(
					"Usage: /ultra | /ultra exec <instructions> | /ultra run <workflow> [args]",
					"warning",
				);
				return;
			}

			const discovered = discover(ctx.cwd);
			const parsed = parseCommandLine(command.invocation);
			let resolved: { spec: WorkflowSpec; args?: Record<string, unknown> };
			try {
				resolved = resolveWorkflowInput(
					{ name: parsed.name, args: parsed.args },
					discovered,
					parsed.rest,
				);
			} catch (err) {
				ctx.ui.notify(
					err instanceof Error ? err.message : String(err),
					"error",
				);
				return;
			}
			const { spec, args: runArgs } = resolved;
			let extensions: SubagentExtensionSelection;
			try {
				extensions = resolveSubagentExtensions(cfg.subagentExtensions);
			} catch (error) {
				ctx.ui.notify(
					error instanceof Error ? error.message : String(error),
					"error",
				);
				return;
			}
			const toolError = unavailableToolError(spec, extensions);
			if (toolError) {
				ctx.ui.notify(toolError, "error");
				return;
			}
			const journal = createJournal(ctx, spec, runArgs);
			const dynamicExtensions = await dynamicResolver(
				ctx,
				spec,
				journal,
				extensions,
			);
			const stepRunner = buildStepRunner(
				ctx,
				spec,
				cfg,
				journal,
				extensions,
				dynamicExtensions,
			);

			// The command owns its AbortController (idle ⇒ ctx.signal is undefined).
			// Global Esc / per-agent abort fire it; the engine fans session.abort().
			const controller = new AbortController();
			const outcome = await ctx.ui.custom<
				| { status: "completed"; result: WorkflowResult }
				| { status: "aborted"; result?: WorkflowResult }
				| { status: "failed"; message: string }
				| null
			>(
				(tui, theme, keybindings, done) => {
					const overlay = new UltraOverlayComponent({
						host: tui,
						theme,
						onRunAbort: () => controller.abort(),
						workflowName: spec.name,
						workflowDescription: spec.description,
						toolUi: tui,
						toolsExpanded: () => ctx.ui.getToolsExpanded(),
						hideToolPreviews: cfg.actionSummarizerModel !== null,
						isToolsExpandKey: (data) =>
							keybindings.matches(data, "app.tools.expand"),
						onToolsExpand: () =>
							ctx.ui.setToolsExpanded(!ctx.ui.getToolsExpanded()),
						cwd: ctx.cwd,
					});
					// P3: return the Component SYNCHRONOUSLY; run the engine DETACHED, or
					// the overlay never renders. `done` resolves the custom() promise.
					void (async () => {
						try {
							const r = await runWorkflow(spec, runArgs, {
								stepRunner,
								concurrency: cfg.concurrency,
								journal,
								dynamicExtensions,
								signal: controller.signal,
								onProgress: (e) => overlay.handleProgress(e),
							});
							done(
								controller.signal.aborted
									? { status: "aborted", result: r }
									: { status: "completed", result: r },
							);
						} catch (error) {
							done(
								controller.signal.aborted
									? { status: "aborted" }
									: {
											status: "failed",
											message:
												error instanceof Error ? error.message : String(error),
										},
							);
						}
					})();
					return overlay;
				},
				{
					overlay: true,
					overlayOptions: {
						anchor: "bottom-left",
						width: "100%",
						maxHeight: "100%",
					},
				},
			);

			if (!outcome) {
				ctx.ui.notify(`ultra: "${spec.name}" aborted.`, "warning");
				return;
			}
			if (outcome.status === "failed") {
				ctx.ui.notify(outcome.message, "error");
				return;
			}
			const result = outcome.result;
			if (!result) {
				ctx.ui.notify(`ultra: "${spec.name}" aborted.`, "warning");
				return;
			}
			const count = Array.isArray(result.result)
				? `${result.result.length} results`
				: "done";
			pi.sendMessage({
				customType: "ultra-result",
				content: formatWorkflowResultMessage(result),
				display: true,
				details: result,
			});
			if (outcome.status === "aborted")
				ctx.ui.notify(`ultra: "${spec.name}" aborted.`, "warning");
			else
				ctx.ui.notify(
					`ultra: "${result.workflow}" complete — ${result.phases.length} phases, ${count}` +
						`${result.steered ? " (steered)" : ""}.`,
					"info",
				);
		},
	};
}