pi-harness-runtime 1.1.50 → 1.1.77

package/harness/langchain/model-router.ts

@@ -0,0 +1,188 @@
+/**
+ * Smart model router — reads the request prompt and decides which model to use
+ * for each agent role at runtime. No hardcoded model IDs; all choices are driven
+ * by env vars + optional per-request directives in the prompt.
+ *
+ * Per-request directives (optional — fallback to env defaults if absent):
+ *
+ *   Planner directive:
+ *     [planner: gpt-5.6]   or  [planner: GLM-5.2]   or  [planner: MiniMax-M2]
+ *
+ *   Reviewer directive (master reviewer — GLM is the design default):
+ *     [reviewer: GLM-5.2]  or  [reviewer: GPT-5.6]
+ *
+ *   Coder directive:
+ *     [coder: MiniMax-M2]   or  [coder: gpt-5.6]
+ *
+ *   Examples in a prompt:
+ *     "Implement X   [reviewer: GPT-5.6]  [planner: GLM-5.2]"
+ *     "Use GLM as master reviewer for this task"
+ *     "GPT as reviewer: please review this code"
+ *
+ *   The parser is forgiving — these all work:
+ *     [reviewer: GLM]        → uses GLM_MODEL from env
+ *     [reviewer: gpt]         → uses PLANNER_MODEL from env (same family)
+ *     [reviewer: MiniMax]     → uses MINIMAX_MODEL from env
+ *
+ * Wiki: wiki/multi-agent-langchain.md
+ */
+
+/** Matches [role: modelFamily] directives, case-insensitive. */
+const DIRECTIVE_RE = /\[(\w+)\s*:\s*(\w[\w-]*)\]/gi;
+
+/** Map from directive family name → env prefix. */
+const FAMILY_MAP: Record<string, string> = {
+	gpt: "PLANNER",
+	glm: "GLM",
+	minimax: "MINIMAX",
+};
+
+/** Env vars that exist for each prefix. */
+const ENVVARS = {
+	PLANNER: ["PLANNER_MODEL", "PLANNER_BASE_URL", "PLANNER_API_KEY"],
+	GLM: ["GLM_MODEL", "GLM_BASE_URL", "GLM_API_KEY"],
+	MINIMAX: ["MINIMAX_MODEL", "MINIMAX_BASE_URL", "MINIMAX_API_KEY"],
+};
+
+/** Model options derived from a resolved env prefix. */
+export interface ResolvedModel {
+	model: string;
+	baseURL: string;
+	apiKey: string;
+}
+
+/** Result of routing a request to models. */
+export interface RouteResult {
+	planner: ResolvedModel;
+	reviewer: ResolvedModel; // master reviewer
+	coder: ResolvedModel;
+	/** Text of the request with directive comments stripped (safe for agent prompts). */
+	cleanRequest: string;
+}
+
+/**
+ * Resolve a model family to actual env-backed model options.
+ * family: "GLM" | "PLANNER" | "MINIMAX" (case-insensitive input)
+ */
+export function resolveModel(family: string): ResolvedModel {
+	const key = FAMILY_MAP[family.toLowerCase()] ?? family.toUpperCase();
+	const env = process.env;
+
+	const modelKey = `${key}_MODEL`;
+	const baseURLKey = `${key}_BASE_URL`;
+	const apiKeyKey = `${key}_API_KEY`;
+
+	const model = env[modelKey];
+	const baseURL = env[baseURLKey];
+	const apiKey = env[apiKeyKey];
+
+	if (!apiKey) {
+		throw new Error(
+			`${apiKeyKey} is not set. Set it in .env (see .env.example).`,
+		);
+	}
+	if (!model) {
+		throw new Error(
+			`${modelKey} is not set. Set it in .env (e.g. ${modelKey}="GLM-5.2").`,
+		);
+	}
+	if (!baseURL) {
+		throw new Error(
+			`${baseURLKey} is not set. Set it in .env (e.g. ${baseURLKey}="https://api.z.ai/api/v1").`,
+		);
+	}
+
+	return { model, baseURL, apiKey };
+}
+
+/**
+ * Route a request prompt to the correct model configuration.
+ *
+ * Algorithm:
+ * 1. Extract [role: family] directives from the prompt
+ * 2. Resolve each family to actual env-backed model options
+ * 3. Apply defaults (planner→PLANNER, reviewer→GLM, coder→MINIMAX)
+ * 4. Strip directive comments from the request before passing to agents
+ */
+export function routeRequest(request: string): RouteResult {
+	const directives = new Map<string, string>();
+	let clean = request;
+
+	// Extract and strip directives
+	let match: RegExpExecArray | null;
+	const re = new RegExp(DIRECTIVE_RE.source, "gi");
+	while ((match = re.exec(request)) !== null) {
+		const [, role, family] = match;
+		directives.set(role.toLowerCase(), family.toLowerCase());
+	}
+	// Remove directive lines/comments from the prompt
+	clean = request.replace(DIRECTIVE_RE, "").trim();
+
+	// Resolve each role
+	const plannerFamily = directives.get("planner") ?? "gpt";
+	const reviewerFamily = directives.get("reviewer") ?? "glm";
+	const coderFamily = directives.get("coder") ?? "minimax";
+
+	return {
+		planner: resolveModel(plannerFamily),
+		reviewer: resolveModel(reviewerFamily),
+		coder: resolveModel(coderFamily),
+		cleanRequest: clean,
+	};
+}
+
+/** Also match natural-language hints in the request. */
+const NATURAL_HINTS: Array<[RegExp, string, string]> = [
+	// Reviewer hints
+	[/\bGLM\s+as\s+(master\s+)?reviewer\b/gi, "reviewer", "glm"],
+	[/\bGPT\s+as\s+(master\s+)?reviewer\b/gi, "reviewer", "gpt"],
+	[/\[reviewer:\s*GLM\]/gi, "reviewer", "glm"],
+	[/\[reviewer:\s*GPT\]/gi, "reviewer", "gpt"],
+	// Planner hints
+	[/\bGPT\s+as\s+planner\b/gi, "planner", "gpt"],
+	[/\bGLM\s+as\s+planner\b/gi, "planner", "glm"],
+	[/\[planner:\s*GLM\]/gi, "planner", "glm"],
+	[/\[planner:\s*GPT\]/gi, "planner", "gpt"],
+	// Coder hints
+	[/\bMiniMax\s+as\s+coder\b/gi, "coder", "minimax"],
+	[/\bGPT\s+as\s+coder\b/gi, "coder", "gpt"],
+	[/\[coder:\s*MiniMax\]/gi, "coder", "minimax"],
+	[/\[coder:\s*GPT\]/gi, "coder", "gpt"],
+];
+
+/**
+ * Route a request, also scanning natural-language hints.
+ * Directives ([role: family]) take precedence over natural hints.
+ */
+export function routeRequestSmart(request: string): RouteResult {
+	const directives = new Map<string, string>();
+	const hints = new Map<string, string>();
+	let clean = request;
+
+	// 1. Extract [role: family] directives
+	let match: RegExpExecArray | null;
+	const re = new RegExp(DIRECTIVE_RE.source, "gi");
+	while ((match = re.exec(request)) !== null) {
+		const [, role, family] = match;
+		directives.set(role.toLowerCase(), family.toLowerCase());
+	}
+	clean = request.replace(DIRECTIVE_RE, "").trim();
+
+	// 2. Scan for natural-language hints
+	for (const [pattern, role, family] of NATURAL_HINTS) {
+		if (!hints.has(role) && pattern.test(request)) {
+			hints.set(role, family);
+		}
+	}
+
+	// 3. Merge: directives override hints, hints fill gaps
+	const getRole = (role: string, def: string) =>
+		directives.get(role) ?? hints.get(role) ?? def;
+
+	return {
+		planner: resolveModel(getRole("planner", "gpt")),
+		reviewer: resolveModel(getRole("reviewer", "glm")),
+		coder: resolveModel(getRole("coder", "minimax")),
+		cleanRequest: clean,
+	};
+}

