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",
);
},
};
}