pi-devin-fusion 0.1.0

package/src/llm.ts

@@ -0,0 +1,248 @@
+/**
+ * Low-level LLM calls for pi-devin-fusion (executor loop).
+ */
+
+import {
+	complete,
+	type AssistantMessage,
+	type Message,
+	type Tool,
+	type ToolCall,
+	type ToolResultMessage,
+} from "@earendil-works/pi-ai/compat";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ProviderStreamOptions } from "@earendil-works/pi-ai/compat";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { TOOL_OUTPUT_MAX_BYTES } from "./config.ts";
+import type { ExecutorToolDef } from "./tools.ts";
+import { truncateToBytes } from "./utils.ts";
+
+type ToolContent = ToolResultMessage["content"];
+
+interface CompleteOptions extends ProviderStreamOptions {
+	apiKey: string;
+	headers?: Record<string, string>;
+	maxTokens: number;
+	temperature?: number;
+}
+
+async function buildCompleteOptions(
+	registry: ModelRegistry,
+	model: Model<Api>,
+	maxTokens: number,
+	temperature: number,
+	signal: AbortSignal | undefined,
+): Promise<CompleteOptions> {
+	const auth = await registry.getApiKeyAndHeaders(model);
+	if (!auth.ok || !auth.apiKey) {
+		throw new Error(auth.ok ? `No API key for ${model.provider}/${model.id}` : auth.error);
+	}
+	const options: CompleteOptions = {
+		apiKey: auth.apiKey,
+		headers: auth.headers,
+		signal,
+		maxTokens,
+	};
+	// Some models (e.g. Anthropic Claude Opus 4.7+, OpenAI Codex) reject temperature.
+	if (getSupportsTemperature(model)) {
+		options.temperature = temperature;
+	}
+	return options;
+}
+
+export async function callModelText(
+	registry: ModelRegistry,
+	model: Model<Api>,
+	systemPrompt: string,
+	userText: string,
+	maxTokens: number,
+	temperature: number,
+	signal: AbortSignal | undefined,
+): Promise<AssistantMessage> {
+	const options = await buildCompleteOptions(registry, model, maxTokens, temperature, signal);
+	return runComplete(
+		model,
+		{ systemPrompt, messages: [{ role: "user", content: userText, timestamp: Date.now() }] },
+		options,
+	);
+}
+
+export interface ToolLoopResult {
+	/** Final assistant message (its text is the executor answer). */
+	message: AssistantMessage;
+	/** Number of complete() calls made. */
+	turns: number;
+	/** Every tool call attempted, with success flag. */
+	toolCalls: Array<{ name: string; ok: boolean }>;
+	/** True when the loop was forced to finalize (cap or circuit breaker) before a natural stop. */
+	cappedOut: boolean;
+}
+
+/**
+ * Run a model through an internal agentic tool loop, bounded by `maxToolCalls`.
+ *
+ * The model may call the provided tools across multiple turns; each tool result
+ * is fed back until the model returns text on its own, the cap is reached, or a
+ * circuit breaker trips. On any forced finish, a final tool-free completion is
+ * requested so the executor always returns a text answer.
+ */
+export async function callModelWithTools(
+	registry: ModelRegistry,
+	model: Model<Api>,
+	systemPrompt: string,
+	userText: string,
+	maxTokens: number,
+	temperature: number,
+	signal: AbortSignal | undefined,
+	toolDefs: ExecutorToolDef[],
+	maxToolCalls: number,
+	ctx: ExtensionContext,
+	onToolEvent?: (ev: { name: string; turn: number; ok: boolean }) => void,
+): Promise<ToolLoopResult> {
+	const options = await buildCompleteOptions(registry, model, maxTokens, temperature, signal);
+	const tools: Tool[] = toolDefs.map((d) => ({ name: d.name, description: d.description, parameters: d.parameters }));
+	const byName = new Map(toolDefs.map((d) => [d.name, d]));
+
+	const messages: Message[] = [{ role: "user", content: userText, timestamp: Date.now() }];
+	const toolCalls: Array<{ name: string; ok: boolean }> = [];
+	let turns = 0;
+	let used = 0;
+	let lastKey: string | undefined;
+	let repeatRun = 0;
+	let errorStreak = 0;
+
+	while (true) {
+		const resp = await runComplete(model, { systemPrompt, messages, tools }, options);
+		turns++;
+
+		const calls = resp.content.filter((c): c is ToolCall => c.type === "toolCall");
+		if (resp.stopReason !== "toolUse" || calls.length === 0) {
+			return { message: resp, turns, toolCalls, cappedOut: false };
+		}
+
+		messages.push(resp);
+		let forceFinalize = false;
+
+		for (const tc of calls) {
+			if (forceFinalize || used >= maxToolCalls) {
+				// Every ToolCall must get a paired result or the next request 400s.
+				messages.push(syntheticResult(tc, forceFinalize ? "stopped: repeated or failing tool calls" : "tool-call budget exhausted"));
+				toolCalls.push({ name: tc.name, ok: false });
+				continue;
+			}
+
+			const ok = await executeToolCall(tc, byName.get(tc.name), signal, ctx, messages);
+			used++;
+			toolCalls.push({ name: tc.name, ok });
+			onToolEvent?.({ name: tc.name, turn: turns, ok });
+
+			// Circuit breaker for TIGHT stuck-loops only: the exact same call (tool + args)
+			// 3x in a row, or 3 consecutive errors. The key includes arguments, so varied
+			// context-gathering — even many calls of the same tool with different paths/queries
+			// — never trips it; only a model spinning on the identical call does. maxToolCalls
+			// remains the hard upper bound.
+			const key = `${tc.name}:${JSON.stringify(tc.arguments)}`;
+			repeatRun = key === lastKey ? repeatRun + 1 : 1;
+			lastKey = key;
+			errorStreak = ok ? 0 : errorStreak + 1;
+			if (repeatRun >= 3 || errorStreak >= 3) {
+				forceFinalize = true;
+			}
+		}
+
+		if (forceFinalize || used >= maxToolCalls) {
+			// Tools exhausted or looping: ask for the final answer with tools omitted, and
+			// nudge via the system prompt (some models go silent when tools disappear unless
+			// explicitly told to answer now). System-prompt nudge avoids an illegal trailing
+			// user message after tool results.
+			const finalSystem = `${systemPrompt}\n\nYou have reached the tool-call limit. Write your complete final answer now using only what you have already gathered — do not request any more tools.`;
+			const finalMsg = await runComplete(model, { systemPrompt: finalSystem, messages }, options);
+			turns++;
+			return { message: finalMsg, turns, toolCalls, cappedOut: true };
+		}
+	}
+}
+
+async function runComplete(
+	model: Model<Api>,
+	context: { systemPrompt: string; messages: Message[]; tools?: Tool[] },
+	options: CompleteOptions,
+): Promise<AssistantMessage> {
+	const resp = await complete(model, context, options);
+	if (resp.stopReason === "error" || resp.stopReason === "aborted") {
+		throw new Error(resp.errorMessage ?? `Model stopped with reason: ${resp.stopReason}`);
+	}
+	return resp;
+}
+
+/** Execute one tool call, push its result message, and report success. Never throws. */
+async function executeToolCall(
+	tc: ToolCall,
+	def: ExecutorToolDef | undefined,
+	signal: AbortSignal | undefined,
+	ctx: ExtensionContext,
+	messages: Message[],
+): Promise<boolean> {
+	try {
+		if (!def) throw new Error(`unknown tool: ${tc.name}`);
+		// tc.arguments is already a parsed object — pass it straight through.
+		// Cancellation flows through the explicit `signal` arg, which every built-in
+		// tool honors (verified); no ctx.signal override is needed.
+		const out = await def.execute(tc.id, tc.arguments, signal, undefined, ctx);
+		messages.push({
+			role: "toolResult",
+			toolCallId: tc.id,
+			toolName: tc.name,
+			content: truncateToolContent(out.content),
+			isError: false,
+			timestamp: Date.now(),
+		});
+		return true;
+	} catch (err) {
+		const text = err instanceof Error ? err.message : String(err);
+		messages.push({
+			role: "toolResult",
+			toolCallId: tc.id,
+			toolName: tc.name,
+			content: [{ type: "text", text: `Error: ${text}` }],
+			isError: true,
+			timestamp: Date.now(),
+		});
+		return false;
+	}
+}
+
+function syntheticResult(tc: ToolCall, text: string): ToolResultMessage {
+	return {
+		role: "toolResult",
+		toolCallId: tc.id,
+		toolName: tc.name,
+		content: [{ type: "text", text }],
+		isError: true,
+		timestamp: Date.now(),
+	};
+}
+
+/** Bound tool output before it re-enters the loop transcript and the final answer. */
+function truncateToolContent(content: ToolContent): ToolContent {
+	return content.map((part) => {
+		if (part.type !== "text") return part;
+		const truncated = truncateToBytes(part.text, TOOL_OUTPUT_MAX_BYTES, "\n…[truncated]");
+		return truncated === part.text ? part : { type: "text", text: truncated };
+	});
+}
+
+export function getSupportsTemperature(model: Model<Api>): boolean {
+	// Anthropic encodes this in model metadata (e.g. Opus 4.7+ set supportsTemperature:false,
+	// some other providers omit the flag). Treat undefined as supported to avoid breaking calls.
+	const meta = model as unknown as { supportsTemperature?: boolean };
+	return meta.supportsTemperature !== false;
+}
+
+export function getTextContent(message: AssistantMessage): string {
+	const textParts = message.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map((c) => c.text);
+	return textParts.join("\n").trim();
+}