package/harness/langchain/models.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Model factories — all models fully env-driven, no hardcoded defaults.
+ *
+ * Agent roles (configurable via env):
+ *   planner  → GPT  (PLANNER_API_KEY, PLANNER_MODEL, PLANNER_BASE_URL)
+ *   reviewer → GLM  (GLM_API_KEY,     GLM_MODEL,     GLM_BASE_URL)
+ *   coder    → MiniMax (MINIMAX_API_KEY, MINIMAX_MODEL, MINIMAX_BASE_URL)
+ *
+ * Wiki: wiki/multi-agent-langchain.md
+ */
+import { ChatOpenAI } from "@langchain/openai";
+export interface ModelOptions {
+    /** Override model id (e.g. "gpt-5.6", "GLM-5.2", "MiniMax-M2") */
+    model?: string;
+    /** Override API base URL */
+    baseURL?: string;
+    /** Override API key */
+    apiKey?: string;
+    /** Sampling temperature */
+    temperature?: number;
+}
+/**
+ * Pre-resolved model config from model-router.ts.
+ * Pass this to skip env-lookup and use the routed model directly.
+ */
+export interface ResolvedModelOptions {
+    model: string;
+    baseURL: string;
+    apiKey: string;
+    /** Sampling temperature */
+    temperature?: number;
+}
+/**
+ * Planner model — GPT family.
+ *
+ * Can be called with:
+ *   - ModelOptions (override fields, rest from env)
+ *   - ResolvedModelOptions (fully resolved from model-router, no env lookup)
+ *
+ * Env vars (when using ModelOptions):
+ *   PLANNER_API_KEY   (required)
+ *   PLANNER_MODEL     (required)
+ *   PLANNER_BASE_URL  (required)
+ */
+export declare function createPlannerModel(opts?: ModelOptions | ResolvedModelOptions): ChatOpenAI;
+/**
+ * Reviewer model — GLM family (master reviewer per design).
+ *
+ * Can be called with:
+ *   - ModelOptions (override fields, rest from env)
+ *   - ResolvedModelOptions (fully resolved from model-router, no env lookup)
+ *
+ * Env vars (when using ModelOptions):
+ *   GLM_API_KEY   (required)
+ *   GLM_MODEL     (required)
+ *   GLM_BASE_URL  (required)
+ */
+export declare function createReviewerModel(opts?: ModelOptions | ResolvedModelOptions): ChatOpenAI;
+/**
+ * Coder model — MiniMax family.
+ *
+ * Can be called with:
+ *   - ModelOptions (override fields, rest from env)
+ *   - ResolvedModelOptions (fully resolved from model-router, no env lookup)
+ *
+ * Env vars (when using ModelOptions):
+ *   MINIMAX_API_KEY   (required)
+ *   MINIMAX_MODEL     (required)
+ *   MINIMAX_BASE_URL  (required)
+ */
+export declare function createCoderModel(opts?: ModelOptions | ResolvedModelOptions): ChatOpenAI;
+//# sourceMappingURL=models.d.ts.map

