pi-harness-runtime 1.1.30 → 1.1.32

package/harness/langchain/agents.ts

@@ -0,0 +1,198 @@
+/**
+ * Multi-Agent definitions — GPT (planner/reviewer/supervisor) + MiniMax (coder).
+ *
+ * This is a TypeScript port of the "supervisor + agents-as-tools" pattern from
+ * Mohamad-Hachem/MultiAgent_Wedding_Planner_With_Langchain (agents.py):
+ *
+ *   Python (agents.py)              →  TypeScript (this file)
+ *   ------------------------------------------------------------------
+ *   subagent1 = create_agent(...)   →  coderAgent = createAgent({ model: minimax ... })
+ *   @tool delegate_to_subagent1     →  delegateToCoder = tool(... { name: "delegate_to_coder" })
+ *   main_agent(tools=[delegates])   →  supervisor = createAgent({ tools: [delegateToCoder, ...] })
+ *
+ * Verdict values intentionally match the existing harness LoopVerdict type
+ * ("approved" | "changes_requested" | "blocked") so this module can feed the
+ * existing blackboard / HerdrEventBus infrastructure.
+ *
+ * Wiki: wiki/multi-agent-langchain.md
+ */
+
+import { createAgent, tool } from "langchain";
+import { z } from "zod";
+import {
+	createCoderModel,
+	createPlannerModel,
+	createReviewerModel,
+	type ModelOptions,
+} from "./models.js";
+
+// ─── Structured review output ───────────────────────────────────────────────
+
+export const ReviewVerdictSchema = z.object({
+	verdict: z
+		.enum(["approved", "changes_requested", "blocked"])
+		.describe("Overall review verdict"),
+	summary: z.string().describe("One-paragraph summary of the review"),
+	comments: z
+		.array(
+			z.object({
+				file: z.string().optional().describe("Affected file, if known"),
+				comment: z.string().describe("Actionable change request"),
+				severity: z.enum(["critical", "major", "minor"]).optional(),
+			}),
+		)
+		.describe("Comments to send back to the coder (empty when approved)"),
+});
+
+export type ReviewVerdict = z.infer<typeof ReviewVerdictSchema>;
+
+// ─── Prompts ────────────────────────────────────────────────────────────────
+
+const PLANNER_PROMPT = `You are the Planning Agent (GPT). Given a feature request, produce a
+concise implementation plan: goals, non-goals, ordered steps, files to touch,
+risks, and a definition-of-done the reviewer can check against.
+Output markdown only.`;
+
+const CODER_PROMPT = `You are the Coding Agent (MiniMax). You receive a plan (and possibly
+review comments from a previous iteration) and produce complete, runnable code.
+Always output fenced code blocks with file-path headers. Address every review
+comment explicitly.`;
+
+const REVIEWER_PROMPT = `You are the Code Review Agent (GPT). You review the coder's output
+against the plan and the review checklist. Be strict but fair: request changes
+only for real problems. Respond via the structured schema.`;
+
+const SUPERVISOR_PROMPT = `You are the Supervisor (GPT). Coordinate the workflow:
+1. Call delegate_to_coder with the instruction (include review comments when fixing).
+2. Call delegate_to_reviewer with the plan + code to review.
+3. If the reviewer requests changes, call delegate_to_coder again with the comments.
+4. Repeat until approved or you judge further iterations unproductive (then stop and summarize).
+Keep the loop tight: no more than 4 coder-review rounds unless the task clearly needs more.`;
+
+// ─── Agents ─────────────────────────────────────────────────────────────────
+
+export function createPlannerAgent(opts: ModelOptions = {}) {
+	return createAgent({
+		model: createPlannerModel(opts),
+		tools: [],
+		systemPrompt: PLANNER_PROMPT,
+	});
+}
+
+export function createCoderAgent(opts: ModelOptions = {}) {
+	return createAgent({
+		model: createCoderModel(opts),
+		tools: [], // roadmap: file read/write tools for real repo edits
+		systemPrompt: CODER_PROMPT,
+	});
+}
+
+export function createReviewerAgent(opts: ModelOptions = {}) {
+	return createAgent({
+		model: createReviewerModel(opts),
+		tools: [],
+		systemPrompt: REVIEWER_PROMPT,
+		responseFormat: ReviewVerdictSchema,
+	});
+}
+
+export type PlannerAgent = ReturnType<typeof createPlannerAgent>;
+export type CoderAgent = ReturnType<typeof createCoderAgent>;
+export type ReviewerAgent = ReturnType<typeof createReviewerAgent>;
+export type SupervisorAgent = ReturnType<typeof createSupervisor>;
+
+/** Extract the last assistant message text from an agent result. */
+export function lastMessage(agentResult: {
+	messages: Array<{ content: unknown }>;
+}): string {
+	const last = agentResult.messages[agentResult.messages.length - 1];
+	if (typeof last?.content === "string") return last.content;
+	if (Array.isArray(last?.content)) {
+		return last.content.map((c: { text?: string }) => c?.text ?? "").join("\n");
+	}
+	return "";
+}
+
+// ─── Delegation tools (agents-as-tools, port of agents.py) ──────────────────
+
+export function buildDelegationTools(
+	opts: { coder?: CoderAgent; reviewer?: ReviewerAgent } = {},
+) {
+	const coder = opts.coder ?? createCoderAgent();
+	const reviewer = opts.reviewer ?? createReviewerAgent();
+
+	const delegateToCoder = tool(
+		async ({ instruction, reviewComments }) => {
+			const userMsg = reviewComments
+				? `${instruction}\n\nPrevious review requested changes:\n${reviewComments}`
+				: instruction;
+			const result = await coder.invoke({
+				messages: [{ role: "user", content: userMsg }],
+			});
+			return lastMessage(result);
+		},
+		{
+			name: "delegate_to_coder",
+			description:
+				"Delegate a coding instruction to the MiniMax coder agent. " +
+				"Pass previous review comments when fixing issues.",
+			schema: z.object({
+				instruction: z.string().describe("What the coder should implement or fix"),
+				reviewComments: z
+					.string()
+					.optional()
+					.describe("Review comments from the previous iteration"),
+			}),
+		},
+	);
+
+	const delegateToReviewer = tool(
+		async ({ plan, code }) => {
+			const result = await reviewer.invoke({
+				messages: [
+					{
+						role: "user",
+						content: `## Plan\n${plan}\n\n## Code to review\n${code}`,
+					},
+				],
+			});
+			const structured = (result as { structuredResponse?: ReviewVerdict })
+				.structuredResponse;
+			return structured
+				? JSON.stringify(structured, null, 2)
+				: lastMessage(result);
+		},
+		{
+			name: "delegate_to_reviewer",
+			description:
+				"Delegate a code review to the GPT reviewer agent. Returns a JSON verdict: " +
+				'{verdict: "approved"|"changes_requested"|"blocked", summary, comments[]}.',
+			schema: z.object({
+				plan: z.string().describe("The implementation plan"),
+				code: z.string().describe("The code the coder produced"),
+			}),
+		},
+	);
+
+	return { delegateToCoder, delegateToReviewer };
+}
+
+// ─── Supervisor (dynamic routing variant) ───────────────────────────────────
+
+export function createSupervisor(
+	opts: {
+		plannerModel?: ModelOptions;
+		coder?: CoderAgent;
+		reviewer?: ReviewerAgent;
+	} = {},
+) {
+	const { delegateToCoder, delegateToReviewer } = buildDelegationTools({
+		coder: opts.coder,
+		reviewer: opts.reviewer,
+	});
+	return createAgent({
+		model: createPlannerModel(opts.plannerModel ?? {}),
+		tools: [delegateToCoder, delegateToReviewer],
+		systemPrompt: SUPERVISOR_PROMPT,
+	});
+}

