// 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; } 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, ) => 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 => { 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 | /ultra run [args]", "warning", ); return; } const discovered = discover(ctx.cwd); const parsed = parseCommandLine(command.invocation); let resolved: { spec: WorkflowSpec; args?: Record }; 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", ); }, }; }