package/harness/langchain/models.ts

@@ -1,8 +1,10 @@
 /**
- * Model factories — GPT (planner/reviewer) + MiniMax (coder).
+ * Model factories — all models fully env-driven, no hardcoded defaults.
  *
- * MiniMax exposes an OpenAI-compatible chat completions API, so we reuse
- * ChatOpenAI with a baseURL override. All values are env-configurable.
+ * Agent roles (configurable via env):
+ *   planner  → GPT  (PLANNER_API_KEY, PLANNER_MODEL, PLANNER_BASE_URL)
+ *   reviewer → GLM  (GLM_API_KEY,     GLM_MODEL,     GLM_BASE_URL)
+ *   coder    → MiniMax (MINIMAX_API_KEY, MINIMAX_MODEL, MINIMAX_BASE_URL)
  *
  * Wiki: wiki/multi-agent-langchain.md
  */
@@ -10,7 +12,7 @@
 import { ChatOpenAI } from "@langchain/openai";
 
 export interface ModelOptions {
-	/** Override model id (e.g. "gpt-4o", "MiniMax-M2.1") */
+	/** Override model id (e.g. "gpt-5.6", "GLM-5.2", "MiniMax-M2") */
 	model?: string;
 	/** Override API base URL */
 	baseURL?: string;
@@ -20,76 +22,136 @@ export interface ModelOptions {
 	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,
-	};
+/**
+ * Pre-resolved model config from model-router.ts.
+ * Pass this to skip env-lookup and use the routed model directly.
+ */
+export interface ResolvedModelOptions {
+	model: string;
+	baseURL: string;
+	apiKey: string;
+	/** Sampling temperature */
+	temperature?: number;
+}
+
+// ─── Shared helpers ──────────────────────────────────────────────────────────
+
+/** Build the `configuration.baseURL` override for ChatOpenAI. */
+function baseURLConfig(baseURL: string): {
+	configuration: { baseURL: string };
+} {
+	return { configuration: { baseURL } };
 }
 
-function minimaxDefaults(): {
+/** Env-var tuple for a single model family. */
+interface ModelEnv {
 	model: string;
 	baseURL: string;
 	apiKey: string;
-} {
-	const apiKey = process.env.MINIMAX_API_KEY ?? "";
+}
+
+/** Read env vars for a model family. Throws if the API key is absent. */
+function readEnv(prefix: string, env: typeof process.env): ModelEnv {
+	const apiKey = env[`${prefix}_API_KEY`] ?? "";
 	if (!apiKey) {
 		throw new Error(
-			"MINIMAX_API_KEY is not set. Add it to .env (see .env.example).",
+			`${prefix}_API_KEY is not set. Add it to .env (see .env.example).\n` +
+				`  Example: ${prefix}_MODEL="GLM-5.2" ${prefix}_BASE_URL="https://api.z.ai/api/v1"`,
 		);
 	}
 	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,
+		model:
+			env[`${prefix}_MODEL`] ??
+			(() => {
+				throw new Error(
+					`${prefix}_MODEL is not set. Set it in .env (e.g. ${prefix}_MODEL="GLM-5.2").`,
+				);
+			})(),
+		baseURL:
+			env[`${prefix}_BASE_URL`] ??
+			(() => {
+				throw new Error(
+					`${prefix}_BASE_URL is not set. Set it in .env (e.g. ${prefix}_BASE_URL="https://api.openai.com/v1").`,
+				);
+			})(),
 	};
 }
 
-/** Build the `configuration.baseURL` override for ChatOpenAI (always set). */
-function baseURLConfig(baseURL: string): {
-	configuration: { baseURL: string };
-} {
-	return { configuration: { baseURL } };
-}
+// ─── Model factories ─────────────────────────────────────────────────────────
 
-/** GPT model — used for planning and code review. */
-export function createPlannerModel(opts: ModelOptions = {}): ChatOpenAI {
-	const d = gptDefaults();
+/**
+ * Planner model — GPT family.
+ *
+ * Can be called with:
+ *   - ModelOptions (override fields, rest from env)
+ *   - ResolvedModelOptions (fully resolved from model-router, no env lookup)
+ *
+ * Env vars (when using ModelOptions):
+ *   PLANNER_API_KEY   (required)
+ *   PLANNER_MODEL     (required)
+ *   PLANNER_BASE_URL  (required)
+ */
+export function createPlannerModel(
+	opts: ModelOptions | ResolvedModelOptions = {},
+): ChatOpenAI {
+	const resolved = "baseURL" in opts ? opts : readEnv("PLANNER", process.env);
+	// resolved.baseURL is always a string (readEnv throws if absent); cast is safe
+	const baseURL = (opts.baseURL ?? resolved.baseURL) as string;
 	return new ChatOpenAI({
-		model: opts.model ?? d.model,
-		apiKey: opts.apiKey ?? d.apiKey,
+		model: opts.model ?? resolved.model,
+		apiKey: opts.apiKey ?? resolved.apiKey,
 		temperature: opts.temperature ?? 0.2,
-		...baseURLConfig(opts.baseURL ?? d.baseURL),
+		...baseURLConfig(baseURL),
 	});
 }
 
-/** Reviewer shares the GPT configuration (can be overridden). */
-export function createReviewerModel(opts: ModelOptions = {}): ChatOpenAI {
-	const d = gptDefaults();
+/**
+ * Reviewer model — GLM family (master reviewer per design).
+ *
+ * Can be called with:
+ *   - ModelOptions (override fields, rest from env)
+ *   - ResolvedModelOptions (fully resolved from model-router, no env lookup)
+ *
+ * Env vars (when using ModelOptions):
+ *   GLM_API_KEY   (required)
+ *   GLM_MODEL     (required)
+ *   GLM_BASE_URL  (required)
+ */
+export function createReviewerModel(
+	opts: ModelOptions | ResolvedModelOptions = {},
+): ChatOpenAI {
+	const resolved = "baseURL" in opts ? opts : readEnv("GLM", process.env);
+	const baseURL = (opts.baseURL ?? resolved.baseURL) as string;
 	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),
+		model: opts.model ?? resolved.model,
+		apiKey: opts.apiKey ?? resolved.apiKey,
+		temperature: opts.temperature ?? 0.1,
+		...baseURLConfig(baseURL),
 	});
 }
 
