pi-harness-runtime 1.1.49 → 1.1.71-3

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

@@ -0,0 +1,204 @@
+import { randomUUID, createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getHerdrWorkspace } from "../../packages/event-bus/src/herdr-bus.js";
+import {
+	PingPongDecisionEngine,
+	scanCodebaseComplexity,
+	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;
+}
+
+interface AuditRecord {
+	id: string;
+	createdAt: string;
+	actorId: string;
+	projectRoot: string;
+	request: string;
+	decision: PingPongDecisionResult["decision"];
+	score: number;
+	thresholds: PingPongDecisionResult["thresholds"];
+	reasons: string[];
+	enqueued: boolean;
+	taskId?: string;
+	taskFile?: string;
+}
+
+export class PingPongMiddleware {
+	private readonly engine: PingPongDecisionEngine;
+
+	constructor(engine = new PingPongDecisionEngine()) {
+		this.engine = engine;
+	}
+
+	submit(
+		request: string,
+		options: PingPongMiddlewareOptions = {},
+	): PingPongMiddlewareResult {
+		const workspace = options.workspace ?? getHerdrWorkspace();
+		const projectRoot = options.projectRoot ?? process.cwd();
+		const createdAt = (options.now?.() ?? new Date()).toISOString();
+		const actorId =
+			options.actorId ?? process.env.PI_AGENT_ID ?? process.env.USER ?? "unknown";
+		ensureWorkspace(workspace);
+
+		const codebase = options.codebase ?? scanCodebaseComplexity(projectRoot);
+		const decision = this.engine.analyze(request, { ...options, codebase });
+		const shouldEnqueue =
+			decision.decision === "run_ping_pong" ||
+			(options.enqueueSuggestions === true &&
+				decision.decision === "suggest_ping_pong");
+
+		let taskId: string | undefined;
+		let taskFile: string | undefined;
+		if (shouldEnqueue) {
+			const task = writeInboxTask(
+				workspace,
+				request,
+				decision,
+				createdAt,
+				actorId,
+				projectRoot,
+			);
+			taskId = task.taskId;
+			taskFile = task.taskFile;
+		}
+
+		const blackboardFile = writeBlackboardSnapshot(
+			projectRoot,
+			request,
+			decision,
+			createdAt,
+			taskId,
+		);
+
+		const auditFile = join(workspace, "ping-pong-decisions.jsonl");
+		const audit: AuditRecord = {
+			id: randomUUID(),
+			createdAt,
+			actorId,
+			projectRoot,
+			request,
+			decision: decision.decision,
+			score: decision.score,
+			thresholds: decision.thresholds,
+			reasons: decision.reasons,
+			enqueued: shouldEnqueue,
+			taskId,
+			taskFile,
+		};
+		appendFileSync(auditFile, JSON.stringify(audit) + "\n", "utf8");
+
+		return {
+			decision,
+			enqueued: shouldEnqueue,
+			taskId,
+			taskFile,
+			auditFile,
+			blackboardFile,
+		};
+	}
+}
+
+export function submitPingPongIntent(
+	request: string,
+	options: PingPongMiddlewareOptions = {},
+): PingPongMiddlewareResult {
+	return new PingPongMiddleware().submit(request, options);
+}
+
+function writeBlackboardSnapshot(
+	projectRoot: string,
+	request: string,
+	decision: PingPongDecisionResult,
+	createdAt: string,
+	taskId?: string,
+): string {
+	const dir = join(projectRoot, ".write-review");
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	const statusFile = join(dir, "status.json");
+	const now = new Date().toISOString();
+	const phase = decision.decision === "run_ping_pong" ? "writing" : "idle";
+	const status = {
+		projectPath: projectRoot,
+		phase,
+		writerDone: false,
+		writerMessage: request,
+		iteration: 0,
+		mode: "ping_pong",
+		pingPong: {
+			decision: decision.decision,
+			score: decision.score,
+			runThreshold: decision.thresholds.run,
+			suggestThreshold: decision.thresholds.suggest,
+			reasons: decision.reasons,
+			request,
+			taskId,
+			createdAt,
+		},
+		createdAt,
+		updatedAt: now,
+	};
+	writeFileSync(statusFile, JSON.stringify(status, null, 2), "utf8");
+	return statusFile;
+}
+function ensureWorkspace(workspace: string): void {
+	if (!existsSync(workspace)) mkdirSync(workspace, { recursive: true });
+	const dirs = ["payloads", "subscriptions", "leases", "reviews", "code"];
+	for (const dir of dirs) {
+		const path = join(workspace, dir);
+		if (!existsSync(path)) mkdirSync(path, { recursive: true });
+	}
+}
+
+function writeInboxTask(
+	workspace: string,
+	request: string,
+	decision: PingPongDecisionResult,
+	createdAt: string,
+	actorId: string,
+	projectRoot: string,
+): { taskId: string; taskFile: string } {
+	const hash = createHash("sha256").update(request).digest("hex").slice(0, 10);
+	const nonce = randomUUID().slice(0, 8);
+	const taskId = "ping-pong-" + Date.now() + "-" + hash + "-" + nonce;
+	const taskFile = join(workspace, taskId + ".md");
+	const body = [
+		"---",
+		"kind: ping-pong",
+		"createdAt: " + createdAt,
+		"actorId: " + actorId,
+		"projectRoot: " + projectRoot,
+		"decision: " + decision.decision,
+		"score: " + decision.score,
+		"runThreshold: " + decision.thresholds.run,
+		"---",
+		"",
+		request.trim(),
+		"",
+	].join("\n");
+	writeFileSync(taskFile, body, "utf8");
+	return { taskId: taskId + ".md", taskFile };
+}