package/src/models.ts

@@ -0,0 +1,53 @@
+/**
+ * Model resolution and executor selection for pi-devin-fusion.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+
+export function modelDisplay(model: Model<Api>): string {
+	return `${model.provider}/${model.id}`;
+}
+
+export function resolveModelIdentifier(registry: ModelRegistry, identifier: string): Model<Api> | undefined {
+	const slash = identifier.indexOf("/");
+	if (slash > 0) {
+		const provider = identifier.slice(0, slash);
+		const id = identifier.slice(slash + 1);
+		return registry.getAll().find((m) => m.provider === provider && m.id === id);
+	}
+	// No provider prefix: search by exact id across all models.
+	return registry.getAll().find((m) => m.id === identifier);
+}
+
+/** Choose the executor model: configured first, else first non-current text authed model. */
+export function resolveExecutorModel(
+	registry: ModelRegistry,
+	currentModel: Model<Api> | undefined,
+	configuredExecutor: string | undefined,
+	warnings: string[],
+): Model<Api> | undefined {
+	if (configuredExecutor) {
+		const resolved = resolveModelIdentifier(registry, configuredExecutor);
+		if (resolved && resolved.input.includes("text") && registry.hasConfiguredAuth(resolved)) {
+			return resolved;
+		}
+		warnings.push(
+			resolved && registry.hasConfiguredAuth(resolved)
+				? `Configured executor ${configuredExecutor} is not a text-capable model; falling back to auto-selection.`
+				: `Configured executor ${configuredExecutor} is not authed; falling back to auto-selection.`,
+		);
+	}
+
+	const available = registry.getAvailable().filter((m) => m.input.includes("text"));
+	if (available.length === 0) return undefined;
+
+	const nonCurrent = currentModel
+		? available.filter((m) => modelDisplay(m) !== modelDisplay(currentModel))
+		: available;
+
+	if (nonCurrent.length > 0) return nonCurrent[0];
+
+	warnings.push("Executor fell back to the current planner model; cost savings are not guaranteed.");
+	return available[0];
+}