package/harness/langchain/checkpointer.test.ts

@@ -0,0 +1,269 @@
+/**
+ * FileCheckpointSaver tests — T9–T11 (wiki/auto-trigger-multi-agent.md §M5)
+ *
+ * Run:
+ *   bun test harness/langchain/checkpointer.test.ts
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import {
+	FileCheckpointSaver,
+	createLoopCheckpointer,
+} from "./checkpointer.js";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const ROOT = `/tmp/checkpointer-test-${randomUUID().slice(0, 8)}`;
+
+function freshSaver(): FileCheckpointSaver {
+	const saver = new FileCheckpointSaver({ root: ROOT });
+	saver.clearAll();
+	return saver;
+}
+
+const THREAD = "thread-abc123";
+const CONFIG = { configurable: { thread_id: THREAD } };
+const CONFIG_WITH_CPID = {
+	configurable: { thread_id: THREAD, checkpoint_id: "cp-001" },
+};
+
+// ─── T9: Basic put/get ──────────────────────────────────────────────────────
+
+describe("T9 — put and get basic checkpoint", () => {
+	it("stores and retrieves a checkpoint", async () => {
+		const saver = freshSaver();
+
+		const checkpoint = {
+			v: 4,
+			id: "cp-001",
+			ts: "2026-08-31T10:00:00.000Z",
+			channel_values: { plan: "do the thing", code: "" },
+			channel_versions: { plan: 1, code: 0 },
+			versions_seen: {},
+		};
+		const metadata = {
+			source: "input" as const,
+			step: -1,
+			parents: {},
+		};
+
+		const updatedConfig = await saver.put(CONFIG, checkpoint, metadata, {});
+		assert.equal(
+			updatedConfig.configurable?.checkpoint_id,
+			"cp-001",
+		);
+
+		// Retrieve it
+		const tuple = await saver.getTuple(CONFIG_WITH_CPID);
+		assert.ok(tuple, "should retrieve the checkpoint");
+		assert.equal(tuple?.checkpoint.id, "cp-001");
+		assert.equal(
+			(tuple?.checkpoint.channel_values as Record<string, unknown>)?.plan,
+			"do the thing",
+		);
+	});
+
+	it("get() returns the checkpoint", async () => {
+		const saver = freshSaver();
+		const cp = {
+			v: 4,
+			id: "cp-get",
+			ts: "2026-08-31T10:01:00.000Z",
+			channel_values: { plan: "test plan" },
+			channel_versions: {},
+			versions_seen: {},
+		};
+		await saver.put(CONFIG, cp, { source: "input", step: -1, parents: {} }, {});
+
+		const retrieved = await saver.get({
+			configurable: { thread_id: THREAD, checkpoint_id: "cp-get" },
+		});
+		assert.ok(retrieved, "should return the checkpoint");
+		assert.equal(retrieved?.id, "cp-get");
+	});
+});
+
+// ─── T10: Parent chain ──────────────────────────────────────────────────────
+
+describe("T10 — parent chain", () => {
+	it("stores and retrieves a parent chain (resume)", async () => {
+		const saver = freshSaver();
+
+		const root = {
+			v: 4,
+			id: "root",
+			ts: "2026-08-31T10:00:00.000Z",
+			channel_values: {},
+			channel_versions: {},
+			versions_seen: {},
+		};
+		const child = {
+			v: 4,
+			id: "child",
+			ts: "2026-08-31T10:01:00.000Z",
+			channel_values: { plan: "the plan" },
+			channel_versions: { plan: 1 },
+			versions_seen: {},
+		};
+
+		await saver.put(
+			CONFIG,
+			root,
+			{ source: "input", step: -1, parents: {} },
+			{},
+		);
+		await saver.put(
+			CONFIG,
+			child,
+			{ source: "loop", step: 0, parents: { "": "root" } },
+			{},
+		);
+
+		// Retrieve child and verify parent
+		const tuple = await saver.getTuple({
+			configurable: { thread_id: THREAD, checkpoint_id: "child" },
+		});
+		assert.ok(tuple);
+		assert.ok(tuple?.parentConfig);
+		assert.equal(
+			tuple?.parentConfig?.configurable?.checkpoint_id,
+			"root",
+		);
+
+		// getTuple without checkpoint_id returns the latest
+		const latest = await saver.getTuple(CONFIG);
+		assert.ok(latest);
+		assert.equal(latest?.checkpoint.id, "child");
+	});
+});
+
+// ─── T11: list + deleteThread ───────────────────────────────────────────────
+
+describe("T11 — list and deleteThread", () => {
+	it("lists checkpoints in reverse chronological order", async () => {
+		const saver = freshSaver();
+
+		for (let i = 0; i < 5; i++) {
+			const cp = {
+				v: 4,
+				id: `cp-${i}`,
+				ts: new Date(1000 + i * 1000).toISOString(),
+				channel_values: { step: i },
+				channel_versions: {},
+				versions_seen: {},
+			};
+			await saver.put(
+				CONFIG,
+				cp,
+				{ source: "loop", step: i, parents: {} },
+				{},
+			);
+		}
+
+		const all: string[] = [];
+		for await (const tuple of saver.list(CONFIG)) {
+			all.push(tuple.checkpoint.id);
+		}
+		assert.equal(all.length, 5);
+		// Newest first
+		assert.equal(all[0], "cp-4");
+		assert.equal(all[4], "cp-0");
+	});
+
+	it("limits list results", async () => {
+		const saver = freshSaver();
+		for (let i = 0; i < 3; i++) {
+			const cp = {
+				v: 4,
+				id: `limit-${i}`,
+				ts: new Date(2000 + i * 1000).toISOString(),
+				channel_values: {},
+				channel_versions: {},
+				versions_seen: {},
+			};
+			await saver.put(
+				CONFIG,
+				cp,
+				{ source: "loop", step: i, parents: {} },
+				{},
+			);
+		}
+
+		const limited: string[] = [];
+		for await (const tuple of saver.list(CONFIG, { limit: 2 })) {
+			limited.push(tuple.checkpoint.id);
+		}
+		assert.equal(limited.length, 2);
+	});
+
+	it("deleteThread removes all checkpoints for a thread", async () => {
+		const saver = freshSaver();
+
+		const cp = {
+			v: 4,
+			id: "delete-me",
+			ts: "2026-08-31T12:00:00.000Z",
+			channel_values: {},
+			channel_versions: {},
+			versions_seen: {},
+		};
+		await saver.put(
+			CONFIG,
+			cp,
+			{ source: "input", step: -1, parents: {} },
+			{},
+		);
+
+		assert.ok(await saver.getTuple(CONFIG), "checkpoint should exist");
+
+		await saver.deleteThread(THREAD);
+
+		assert.ok(
+			!(await saver.getTuple(CONFIG)),
+			"checkpoint should be gone after deleteThread",
+		);
+	});
+
+	it("toJSON returns a string (not the internal object)", async () => {
+		const saver = freshSaver();
+		const json = saver.toJSON();
+		assert.equal(typeof json, "string");
+		assert.ok(json.length > 0);
+	});
+
+	it("listThreads returns thread ids", async () => {
+		const saver = freshSaver();
+		const tid = `thread-${randomUUID().slice(0, 6)}`;
+		const cp = {
+			v: 4,
+			id: "cp-t",
+			ts: "2026-08-31T12:00:00.000Z",
+			channel_values: {},
+			channel_versions: {},
+			versions_seen: {},
+		};
+		await saver.put(
+			{ configurable: { thread_id: tid } },
+			cp,
+			{ source: "input", step: -1, parents: {} },
+			{},
+		);
+
+		const threads = saver.listThreads();
+		assert.ok(threads.includes(tid), `Expected ${tid} in ${JSON.stringify(threads)}`);
+	});
+});
+
+// ─── T12: createLoopCheckpointer factory ─────────────────────────────────────
+
+describe("T12 — createLoopCheckpointer factory", () => {
+	it("creates a saver with the correct root path", () => {
+		const saver = createLoopCheckpointer("/my/workspace");
+		assert.ok(saver instanceof FileCheckpointSaver);
+	});
+});