pi-harness-runtime 1.1.30 → 1.1.32

package/harness/langchain/graph.ts

@@ -0,0 +1,291 @@
+/**
+ * Deterministic write-review loop as a LangGraph StateGraph.
+ *
+ *   START → plan (GPT) → write (MiniMax) → review (GPT)
+ *                                      ├─ approved / blocked / max-iter → finish
+ *                                      └─ changes_requested → write (with comments)
+ *
+ * Unlike the supervisor variant (agents.ts, agents.py style) where an LLM
+ * decides routing, here the structured review verdict drives the conditional
+ * edge — the loop is guaranteed to terminate at maxIterations.
+ *
+ * Wiki: wiki/multi-agent-langchain.md
+ */
+
+import {
+	Annotation,
+	END,
+	MemorySaver,
+	START,
+	StateGraph,
+} from "@langchain/langgraph";
+import {
+	lastMessage,
+	type ReviewVerdict,
+	ReviewVerdictSchema,
+} from "./agents.js";
+
+// ─── State ──────────────────────────────────────────────────────────────────
+
+const LoopState = Annotation.Root({
+	/** Original user request */
+	request: Annotation<string>,
+	/** Plan produced by the GPT planner */
+	plan: Annotation<string>,
+	/** Current iteration (0 = first pass) */
+	iteration: Annotation<number>({
+		reducer: (_prev, next) => next,
+		default: () => 0,
+	}),
+	/** Latest code output from the MiniMax coder */
+	code: Annotation<string>,
+	/** Latest structured review from the GPT reviewer */
+	review: Annotation<ReviewVerdict>,
+	/** Human-readable step log (reducer appends) */
+	log: Annotation<string[]>({
+		reducer: (prev, next) => [...(prev ?? []), ...(next ?? [])],
+		default: () => [],
+	}),
+});
+
+export type LoopState = typeof LoopState.State;
+
+// ─── Dependencies (inject real agents or dry-run stubs) ─────────────────────
+
+export interface LoopDeps {
+	plan: (request: string) => Promise<string>;
+	write: (plan: string, review: ReviewVerdict | null) => Promise<string>;
+	review: (plan: string, code: string) => Promise<ReviewVerdict>;
+	maxIterations: number;
+	onStep?: (step: string, state: LoopState) => void;
+}
+
+// ─── Node implementations ───────────────────────────────────────────────────
+
+function planNode(deps: LoopDeps) {
+	return async (state: LoopState): Promise<Partial<LoopState>> => {
+		const plan = await deps.plan(state.request);
+		deps.onStep?.("plan", state);
+		return {
+			plan,
+			iteration: 0,
+			log: [`[plan] GPT produced plan (${plan.length} chars)`],
+		};
+	};
+}
+
+function writeNode(deps: LoopDeps) {
+	return async (state: LoopState): Promise<Partial<LoopState>> => {
+		const code = await deps.write(state.plan, state.review ?? null);
+		const iter = state.iteration + 1;
+		deps.onStep?.("write", { ...state, iteration: iter });
+		const reviewNote = state.review
+			? ` (addressing ${state.review.comments.length} review comment(s))`
+			: "";
+		// Note: previous `review` stays in state on purpose — the coder reads its comments.
+		return {
+			code,
+			iteration: iter,
+			log: [`[write:${iter}] MiniMax wrote code${reviewNote}`],
+		};
+	};
+}
+
+function reviewNode(deps: LoopDeps) {
+	return async (state: LoopState): Promise<Partial<LoopState>> => {
+		const review = await deps.review(state.plan, state.code);
+		deps.onStep?.("review", state);
+		return {
+			review,
+			log: [`[review:${state.iteration}] GPT verdict: ${review.verdict}`],
+		};
+	};
+}
+
+function finishNode() {
+	return async (state: LoopState): Promise<Partial<LoopState>> => {
+		const verdict = state.review?.verdict ?? "blocked";
+		const reason =
+			verdict === "approved"
+				? "reviewer approved"
+				: verdict === "changes_requested"
+					? `max iterations (${state.iteration}) reached with changes still requested`
+					: "reviewer blocked the task";
+		return {
+			log: [`[finish] ${state.iteration} iteration(s) — ${reason}`],
+		};
+	};
+}
+
+// ─── Routing ────────────────────────────────────────────────────────────────
+
+function routeAfterReview(
+	state: LoopState,
+	maxIterations: number,
+): "write" | "finish" {
+	const verdict = state.review?.verdict;
+	if (verdict === "approved" || verdict === "blocked") return "finish";
+	if (state.iteration >= maxIterations) return "finish";
+	return "write";
+}
+
+// ─── Graph builder ──────────────────────────────────────────────────────────
+
+export function buildWriteReviewLoop(
+	deps: LoopDeps,
+	opts: { checkpointer?: boolean | unknown } = {},
+) {
+	// Node names must not collide with state channel names (LangGraph rule),
+	// hence the "*Step" suffixes.
+	const builder = new StateGraph(LoopState)
+		.addNode("planStep", planNode(deps))
+		.addNode("writeStep", writeNode(deps))
+		.addNode("reviewStep", reviewNode(deps))
+		.addNode("finishStep", finishNode())
+		.addEdge(START, "planStep")
+		.addEdge("planStep", "writeStep")
+		.addEdge("writeStep", "reviewStep")
+		.addConditionalEdges(
+			"reviewStep",
+			(state) => routeAfterReview(state, deps.maxIterations),
+			// Router returns logical names; map them to the physical node names
+			{ write: "writeStep", finish: "finishStep" },
+		)
+		.addEdge("finishStep", END);
+
+	// Resolve checkpointer: false=disabled, object=use it, true/undefined=default MemorySaver
+	const cp = opts.checkpointer;
+	const checkpointerToUse =
+		cp === false
+			? undefined
+			: cp != null && cp !== true
+				? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+				  (cp as any)
+				: new MemorySaver();
+	return builder.compile({ checkpointer: checkpointerToUse });
+}
+
+/** Inferred compiled-graph type (do not hand-roll langgraph generics). */
+export type WriteReviewLoop = ReturnType<typeof buildWriteReviewLoop>;
+
+// ─── Real-model dependency wiring ───────────────────────────────────────────
+
+export interface RealLoopOptions {
+	maxIterations?: number;
+	onStep?: (step: string, state: LoopState) => void;
+	importAgents?: () => Promise<{
+		createPlannerAgent: () => {
+			invoke: (input: { messages: unknown[] }) => Promise<{
+				messages: Array<{ content: unknown }>;
+			}>;
+		};
+		createCoderAgent: () => {
+			invoke: (input: { messages: unknown[] }) => Promise<{
+				messages: Array<{ content: unknown }>;
+			}>;
+		};
+		createReviewerAgent: () => {
+			invoke: (input: { messages: unknown[] }) => Promise<{
+				messages: Array<{ content: unknown }>;
+				structuredResponse?: ReviewVerdict;
+			}>;
+		};
+	}>;
+}
+
+/**
+ * Build LoopDeps backed by the real GPT/MiniMax agents from agents.ts.
+ * Kept lazy (dynamic import) so dry-run mode never touches API keys.
+ */
+export async function buildRealLoopDeps(
+	options: RealLoopOptions = {},
+): Promise<LoopDeps> {
+	const mod = await import("./agents.js");
+	const planner = mod.createPlannerAgent();
+	const coder = mod.createCoderAgent();
+	const reviewer = mod.createReviewerAgent();
+
+	return {
+		maxIterations: options.maxIterations ?? 3,
+		onStep: options.onStep,
+		plan: async (request) =>
+			lastMessage(
+				await planner.invoke({
+					messages: [{ role: "user", content: request }],
+				}),
+			),
+		write: async (plan, review) => {
+			const userMsg = review
+				? `## Plan\n${plan}\n\n## Review comments to address\n${review.comments
+						.map((c, i) => `${i + 1}. ${c.comment}`)
+						.join("\n")}`
+				: `## Plan\n${plan}`;
+			return lastMessage(
+				await coder.invoke({ messages: [{ role: "user", content: userMsg }] }),
+			);
+		},
+		review: async (plan, code) => {
+			const result = await reviewer.invoke({
+				messages: [
+					{
+						role: "user",
+						content: `## Plan\n${plan}\n\n## Code to review\n${code}`,
+					},
+				],
+			});
+			if (result.structuredResponse) return result.structuredResponse;
+			// Fallback: try to parse the last message as JSON
+			try {
+				return ReviewVerdictSchema.parse(JSON.parse(lastMessage(result)));
+			} catch {
+				return {
+					verdict: "blocked",
+					summary: "Reviewer returned unparseable output",
+					comments: [],
+				};
+			}
+		},
+	};
+}
+
+// ─── Dry-run dependencies (no API keys needed) ───────────────────────────────
+
+/** Deterministic stubs: iteration 1 requests changes, iteration 2 approves. */
+export function buildDryRunDeps(
+	options: { maxIterations?: number; onStep?: LoopDeps["onStep"] } = {},
+): LoopDeps {
+	let writeCount = 0;
+	return {
+		maxIterations: options.maxIterations ?? 3,
+		onStep: options.onStep,
+		plan: async (request) =>
+			`# Plan (dry-run)\n\nRequest: ${request}\n\n1. Stub step one\n2. Stub step two`,
+		write: async (plan, review) => {
+			writeCount += 1;
+			const fixNote = review
+				? `\n// addressing: ${review.comments.map((c) => c.comment).join("; ")}`
+				: "";
+			return `\`\`\`ts\n// stub code, iteration ${writeCount}\nexport const plan = ${JSON.stringify(plan.slice(0, 60))};${fixNote}\n\`\`\``;
+		},
+		review: async (_plan, _code) => {
+			if (writeCount < 2) {
+				return {
+					verdict: "changes_requested",
+					summary: "Dry-run: requesting one round of changes",
+					comments: [
+						{
+							file: "index.ts",
+							comment: "dry-run: rename the exported constant",
+							severity: "minor",
+						},
+					],
+				};
+			}
+			return {
+				verdict: "approved",
+				summary: "Dry-run: looks good",
+				comments: [],
+			};
+		},
+	};
+}