package/harness/langchain/run.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=run.d.ts.map

package/harness/langchain/run.ts

@@ -26,6 +26,8 @@ interface CliArgs {
 	maxIterations: number;
 	dryRun: boolean;
 	daemon: boolean;
+	/** If true, remaining args are passed to the cron subcommand handler. */
+	cronArgs?: string[];
 }
 
 function parseArgs(argv: string[]): CliArgs {
@@ -51,6 +53,13 @@ function parseArgs(argv: string[]): CliArgs {
 			normalized.push(arg);
 		}
 	}
+	// Detect "cron" subcommand before processing other flags
+	const cronIndex = normalized.indexOf("cron");
+	if (cronIndex !== -1) {
+		args.cronArgs = normalized.slice(cronIndex + 1);
+		return args;
+	}
+
 	for (const arg of normalized) {
 		if (arg.startsWith("--mode=")) {
 			const mode = arg.slice("--mode=".length);
@@ -89,9 +98,9 @@ function parseArgs(argv: string[]): CliArgs {
 			if (!args.request) args.request = arg;
 		}
 	}
-	if (!args.request && !args.daemon) {
+	if (!args.request && !args.daemon && !args.cronArgs) {
 		throw new Error(
-			'A request is required: --request="..." or a bare string (or use --daemon to start the watcher)',
+			'A request is required: --request="..." or a bare string (or use --daemon or --cron to start the watcher)',
 		);
 	}
 	return args;
@@ -190,7 +199,10 @@ async function runDaemon(args: CliArgs): Promise<void> {
 
 async function main(): Promise<void> {
 	const args = parseArgs(process.argv.slice(2));
-	if (args.daemon) {
+	if (args.cronArgs !== undefined) {
+		const { runCron } = await import("./cron-cli.js");
+		await runCron(args.cronArgs);
+	} else if (args.daemon) {
 		await runDaemon(args);
 	} else if (args.mode === "supervisor") {
 		await runSupervisor(args);

package/harness/langchain/scoreboard.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Scoreboard integration tests — T15
+ *
+ * Tests that the WriteReviewBlackboard is correctly wired into the LangGraph loop:
+ * 1. `buildRealLoopDeps` creates and updates the blackboard at each step
+ * 2. Agent prompts receive the scoreboard markdown
+ * 3. `status.json` reflects the current phase/verdict/files
+ *
+ * Run:
+ *   bun test harness/langchain/scoreboard.test.ts
+ */
+export {};
+//# sourceMappingURL=scoreboard.test.d.ts.map

package/harness/langchain/scoreboard.test.ts

@@ -19,7 +19,6 @@ import { buildDryRunDeps } from "./graph.js";
 import { createLoopCheckpointer } from "./checkpointer.js";
 
 describe("T15 — Scoreboard blackboard wiring", () => {
-
 	const tmpDir = `/tmp/scoreboard-test-${Date.now()}`;
 	const blackboardDir = join(tmpDir, ".write-review");
 
@@ -48,6 +47,8 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 			code: "",
 			review: null as any,
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 
 		const statusPath = join(blackboardDir, "status.json");
@@ -67,6 +68,8 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 			code: "",
 			review: null as any,
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 
 		const content = JSON.parse(
@@ -89,6 +92,8 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 			code: "",
 			review: null as any,
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 
 		deps.onStep?.("write", {
@@ -98,6 +103,8 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 			code: "``` harness/langchain/surge.ts\nconst x = 1;\n```",
 			review: null as any,
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 
 		const content = JSON.parse(
@@ -122,15 +129,19 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 			code: "",
 			review: null as any,
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 
 		deps.onStep?.("write", {
 			request: "test",
 			plan: "# plan",
 			iteration: 1,
-			code: '```harness/langchain/surge.ts\nconst x = 1;\n```',
+			code: "```harness/langchain/surge.ts\nconst x = 1;\n```",
 			review: null as any,
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 
 		deps.onStep?.("review", {
@@ -146,6 +157,8 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 				],
 			},
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 
 		const content = JSON.parse(
@@ -153,7 +166,10 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 		);
 		assert.equal(content.phase, "changes_requested");
 		assert.equal(content.verdict, "changes_requested");
-		assert.ok(content.changesRequested?.length > 0, "changesRequested should be set");
+		assert.ok(
+			content.changesRequested?.length > 0,
+			"changesRequested should be set",
+		);
 	});
 
 	it("dry-run plan prompt includes scoreboard markdown", async () => {
@@ -170,10 +186,12 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 			code: "",
 			review: null as any,
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 
 		// Call plan() — the stub returns a string that includes scoreboard context
-		const result = await deps.plan("implement X");
+		const _result = await deps.plan("implement X");
 
 		// The stub output should include the plan text; the scoreboard is in the
 		// agent context, not the stub return value. Verify status.json was written.
@@ -194,6 +212,8 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 			code: "",
 			review: null as any,
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 		deps.onStep?.("write", {
 			request: "test",
@@ -202,6 +222,8 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 			code: "```a.ts\n1\n```",
 			review: null as any,
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 		deps.onStep?.("review", {
 			request: "test",
@@ -210,6 +232,8 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 			code: "```a.ts\n1\n```",
 			review: { verdict: "approved", summary: "ok", comments: [] },
 			log: [],
+			lastCommentedFile: undefined,
+			seenCommentPairs: [],
 		});
 
 		const content = JSON.parse(
@@ -218,5 +242,4 @@ describe("T15 — Scoreboard blackboard wiring", () => {
 		assert.equal(content.phase, "approved");
 		assert.equal(content.iteration, 1);
 	});
-
 });

package/harness/langchain/status-line.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Status line manager — drives the harness loop status in the pi host.
+ *
+ * Architecture:
+ *
+ *   Pi-lens installed?
+ *   ├─ YES → LoopWidget.makeRenderer() → pi host's ui.setWidget("harness-loop", ...)
+ *   └─ NO  → write to .harness-status → pi host reads and displays
+ *
+ * The status line shows two tiers of information:
+ *   [loop status]  [API quota]
+ *   [P] planning  |  MiniMax: 5h: 89% left · week: 90% left
+ *
+ * API quota is read from ~/.pi-harness/quota.json (written by the pi host
+ * process that has access to the TUI quota signals).  The daemon polls this
+ * file every 60s so the status line stays fresh even when no task is running.
+ *
+ * Wiki: wiki/pi-lens-status-line.md
+ */
+export interface QuotaData {
+    /** MiniMax 5-hour window usage percentage (0–100). Undefined = unknown. */
+    fiveHourPercent?: number;
+    /** MiniMax weekly window usage percentage (0–100). Undefined = unknown. */
+    weeklyPercent?: number;
+    /** ISO timestamp of when the 5-hour quota resets. */
+    fiveHourResetAt?: string;
+    /** ISO timestamp of when the weekly quota resets. */
+    weeklyResetAt?: string;
+    /** Raw message from GLM quota signal (for display) */
+    rawMessage?: string;
+}
+/** True when the daemon is running inside a pi-lens-equipped pi host. */
+export declare function isPiLensAvailable(): boolean;
+/**
+ * Build a one-line status string.
+ * Format: "MiniMax: 5h: 89% left (resets in 2h) · week: 90% left"
+ */
+export declare function formatQuotaLine(q: QuotaData): string;
+/**
+ * Drives the harness status line in the pi host.
+ *
+ * - When pi-lens is available: provides the LoopWidget renderer factory
+ *   for the pi host to integrate via `ui.setWidget("harness-loop", factory)`.
+ * - When pi-lens is not available: writes a plain-text status to
+ *   `<workspace>/.harness-status` every time update() is called.
+ *
+ * The pi host can read `.harness-status` and display it in its own UI.
+ */
+export declare class StatusLineManager {
+    private readonly workspace;
+    private readonly quotaFile;
+    private lastQuota;
+    private timer?;
+    private loopStatus;
+    constructor(workspace: string);
+    /**
+     * Start polling the quota file.
+     * Call once after construction.
+     */
+    start(): void;
+    /** Stop polling. */
+    stop(): void;
+    /**
+     * Update the loop status (planning/writing/reviewing/finished).
+     * Call this from the daemon's onStep handler.
+     */
+    updateLoopStatus(status: string): void;
+    /**
+     * Update the full status — call after each loop transition.
+     * Writes the status file (when no pi-lens) and logs to console.
+     */
+    update(data: {
+        loopStatus?: string;
+        quota?: QuotaData;
+    }): void;
+    /**
+     * Returns a rendered one-line status string for the pi host to display.
+     * Combines loop status + quota into a single readable line.
+     */
+    getLine(): string;
+    private _pollQuota;
+    private _writeStatusFile;
+}
+/**
+ * Write quota data to the shared quota file.
+ * Call this from the pi host process that receives GLM TUI signals.
+ *
+ * The daemon reads this file to keep its status line fresh.
+ */
+export declare function writeQuotaFile(data: QuotaData): void;
+//# sourceMappingURL=status-line.d.ts.map

package/harness/langchain/status-line.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * StatusLineManager tests — T16
+ *
+ * Tests the pi-lens detection, quota formatting, and status file writing
+ * when pi-lens is not available.
+ */
+export {};
+//# sourceMappingURL=status-line.test.d.ts.map

package/harness/langchain/surge.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Surge auto-resume — 529 / overloaded_error (MiniMax) + 1308 (GLM quota) detection,
+ * escalation backoff, and retry wrappers for the daemon's graph invocations.
+ *
+ * Two wrappers:
+ *   invokeWithSurgeRetry     — MiniMax 529/overload; exponential backoff
+ *   invokeWithGLMRetry       — GLM 1308 quota; waits until reset time
+ *
+ * Wiki: wiki/peak-hour-surge-auto-resume.md
+ */
+export interface SurgeSignal {
+    /** Parsed recovery delay in ms (midpoint of the stated range, or fallback) */
+    retryAfterMs: number;
+    /** True when the delay came from an explicit provider statement */
+    explicit: boolean;
+    /** Raw error text for logs */
+    sourceText: string;
+}
+/**
+ * Classify an unknown error as a transient provider surge (MiniMax).
+ * Returns null for anything that is not a 529/overload-class failure.
+ */
+export declare function classifySurge(err: unknown): SurgeSignal | null;
+/**
+ * Classify a GLM 1308 quota exhaustion error.
+ * Returns the reset-at ISO timestamp, or null if not a GLM quota error.
+ */
+export declare function classifyGLMQuota(err: unknown): GLMQuotaSignal | null;
+export interface GLMQuotaSignal {
+    /** ISO timestamp when the quota resets */
+    resetAt: string;
+    /** Epoch ms when the quota resets */
+    resetAtEpoch: number;
+    /** Raw error text for logs */
+    sourceText: string;
+}
+export interface SurgePolicy {
+    /** Override the signal's parsed delay (ms). Default: use the signal. */
+    baseDelayMs?: number;
+    /** Delay multiplier per attempt. Default: 2 (3 → 6 → 12 min) */
+    multiplier: number;
+    /** Floor for any wait. Default: 30_000 (never hammer a surging provider) */
+    minDelayMs: number;
+    /** Ceiling for any wait. Default: 15 min */
+    maxDelayMs: number;
+    /** ± ratio applied as jitter. Default: 0.2 */
+    jitterRatio: number;
+    /** Max surge pauses before giving up. Default: 5 */
+    maxAttempts: number;
+}
+/**
+ * Deterministic delay computation (unit-testable, no timers).
+ * `rand` in [0,1] controls jitter; omit it for zero jitter.
+ */
+export declare function computeSurgeDelayMs(signal: SurgeSignal, attempt: number, policy?: Partial<SurgePolicy>, rand?: number): number;
+/** Attempt counter with escalation; persists across a task's lifetime. */
+export declare class SurgeScheduler {
+    private attempt;
+    private readonly policy;
+    constructor(policy?: Partial<SurgePolicy>);
+    /** Next attempt number, or null when maxAttempts is exhausted. */
+    nextAttempt(): number | null;
+    get attempts(): number;
+    delayFor(signal: SurgeSignal, rand?: number): number;
+}
+export interface SurgeRetryOptions {
+    policy?: Partial<SurgePolicy>;
+    /** Called before each surge pause (logging / notifications) */
+    onSurge?: (info: {
+        attempt: number;
+        delayMs: number;
+        signal: SurgeSignal;
+    }) => void;
+    /** Called once when attempts are exhausted (before rethrow) */
+    onExhausted?: (signal: SurgeSignal) => void;
+    /** Injectable sleep for tests. Default: real setTimeout */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Run `fn`, retrying only on surge-classified failures (MiniMax 529/overload)
+ * with exponential backoff. Non-surge errors rethrow immediately.
+ */
+export declare function invokeWithSurgeRetry<T>(fn: () => Promise<T>, opts?: SurgeRetryOptions): Promise<T>;
+export interface GLMRetryOptions {
+    /** Called when GLM quota exhaustion is detected (for status-line countdown) */
+    onGLMQuota?: (signal: GLMQuotaSignal) => void;
+    /** Called after the countdown expires and the loop retries */
+    onGLMRetry?: (signal: GLMQuotaSignal) => void;
+    /** Called when the GLM quota error is non-retryable (e.g., no reset time) */
+    onGLMExhausted?: (signal: GLMQuotaSignal) => void;
+    /** Injectable sleep for tests. Default: real setTimeout */
+    sleep?: (ms: number) => Promise<void>;
+    /** How often to tick the countdown callback (default: 30s) */
+    tickMs?: number;
+}
+/**
+ * Run `fn`, retrying on GLM 1308 quota errors.
+ * After the first 1308, waits until the reset time before retrying.
+ * Subsequent 1308s within the same wait window are silently ignored.
+ * Non-GLM-quota errors rethrow immediately.
+ */
+export declare function invokeWithGLMRetry<T>(fn: () => Promise<T>, opts?: GLMRetryOptions): Promise<T>;
+//# sourceMappingURL=surge.d.ts.map

package/harness/langchain/surge.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Surge auto-resume tests — S2/S4 acceptance (wiki/peak-hour-surge-auto-resume.md)
+ *
+ * All deterministic via injected sleep/rand — no real timers, no API keys.
+ *
+ * Run:
+ *   bun test harness/langchain/surge.test.ts
+ */
+export {};
+//# sourceMappingURL=surge.test.d.ts.map