pi-devin-fusion 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# pi-devin-fusion
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Devin Fusion "sidekick" pattern for [pi](https://github.com/earendil-works/pi).
+
+Two models work together: the active **planner** (you pick it) plans and reviews, and a cheaper **executor** (auto-selected) implements. The planner delegates to the executor via the `sidekick` tool. Mutating executor tools require consent and run serialized to prevent clobbered writes.
+
+## Why
+
+From [Cognition's blog post](https://cognition.com/blog/devin-fusion):
+
+> the main agent should take minimal actions, and only read what is absolutely necessary. By default it should delegate and monitor, while making the significant decisions: the plan, the interpretation of ambiguity, the final review.
+
+This extension makes that pattern work in pi — not as a suggestion, but as a mechanical tool wrapper. The planner model is always in control; the executor model runs a controlled tool loop with bounded turns.
+
+## Installation
+
+Install directly in your pi project:
+
+```bash
+pi install ./
+```
+
+Or install from npm:
+
+```bash
+pi install npm:pi-devin-fusion
+```
+
+You can also install from a local path:
+
+```bash
+pi install ./path/to/pi-devin-fusion
+```
+
+## Usage
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/devin on` / `forced` | Force every user message through the planner/sidekick split |
+| `/devin available` / `auto` | Let the model decide when to use the sidekick (default) |
+| `/devin off` | Disable the sidekick tool for this session |
+| `/devin <prompt>` | Send a prompt through the forced planner prefix once |
+| `/devin-setup` | Interactive picker to choose executor model, tools, and config (session-scoped) |
+| `/devin-init` | Create a `.pi/devin.json` template to set the executor model and tool selection |
+| `/devin-status` | Show current Devin mode, executor, tool selection, and consent state |
+### Tools
+
+The extension registers one tool:
+
+- **`sidekick`** — Delegate a task to the executor model. Accepts a `prompt` string, optional `context_mode` (`"none"` / `"recent"`), and optional `context_turns` (1–10, default 4 for "recent" mode).
+
+## Workflow
+
+### Interactive setup (recommended for first use)
+
+1. Run `/devin-setup` to pick an executor model and session config interactively.
+2. Turn Devin on with `/devin on`.
+3. Ask your question. The model uses the sidekick executor for implementation tasks.
+
+### Config-file setup
+
+1. (Optional) Run `/devin-init` to create a `.pi/devin.json` template.
+2. Turn Devin on with `/devin on`.
+3. Ask your question.
+
+The planner delegates to the sidekick executor for exploration and implementation; it reviews
+the result before responding. Use `/devin <prompt>` for a one-off delegation without changing the mode.
+
+### Session vs file configuration
+
+Settings from `/devin-setup` take precedence over `.pi/devin.json`. Session state persists
+within the conversation and is restored on session restore. Use `/devin-status` to inspect
+the effective configuration.
+
+## Configuration
+
+`.pi/devin.json` in your project root:
+
+```json
+{
+  "$schema": "devin-fusion-config",
+  "executor": "openai/gpt-4.1-mini",
+  "executorTools": "all",
+  "executorToolsConsent": false,
+  "maxExecutorOutputTokens": 4096,
+  "temperature": 0.2,
+  "maxToolCalls": 16,
+  "footerDisplay": "full"
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `executor` | auto-selected | Model identifier for the executor (e.g. `"openai/gpt-4.1-mini"`). Auto-selects the first non-current text model if unset. |
+| `executorTools` | `"all"` | Tool selection: `"none"`, `"readonly"`, `"all"`, or an array like `["read", "grep", "write"]`. |
+| `executorToolsConsent` | `false` | When `true`, skips the consent prompt for mutating tools. |
+| `maxExecutorOutputTokens` | `4096` | Max output tokens per executor call. |
+| `temperature` | `0.2` | Temperature for the executor model. |
+| `maxToolCalls` | `16` | Max tool calls per executor run (clamped to 1–100). |
+| `footerDisplay` | `"full"` | Footer verbosity: `"full"`, `"compact"`, or `"off"`. |
+
+**Session precedence:** `/devin-setup` selection overrides `.pi/devin.json`. Session state persists in the conversation and is restored on session restore.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | Extension entry: `sidekick` tool, `/devin` commands, session state, footers |
+| `src/config.ts` | Config loading, defaults, template generation |
+| `src/context.ts` | Context normalization and recent-history builder |
+| `src/executor.ts` | Executor pipeline: model resolution, consent gate, serialized mutating runs |
+| `src/executor_policy.ts` | Pure consent-policy check (testable without models) |
+| `src/llm.ts` | Low-level LLM calls, tool loop, circuit breakers, output truncation |
+| `src/models.ts` | Model resolution helpers, executor auto-selection with auth check |
+| `src/prompts.ts` | Planner prefix prompt and sidekick system prompt |
+| `src/tools.ts` | Tool-definition factory, selection normalization, mutating detection |
+| `src/types.ts` | Shared DevinConfig, SidekickOptions, ToolSelection, FooterDisplay types |
+| `src/ui.ts` | Interactive session setup picker via pi TUI components |
+| `src/utils.ts` | Concurrency-limited map, byte truncation, JSON extraction |
+## Credit
+
+Inspired by [Devin Fusion](https://cognition.com/blog/devin-fusion) by [Cognition](https://cognition.com).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "pi-devin-fusion",
+  "version": "0.1.0",
+  "description": "Devin sidekick planner/executor split for pi, inspired by devin fusion",
+  "type": "module",
+  "main": "./src/index.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khanhdeptraivaicachuong/pi-devin-fusion.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "src/*.ts",
+    "README.md",
+    "LICENSE",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "clean": "rm -rf node_modules",
+    "build": "echo 'pi-devin-fusion is loaded directly by pi via jiti; no build step required'",
+    "check": "tsc --noEmit",
+    "test": "node --import jiti/register src/__tests__/run.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "keywords": ["pi-package", "pi-extension", "devin", "fusion", "sidekick", "planner", "executor", "coding-agent", "llm"],
+  "dependencies": {},
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "jiti": "^2.4.0",
+    "typescript": "^5.5.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,73 @@
+/**
+ * Devin configuration loading and validation.
+ */
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { DevinConfig, ResolvedDevinConfig } from "./types.ts";
+
+export type { DevinConfig, ResolvedDevinConfig };
+
+export const DEFAULT_MAX_EXECUTOR_OUTPUT_TOKENS = 4096;
+export const DEFAULT_TEMPERATURE = 0.2;
+export const DEFAULT_EXECUTOR_TOOLS: "all" = "all";
+export const DEFAULT_MAX_TOOL_CALLS = 16;
+export const MIN_TOOL_CALLS = 1;
+export const MAX_TOOL_CALLS = 100;
+/** Per tool result, before it re-enters the loop transcript (keeps executor context bounded). */
+export const TOOL_OUTPUT_MAX_BYTES = 12_000;
+
+export function loadConfig(cwd: string, projectTrusted: boolean): DevinConfig {
+	const paths: string[] = [];
+	if (projectTrusted) {
+		paths.push(join(cwd, ".pi", "devin.json"));
+	}
+	paths.push(join(getAgentDir(), "devin.json"));
+
+	for (const path of paths) {
+		if (!existsSync(path)) continue;
+		try {
+			return JSON.parse(readFileSync(path, "utf8")) as DevinConfig;
+		} catch (err) {
+			console.error(`[pi-devin-fusion] failed to parse ${path}:`, err);
+		}
+	}
+	return {};
+}
+
+export function applyDefaults(
+	config: DevinConfig,
+	overrides: Pick<DevinConfig, "executor" | "executorTools" | "maxToolCalls" | "footerDisplay"> = {},
+): ResolvedDevinConfig {
+	const merged: DevinConfig = { ...config };
+	if (overrides.executor !== undefined) merged.executor = overrides.executor;
+	if (overrides.executorTools !== undefined) merged.executorTools = overrides.executorTools;
+	if (overrides.maxToolCalls !== undefined) merged.maxToolCalls = overrides.maxToolCalls;
+	if (overrides.footerDisplay !== undefined) merged.footerDisplay = overrides.footerDisplay;
+
+	// Single source of truth for defaults: callers can read these knobs directly.
+	// The invoking model/tool can only choose context; executor, tools, max calls,
+	// output tokens, and temperature are user config/session setup or defaults.
+	return {
+		...merged,
+		executor: merged.executor,
+		maxExecutorOutputTokens: merged.maxExecutorOutputTokens ?? DEFAULT_MAX_EXECUTOR_OUTPUT_TOKENS,
+		temperature: merged.temperature ?? DEFAULT_TEMPERATURE,
+		executorTools: merged.executorTools ?? DEFAULT_EXECUTOR_TOOLS,
+		maxToolCalls: merged.maxToolCalls ?? DEFAULT_MAX_TOOL_CALLS,
+		footerDisplay: merged.footerDisplay ?? "full",
+	};
+}
+
+export function generateConfigExample(executor?: string): DevinConfig {
+	return {
+		...(executor ? { executor } : {}),
+		maxExecutorOutputTokens: DEFAULT_MAX_EXECUTOR_OUTPUT_TOKENS,
+		temperature: DEFAULT_TEMPERATURE,
+		executorTools: DEFAULT_EXECUTOR_TOOLS,
+		maxToolCalls: DEFAULT_MAX_TOOL_CALLS,
+		executorToolsConsent: false,
+		footerDisplay: "full",
+	};
+}

package/src/context.ts

@@ -0,0 +1,86 @@
+/**
+ * Conversation-context helpers for optional executor context.
+ */
+
+const MAX_CONTEXT_TURNS = 10;
+const DEFAULT_CONTEXT_TURNS = 4;
+const MAX_CONTEXT_CHARS = 20000;
+
+export type DevinContextMode = "none" | "recent";
+
+export function normalizeContextTurns(value: number | undefined): number {
+	if (value === undefined || !Number.isFinite(value)) return DEFAULT_CONTEXT_TURNS;
+	return Math.max(1, Math.min(MAX_CONTEXT_TURNS, Math.floor(value)));
+}
+
+interface MaybeMessage {
+	content?: unknown;
+}
+
+function getContentText(content: unknown): string {
+	if (typeof content === "string") return content.trim();
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((part) => {
+			if (typeof part === "string") return part;
+			if (part && typeof part === "object" && "type" in part) {
+				const p = part as { type?: unknown };
+				if (p.type === "text") {
+					const text = (part as { text?: unknown }).text;
+					return typeof text === "string" ? text : "";
+				}
+			}
+			return "";
+		})
+		.join("\n")
+		.trim();
+}
+
+export function extractMessageText(message: unknown): string {
+	const m = message as MaybeMessage;
+	return getContentText(m?.content);
+}
+
+export function buildRecentContextFromEntries(entries: unknown[], turns: number | undefined): string | undefined {
+	const maxTurns = normalizeContextTurns(turns);
+	const messages: Array<{ role: "user" | "assistant"; text: string }> = [];
+	let userMessagesSeen = 0;
+
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i] as { type?: unknown; message?: MaybeMessage };
+		if (entry?.type !== "message" || !entry.message) continue;
+		const role = (entry.message as { role?: unknown }).role;
+		if (role !== "user" && role !== "assistant") continue;
+		const text = getContentText(entry.message.content);
+		if (!text) continue;
+		messages.unshift({ role: role as "user" | "assistant", text });
+		if (role === "user") {
+			userMessagesSeen++;
+			if (userMessagesSeen >= maxTurns) break;
+		}
+	}
+
+	if (messages.length === 0) return undefined;
+
+	let rendered = messages
+		.map((m) => `${m.role === "user" ? "User" : "Assistant"}: ${m.text}`)
+		.join("\n\n");
+
+	if (rendered.length > MAX_CONTEXT_CHARS) {
+		rendered = rendered.slice(rendered.length - MAX_CONTEXT_CHARS).trimStart();
+		rendered = `[truncated to last ${MAX_CONTEXT_CHARS} chars]\n${rendered}`;
+	}
+
+	return rendered;
+}
+
+export function buildSidekickTaskText(prompt: string, contextText: string | undefined): string {
+	if (!contextText?.trim()) return prompt;
+	return [
+		"Recent conversation context:",
+		contextText.trim(),
+		"",
+		"Current task:",
+		prompt.trim(),
+	].join("\n");
+}

package/src/executor.ts

@@ -0,0 +1,127 @@
+/**
+ * Single-executor (sidekick) pipeline: resolve executor, run its tool loop.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { applyDefaults, loadConfig } from "./config.ts";
+import { buildSidekickTaskText } from "./context.ts";
+import { SIDEKICK_SYSTEM_PROMPT } from "./prompts.ts";
+import { callModelWithTools, getTextContent } from "./llm.ts";
+import { resolveExecutorModel } from "./models.ts";
+import { isMutatingSelection, resolveToolDefs } from "./tools.ts";
+import type { SidekickOptions, SidekickResult } from "./types.ts";
+
+/** Serialize runs that can mutate shared filesystem/state to avoid clobbered writes. */
+let mutationQueue: Promise<unknown> = Promise.resolve();
+function runSerialized<T>(fn: () => Promise<T>): Promise<T> {
+	const run = mutationQueue.then(fn, fn);
+	// Keep the chain alive even if a run rejects.
+	mutationQueue = run.then(
+		() => undefined,
+		() => undefined,
+	);
+	return run;
+}
+
+function classifyError(message: string): SidekickResult["details"]["failure_reason"] {
+	const lower = message.toLowerCase();
+	if (lower.includes("credit") || lower.includes("quota") || lower.includes("billing")) {
+		return "insufficient_credits";
+	}
+	if (lower.includes("rate limit") || lower.includes("429")) {
+		return "rate_limited";
+	}
+	return "unexpected_error";
+}
+
+export async function runSidekick(
+	cwd: string,
+	registry: ModelRegistry,
+	currentModel: Model<Api> | undefined,
+	task: string,
+	projectTrusted: boolean,
+	overrides: SidekickOptions,
+	ctx: ExtensionContext,
+	consented: boolean,
+	signal: AbortSignal | undefined,
+	onUpdate?: (partial: { content: Array<{ type: "text"; text: string }>; details: unknown }) => void,
+): Promise<SidekickResult> {
+	const config = applyDefaults(loadConfig(cwd, projectTrusted), overrides);
+	const warnings: string[] = [];
+
+	const executor = resolveExecutorModel(registry, currentModel, config.executor, warnings);
+	if (!executor) {
+		const details = {
+			status: "error" as const,
+			error: "no authed text executor model available",
+			failure_reason: "no_executor_model" as const,
+			warnings,
+		};
+		return { content: [{ type: "text", text: JSON.stringify(details, null, 2) }], details };
+	}
+
+	// Fail-closed: mutating executor tools require explicit consent.
+	const hasConsent = consented || config.executorToolsConsent === true;
+	if (isMutatingSelection(config.executorTools) && !hasConsent) {
+		const details = {
+			status: "error" as const,
+			executor_model: undefined,
+			error: "executor mutating tools require consent",
+			failure_reason: "mutation_consent_required" as const,
+			warnings,
+		};
+		return { content: [{ type: "text", text: JSON.stringify(details, null, 2) }], details };
+	}
+
+	const taskText = buildSidekickTaskText(task, overrides.context_text);
+	const toolDefs = resolveToolDefs(config.executorTools, cwd);
+	const mutating = isMutatingSelection(config.executorTools);
+	const executorModel = modelDisplayLocal(executor);
+	const label = `Sidekick: ${executorModel} | tools: ${config.executorTools}${mutating ? " (serialized)" : ""}`;
+
+	onUpdate?.({ content: [{ type: "text", text: label }], details: { phase: "executing" } });
+
+	const runLoop = () =>
+		callModelWithTools(
+			registry,
+			executor,
+			SIDEKICK_SYSTEM_PROMPT,
+			taskText,
+			config.maxExecutorOutputTokens,
+			config.temperature,
+			signal,
+			toolDefs,
+			config.maxToolCalls,
+			ctx,
+		);
+
+	try {
+		const result = mutating ? await runSerialized(runLoop) : await runLoop();
+		const output = getTextContent(result.message);
+		const details = {
+			status: "ok" as const,
+			executor_model: executorModel,
+			output,
+			turns: result.turns,
+			tool_calls: result.toolCalls,
+			capped: result.cappedOut,
+			warnings,
+		};
+		return { content: [{ type: "text", text: output }], details };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		const details = {
+			status: "error" as const,
+			executor_model: executorModel,
+			error: message,
+			failure_reason: classifyError(message),
+			warnings,
+		};
+		return { content: [{ type: "text", text: JSON.stringify(details, null, 2) }], details };
+	}
+}
+
+function modelDisplayLocal(model: Model<Api>): string {
+	return `${model.provider}/${model.id}`;
+}

package/src/executor_policy.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure executor tool-selection policy, extracted so tests can assert the
+ * fail-closed behavior without invoking models or tools.
+ */
+
+import { applyDefaults } from "./config.ts";
+import { isMutatingSelection } from "./tools.ts";
+import type { SidekickOptions } from "./types.ts";
+
+export interface ExecutorPolicy {
+	executor?: string;
+	toolSelectionConsentRequired: boolean;
+}
+
+/**
+ * Decide whether running the executor needs mutating-tool consent.
+ * Returns the resolved executor id and whether mutation consent is required.
+ */
+export function resolveExecutorPolicy(
+	cwd: string,
+	projectTrusted: boolean,
+	overrides: SidekickOptions,
+	consented: boolean,
+): ExecutorPolicy {
+	const config = applyDefaults(loadConfigLocal(cwd, projectTrusted), overrides);
+	const mutating = isMutatingSelection(config.executorTools);
+	const hasConsent = consented || config.executorToolsConsent === true;
+	return {
+		executor: config.executor,
+		toolSelectionConsentRequired: mutating && !hasConsent,
+	};
+}
+
+// Local import avoids a cycle with config's own loader name.
+import { loadConfig } from "./config.ts";
+function loadConfigLocal(cwd: string, projectTrusted: boolean) {
+	return loadConfig(cwd, projectTrusted);
+}