package/harness/langchain/models.ts

@@ -0,0 +1,95 @@
+/**
+ * Model factories — GPT (planner/reviewer) + MiniMax (coder).
+ *
+ * MiniMax exposes an OpenAI-compatible chat completions API, so we reuse
+ * ChatOpenAI with a baseURL override. All values are env-configurable.
+ *
+ * Wiki: wiki/multi-agent-langchain.md
+ */
+
+import { ChatOpenAI } from "@langchain/openai";
+
+export interface ModelOptions {
+	/** Override model id (e.g. "gpt-4o", "MiniMax-M2.1") */
+	model?: string;
+	/** Override API base URL */
+	baseURL?: string;
+	/** Override API key */
+	apiKey?: string;
+	/** Sampling temperature */
+	temperature?: number;
+}
+
+function gptDefaults(): { model: string; baseURL: string; apiKey: string } {
+	const apiKey = process.env.OPENAI_API_KEY ?? "";
+	if (!apiKey) {
+		throw new Error(
+			"OPENAI_API_KEY is not set. Add it to .env (see .env.example).",
+		);
+	}
+	return {
+		model: process.env.OPENAI_MODEL ?? "gpt-4o",
+		// Optional override (proxies / gateways); defaults to the public endpoint
+		baseURL: process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1",
+		apiKey,
+	};
+}
+
+function minimaxDefaults(): {
+	model: string;
+	baseURL: string;
+	apiKey: string;
+} {
+	const apiKey = process.env.MINIMAX_API_KEY ?? "";
+	if (!apiKey) {
+		throw new Error(
+			"MINIMAX_API_KEY is not set. Add it to .env (see .env.example).",
+		);
+	}
+	return {
+		model: process.env.MINIMAX_MODEL ?? "MiniMax-M2",
+		// International endpoint by default; China mainland: https://api.minimax.chat/v1
+		baseURL: process.env.MINIMAX_BASE_URL ?? "https://api.minimaxi.com/v1",
+		apiKey,
+	};
+}
+
+/** Build the `configuration.baseURL` override for ChatOpenAI (always set). */
+function baseURLConfig(baseURL: string): {
+	configuration: { baseURL: string };
+} {
+	return { configuration: { baseURL } };
+}
+
+/** GPT model — used for planning and code review. */
+export function createPlannerModel(opts: ModelOptions = {}): ChatOpenAI {
+	const d = gptDefaults();
+	return new ChatOpenAI({
+		model: opts.model ?? d.model,
+		apiKey: opts.apiKey ?? d.apiKey,
+		temperature: opts.temperature ?? 0.2,
+		...baseURLConfig(opts.baseURL ?? d.baseURL),
+	});
+}
+
+/** Reviewer shares the GPT configuration (can be overridden). */
+export function createReviewerModel(opts: ModelOptions = {}): ChatOpenAI {
+	const d = gptDefaults();
+	return new ChatOpenAI({
+		model: opts.model ?? d.model,
+		apiKey: opts.apiKey ?? d.apiKey,
+		temperature: opts.temperature ?? 0.1, // reviews want determinism
+		...baseURLConfig(opts.baseURL ?? d.baseURL),
+	});
+}
+
+/** MiniMax model — used for code generation (OpenAI-compatible endpoint). */
+export function createCoderModel(opts: ModelOptions = {}): ChatOpenAI {
+	const d = minimaxDefaults();
+	return new ChatOpenAI({
+		model: opts.model ?? d.model,
+		apiKey: opts.apiKey ?? d.apiKey,
+		temperature: opts.temperature ?? 0.3,
+		...baseURLConfig(opts.baseURL ?? d.baseURL),
+	});
+}