package/src/prompts.ts

@@ -0,0 +1,23 @@
+/**
+ * System prompts for pi-devin-fusion.
+ */
+
+export const PLANNER_FORCE_PROMPT_PREFIX = `You are the PLANNER/REVIEWER in a Devin-fusion style setup (pi-devin-fusion). You own the plan, the interpretation of ambiguity, and the final review. The SIDEKICK (a separate, cheaper executor model) owns mechanical implementation.
+
+Rules:
+- Delegate implementation and codebase exploration for code-changing work to the sidekick tool with a PRECISE spec: exact files, exact changes, constraints to preserve. Do not give vague goals.
+- Do NOT call native mutating tools (bash/edit/write) yourself for the implementation; the sidekick performs the edits. You may still read files and inspect diffs for review.
+- When the sidekick returns a result, review it against real command output and the plan before giving your final answer. If it is wrong, send corrected feedback through the sidekick tool rather than editing yourself.
+- For ambiguous intent or design choices, make the decision yourself, then hand the sidekick an unambiguous spec. Do not ask the sidekick to make the judgment call.
+- ASCII-only output.`;
+
+export const SIDEKICK_SYSTEM_PROMPT = `You are the SIDEKICK executor in a Devin-fusion style setup (pi-devin-fusion). The planner model owns the plan and final review; you own execution.
+
+Operating rules:
+- Execute the exact spec you are given. Do not redesign, rename beyond the spec, or touch files you were not asked to touch.
+- Produce complete, unabridged changes. No placeholders, no "// rest unchanged", no elided blocks.
+- Run verification yourself when asked (build / test / lint) and report the real command output, not a summary of what you expect to happen.
+- Read only the files you need to do the work; do not pull in the whole repository.
+- If the task turns out to need judgment (ambiguous intent, a design choice, a spec that contradicts itself), STOP and return exactly: NEEDS_DECISION: <the specific question to escalate>. Do not guess on judgment calls.
+- Return a concise result: what you changed (files + one line each), the verification you ran and its outcome, and anything the planner should review. No preamble, no self-congratulation.
+- ASCII-only output.`;