-/** MiniMax model — used for code generation (OpenAI-compatible endpoint). */
-export function createCoderModel(opts: ModelOptions = {}): ChatOpenAI {
-	const d = minimaxDefaults();
+/**
+ * Coder model — MiniMax family.
+ *
+ * Can be called with:
+ *   - ModelOptions (override fields, rest from env)
+ *   - ResolvedModelOptions (fully resolved from model-router, no env lookup)
+ *
+ * Env vars (when using ModelOptions):
+ *   MINIMAX_API_KEY   (required)
+ *   MINIMAX_MODEL     (required)
+ *   MINIMAX_BASE_URL  (required)
+ */
+export function createCoderModel(
+	opts: ModelOptions | ResolvedModelOptions = {},
+): ChatOpenAI {
+	const resolved = "baseURL" in opts ? opts : readEnv("MINIMAX", process.env);
+	const baseURL = (opts.baseURL ?? resolved.baseURL) as string;
 	return new ChatOpenAI({
-		model: opts.model ?? d.model,
-		apiKey: opts.apiKey ?? d.apiKey,
+		model: opts.model ?? resolved.model,
+		apiKey: opts.apiKey ?? resolved.apiKey,
 		temperature: opts.temperature ?? 0.3,
-		...baseURLConfig(opts.baseURL ?? d.baseURL),
+		...baseURLConfig(baseURL),
 	});
 }

package/harness/langchain/ping-pong-middleware.d.ts

@@ -0,0 +1,28 @@
+import { PingPongDecisionEngine, type PingPongDecisionOptions, type PingPongDecisionResult } from "../../packages/intent-analyzer/src/index.js";
+export interface PingPongMiddlewareOptions extends PingPongDecisionOptions {
+    /** Shared directory watched by LoopDaemon. Defaults to /tmp/herdr-workspace. */
+    workspace?: string;
+    /** Repository root and blackboard owner. Defaults to process.cwd(). */
+    projectRoot?: string;
+    /** Agent or terminal identifier for audit records. */
+    actorId?: string;
+    /** Also enqueue suggest_ping_pong decisions. Default: false. */
+    enqueueSuggestions?: boolean;
+    /** Test hook for stable timestamps. */
+    now?: () => Date;
+}
+export interface PingPongMiddlewareResult {
+    decision: PingPongDecisionResult;
+    enqueued: boolean;
+    taskId?: string;
+    taskFile?: string;
+    auditFile: string;
+    blackboardFile: string;
+}
+export declare class PingPongMiddleware {
+    private readonly engine;
+    constructor(engine?: PingPongDecisionEngine);
+    submit(request: string, options?: PingPongMiddlewareOptions): PingPongMiddlewareResult;
+}
+export declare function submitPingPongIntent(request: string, options?: PingPongMiddlewareOptions): PingPongMiddlewareResult;
+//# sourceMappingURL=ping-pong-middleware.d.ts.map

package/harness/langchain/ping-pong-middleware.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ping-pong-middleware.test.d.ts.map

package/harness/langchain/ping-pong-middleware.test.ts

@@ -0,0 +1,69 @@
+import { describe, it } from "node:test";
+import { equal, ok } from "node:assert";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { PingPongMiddleware } from "./ping-pong-middleware.js";
+
+describe("PingPongMiddleware", () => {
+	it("records explicit PING-PONG decisions in blackboard and inbox", () => {
+		const projectRoot = mkdtempSync(join(tmpdir(), "ping-pong-project-"));
+		const workspace = mkdtempSync(join(tmpdir(), "ping-pong-workspace-"));
+		try {
+			const result = new PingPongMiddleware().submit(
+				"Good plan, then write down plan to wiki/ then I will ask Minimax to write code then you review",
+				{
+					projectRoot,
+					workspace,
+					actorId: "test-agent",
+					now: () => new Date("2026-09-10T00:00:00.000Z"),
+				},
+			);
+
+			equal(result.enqueued, true);
+			ok(result.taskFile);
+			ok(result.taskId?.endsWith(".md"));
+			const taskBody = readFileSync(result.taskFile!, "utf8");
+			ok(taskBody.includes("kind: ping-pong"));
+			ok(taskBody.includes("ask Minimax to write code"));
+
+			const blackboard = JSON.parse(
+				readFileSync(join(projectRoot, ".write-review", "status.json"), "utf8"),
+			);
+			equal(blackboard.mode, "ping_pong");
+			equal(blackboard.phase, "writing");
+			equal(blackboard.pingPong.decision, "run_ping_pong");
+			equal(blackboard.pingPong.taskId, result.taskId);
+
+			const audit = readFileSync(result.auditFile, "utf8");
+			ok(audit.includes("run_ping_pong"));
+			ok(audit.includes("test-agent"));
+		} finally {
+			rmSync(projectRoot, { recursive: true, force: true });
+			rmSync(workspace, { recursive: true, force: true });
+		}
+	});
+
+	it("records inline decisions without enqueueing", () => {
+		const projectRoot = mkdtempSync(join(tmpdir(), "ping-pong-project-"));
+		const workspace = mkdtempSync(join(tmpdir(), "ping-pong-workspace-"));
+		try {
+			const result = new PingPongMiddleware().submit(
+				"analyze why the loop is quiet, do not edit code",
+				{ projectRoot, workspace, actorId: "test-agent" },
+			);
+
+			equal(result.enqueued, false);
+			equal(result.taskFile, undefined);
+			const blackboard = JSON.parse(
+				readFileSync(join(projectRoot, ".write-review", "status.json"), "utf8"),
+			);
+			equal(blackboard.mode, "ping_pong");
+			equal(blackboard.phase, "idle");
+			equal(blackboard.pingPong.decision, "handle_inline");
+		} finally {
+			rmSync(projectRoot, { recursive: true, force: true });
+			rmSync(workspace, { recursive: true, force: true });
+		}
+	});
+});