package/harness/langchain/run.ts

@@ -0,0 +1,207 @@
+/**
+ * CLI runner for the LangChain write-review loop.
+ *
+ * Usage:
+ *   bun harness/langchain/run.ts --mode graph --request "implement X" [--max-iterations 3]
+ *   bun harness/langchain/run.ts --mode graph --request "implement X" --dry-run
+ *   bun harness/langchain/run.ts --mode supervisor --request "implement X"
+ *
+ * --dry-run uses deterministic stubs — no API keys needed. Use it to verify
+ * the whole loop machinery (plan → write → review → fix → approve).
+ *
+ * Wiki: wiki/multi-agent-langchain.md
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+	buildDryRunDeps,
+	buildRealLoopDeps,
+	buildWriteReviewLoop,
+	type LoopState,
+} from "./graph.js";
+
+interface CliArgs {
+	mode: "graph" | "supervisor";
+	request: string;
+	maxIterations: number;
+	dryRun: boolean;
+	daemon: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+	const args: CliArgs = {
+		mode: "graph",
+		request: "",
+		maxIterations: 3,
+		dryRun: false,
+		daemon: false,
+	};
+	// Normalize space-separated flags (--mode graph) into --mode=graph form
+	const normalized: string[] = [];
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i] as string;
+		const spaced =
+			(arg === "--mode" || arg === "--request" || arg === "--max-iterations") &&
+			argv[i + 1] !== undefined &&
+			!(argv[i + 1] as string).startsWith("--");
+		if (spaced) {
+			normalized.push(`${arg}=${argv[i + 1]}`);
+			i++;
+		} else {
+			normalized.push(arg);
+		}
+	}
+	for (const arg of normalized) {
+		if (arg.startsWith("--mode=")) {
+			const mode = arg.slice("--mode=".length);
+			if (mode !== "graph" && mode !== "supervisor") {
+				throw new Error(`Unknown mode: ${mode} (expected graph|supervisor)`);
+			}
+			args.mode = mode;
+		} else if (arg.startsWith("--request=")) {
+			args.request = arg.slice("--request=".length);
+		} else if (arg.startsWith("--max-iterations=")) {
+			const n = Number.parseInt(arg.slice("--max-iterations=".length), 10);
+			if (Number.isNaN(n) || n < 1 || n > 20) {
+				throw new Error("--max-iterations must be 1-20");
+			}
+			args.maxIterations = n;
+		} else if (arg === "--dry-run") {
+			args.dryRun = true;
+		} else if (arg === "--daemon") {
+			args.daemon = true;
+		} else if (arg === "--help" || arg === "-h") {
+			console.log(
+				[
+					"Usage: bun harness/langchain/run.ts [options]",
+					"",
+					"Options:",
+					"  --mode=graph|supervisor   Loop style (default: graph)",
+					'  --request="..."           The feature request',
+					"  --max-iterations=N        Max write-review rounds (default: 3)",
+					"  --dry-run                 Deterministic stubs, no API calls",
+					"  --daemon                  Start as a long-running daemon (auto-trigger loop)",
+				].join("\n"),
+			);
+			process.exit(0);
+		} else {
+			// Bare positional argument = request
+			if (!args.request) args.request = arg;
+		}
+	}
+	if (!args.request && !args.daemon) {
+		throw new Error(
+			'A request is required: --request="..." or a bare string (or use --daemon to start the watcher)',
+		);
+	}
+	return args;
+}
+
+function printStep(step: string, state: LoopState): void {
+	const labels: Record<string, string> = {
+		plan: "🧭 GPT planner",
+		write: "✍️  MiniMax coder",
+		review: "🔍 GPT reviewer",
+		finish: "🏁 finish",
+	};
+	const iter = state.iteration > 0 ? ` (iteration ${state.iteration})` : "";
+	console.log(`  ${labels[step] ?? step}${iter}`);
+}
+
+async function runGraphLoop(args: CliArgs): Promise<void> {
+	console.log(
+		`\n━━━ Write-Review Loop (graph mode)${args.dryRun ? " — DRY RUN" : ""} ━━━`,
+	);
+	console.log(`Request: ${args.request}\n`);
+
+	const deps = args.dryRun
+		? buildDryRunDeps({ maxIterations: args.maxIterations, onStep: printStep })
+		: await buildRealLoopDeps({
+				maxIterations: args.maxIterations,
+				onStep: printStep,
+			});
+
+	const loop = buildWriteReviewLoop(deps);
+	const threadId = `loop-${randomUUID().slice(0, 8)}`;
+
+	const finalState = await loop.invoke(
+		{ request: args.request },
+		{ configurable: { thread_id: threadId } },
+	);
+
+	console.log("\n─── Step log ───");
+	for (const line of finalState.log) console.log(`  ${line}`);
+
+	console.log("\n─── Verdict ───");
+	const review = finalState.review;
+	if (review) {
+		console.log(`  ${review.verdict.toUpperCase()} — ${review.summary}`);
+		if (review.comments.length > 0) {
+			console.log("  Open comments:");
+			for (const c of review.comments) {
+				const file = c.file ? ` (${c.file})` : "";
+				console.log(`   - [${c.severity ?? "n/a"}] ${c.comment}${file}`);
+			}
+		}
+	} else {
+		console.log("  (no review produced)");
+	}
+}
+
+async function runSupervisor(args: CliArgs): Promise<void> {
+	if (args.dryRun) {
+		throw new Error(
+			"--dry-run is only supported for --mode=graph (supervisor needs real models)",
+		);
+	}
+	console.log("\n━━━ Write-Review Loop (supervisor mode) ━━━");
+	console.log(`Request: ${args.request}\n`);
+
+	const { createSupervisor, lastMessage } = await import("./agents.js");
+	const supervisor = createSupervisor();
+	const result = await supervisor.invoke({
+		messages: [{ role: "user", content: args.request }],
+	});
+	console.log("\n─── Supervisor output ───");
+	console.log(lastMessage(result));
+}
+
+async function runDaemon(args: CliArgs): Promise<void> {
+	const { LoopDaemon } = await import("./daemon.js");
+	const daemon = new LoopDaemon({
+		maxIterations: args.maxIterations,
+		dryRun: args.dryRun,
+		sources: ["inbox", "bus"],
+	});
+
+	// Graceful shutdown on SIGTERM / SIGINT
+	const shutdown = () => {
+		daemon.stop();
+		process.exit(0);
+	};
+	process.on("SIGTERM", shutdown);
+	process.on("SIGINT", shutdown);
+
+	daemon.start();
+
+	// Keep the process alive
+	await new Promise(() => {});
+}
+
+async function main(): Promise<void> {
+	const args = parseArgs(process.argv.slice(2));
+	if (args.daemon) {
+		await runDaemon(args);
+	} else if (args.mode === "supervisor") {
+		await runSupervisor(args);
+	} else {
+		await runGraphLoop(args);
+	}
+}
+
+main().catch((err: unknown) => {
+	console.error(
+		`[run] Error: ${err instanceof Error ? err.message : String(err)}`,
+	);
+	process.exit(1);
+});