package/src/tools.ts

@@ -0,0 +1,108 @@
+/**
+ * Executor tool resolution for pi-devin-fusion.
+ *
+ * Tool definitions are built from a hard-coded allowlist of pi's own tool
+ * factories — never from the live extension registry — so the `sidekick` tool
+ * can never leak into the executor's tool list (recursion guarantee).
+ */
+
+import {
+	createBashToolDefinition,
+	createEditToolDefinition,
+	createFindToolDefinition,
+	createGrepToolDefinition,
+	createLsToolDefinition,
+	createReadToolDefinition,
+	createWriteToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import { DEFAULT_MAX_TOOL_CALLS, MAX_TOOL_CALLS, MIN_TOOL_CALLS } from "./config.ts";
+import type { ToolSelection } from "./types.ts";
+
+/**
+ * Subset of ToolDefinition used by the executor tool loop in llm.ts.
+ * Intentionally structural and minimal — the factory return types are
+ * heterogeneous TypeBox schemas we don't need to unify at the type level.
+ */
+export interface ExecutorToolDef {
+	name: string;
+	description: string;
+	parameters: TSchema;
+	execute(
+		toolCallId: string,
+		args: Record<string, unknown>,
+		signal: AbortSignal | undefined,
+		extra: unknown,
+		ctx: unknown,
+	): Promise<{ content: ToolResultMessage["content"]; isError: boolean }>;
+}
+
+export const READONLY_TOOL_NAMES = ["read", "grep", "find", "ls"] as const;
+export const MUTATING_TOOL_NAMES = ["bash", "edit", "write"] as const;
+export const ALL_TOOL_NAMES = [...READONLY_TOOL_NAMES, ...MUTATING_TOOL_NAMES] as const;
+
+type ToolName = (typeof ALL_TOOL_NAMES)[number];
+
+// Library boundary: the factory return types carry `any` TState from the
+// coding-agent. We narrow to our structural ExecutorToolDef with `unknown`
+// to keep source-level `any` out of this module.
+function build(name: ToolName, cwd: string): ExecutorToolDef {
+	switch (name) {
+		case "read": return createReadToolDefinition(cwd) as unknown as ExecutorToolDef;
+		case "grep": return createGrepToolDefinition(cwd) as unknown as ExecutorToolDef;
+		case "find": return createFindToolDefinition(cwd) as unknown as ExecutorToolDef;
+		case "ls": return createLsToolDefinition(cwd) as unknown as ExecutorToolDef;
+		case "bash": return createBashToolDefinition(cwd) as unknown as ExecutorToolDef;
+		case "edit": return createEditToolDefinition(cwd) as unknown as ExecutorToolDef;
+		case "write": return createWriteToolDefinition(cwd) as unknown as ExecutorToolDef;
+	}
+}
+
+function isToolName(value: string): value is ToolName {
+	return (ALL_TOOL_NAMES as readonly string[]).includes(value);
+}
+
+/** Normalize a selection (mode or explicit list) into an ordered, deduped tool-name list. */
+export function selectionToNames(selection: ToolSelection | undefined): ToolName[] {
+	if (!selection || selection === "none") return [];
+	if (selection === "readonly") return [...READONLY_TOOL_NAMES];
+	if (selection === "all") return [...ALL_TOOL_NAMES];
+	if (Array.isArray(selection)) {
+		const seen = new Set<string>();
+		const out: ToolName[] = [];
+		for (const raw of selection) {
+			const name = String(raw).toLowerCase();
+			if (isToolName(name) && !seen.has(name)) {
+				seen.add(name);
+				out.push(name);
+			}
+		}
+		return out;
+	}
+	return [];
+}
+
+/** Build executable tool definitions for the resolved selection. */
+export function resolveToolDefs(selection: ToolSelection | undefined, cwd: string): ExecutorToolDef[] {
+	return selectionToNames(selection).map((n) => build(n, cwd));
+}
+
+/** True when the selection includes a tool that can mutate the filesystem or run commands. */
+export function isMutatingSelection(selection: ToolSelection | undefined): boolean {
+	return selectionToNames(selection).some((n) => (MUTATING_TOOL_NAMES as readonly string[]).includes(n));
+}
+
+/** A short, stable label for a selection (for footers, status, diagnostics). */
+export function selectionLabel(selection: ToolSelection | undefined): string {
+	if (!selection || selection === "none") return "none";
+	if (selection === "readonly" || selection === "all") return selection;
+	const names = selectionToNames(selection);
+	return names.length ? names.join(",") : "none";
+}
+
+/** Clamp a max-tool-calls value into the supported range, defaulting when absent. */
+export function clampMaxToolCalls(value: number | undefined): number {
+	if (value === undefined || !Number.isFinite(value)) return DEFAULT_MAX_TOOL_CALLS;
+	return Math.max(MIN_TOOL_CALLS, Math.min(MAX_TOOL_CALLS, Math.floor(value)));
+}

package/src/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared types for pi-devin-fusion.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+
+export type { Api, Model };
+
+/** Named executor tool bundles, or an explicit list of tool names. */
+export type ToolMode = "none" | "readonly" | "all";
+export type ToolSelection = ToolMode | string[];
+export type FooterDisplay = "off" | "compact" | "full";
+export type DevinMode = "available" | "forced" | "off";
+
+export interface DevinConfig {
+	/** Explicit executor model identifier, e.g. "anthropic/claude-haiku-4-5". */
+	executor?: string;
+	/** Max tokens for the executor's final answer. */
+	maxExecutorOutputTokens?: number;
+	/** Sampling temperature for the executor. */
+	temperature?: number;
+	/** Executor tool access: "none", "readonly" (read/grep/find/ls), or "all" (adds bash/edit/write). */
+	executorTools?: ToolSelection;
+	/** Max tool-call steps the executor may take (1–100). */
+	maxToolCalls?: number;
+	/** Non-interactive consent for mutating executor tools (bash/edit/write). */
+	executorToolsConsent?: boolean;
+	/** Footer verbosity: "full" (default), "compact", or "off". */
+	footerDisplay?: FooterDisplay;
+}
+
+/** A DevinConfig after `applyDefaults`: the numeric/tool knobs are guaranteed present. */
+export type ResolvedDevinConfig = DevinConfig & {
+	maxExecutorOutputTokens: number;
+	temperature: number;
+	executorTools: ToolSelection;
+	maxToolCalls: number;
+	footerDisplay: FooterDisplay;
+};
+
+/** Options accepted from a session/extension override (planner cannot override tools). */
+export interface SidekickOptions {
+	executor?: string;
+	executorTools?: ToolSelection;
+	maxToolCalls?: number;
+	footerDisplay?: FooterDisplay;
+	context_text?: string;
+}
+
+export interface SidekickResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: SidekickDetails;
+}
+
+export interface SidekickDetails {
+	status: "ok" | "error";
+	executor_model?: string;
+	turns?: number;
+	tool_calls?: Array<{ name: string; ok: boolean }>;
+	capped?: boolean;
+	warnings?: string[];
+	output?: string;
+	error?: string;
+	failure_reason?:
+		| "mutation_consent_required"
+		| "no_executor_model"
+		| "rate_limited"
+		| "insufficient_credits"
+		| "unexpected_error";
+}