pi-harness-runtime 1.1.0 → 1.1.2

package/packages/write-review/src/review.ts

@@ -0,0 +1,206 @@
+/**
+ * Review Integration
+ *
+ * Uses pi-subagents review-loop for multi-round code review.
+ */
+
+import type { WriteReviewStatus } from "./types.js";
+
+/**
+ * Review round result
+ */
+export interface ReviewResult {
+	verdict: "approved" | "changes_requested" | "blocked";
+	iteration: number;
+	message: string;
+	changesNeeded?: string[];
+	issues?: ReviewIssue[];
+}
+
+/**
+ * Issue found during review
+ */
+export interface ReviewIssue {
+	severity: "blocker" | "major" | "minor" | "suggestion";
+	type: "correctness" | "security" | "performance" | "style" | "test" | "docs";
+	location: string;
+	description: string;
+	suggestion?: string;
+}
+
+/**
+ * Build review task for pi-subagents
+ */
+export function buildReviewTask(
+	status: WriteReviewStatus,
+	projectPath: string,
+): string {
+	const codeFiles = status.codeFiles ?? [];
+	const iteration = status.iteration;
+
+	const task = `## Review Task - Iteration ${iteration}
+
+Review the code written in this iteration.
+
+### Code Files to Review:
+${codeFiles.map((f) => `- ${f}`).join("\n") || "No files recorded yet."}
+
+### Project Path: ${projectPath}
+
+### Review Instructions:
+1. Read the code files listed above.
+2. Run the review-loop workflow using pi-subagents.
+3. Focus on: correctness, security, performance, tests, and code style.
+4. Return a verdict: APPROVED, CHANGES_REQUESTED, or BLOCKED.
+
+### Verdict Format:
+\`\`\`
+## Verdict: [APPROVED|CHANGES_REQUESTED|BLOCKED]
+[Your detailed review message]
+\`\`\`
+
+For CHANGES_REQUESTED, list specific changes needed:
+\`\`\`
+## Changes Needed:
+1. [Issue description] - [File:Line]
+2. [Issue description] - [File:Line]
+\`\`\`
+`;
+
+	return task;
+}
+
+/**
+ * Parse verdict from review output
+ */
+export function parseVerdict(output: string): {
+	verdict: "approved" | "changes_requested" | "blocked";
+	message: string;
+	changes?: string[];
+} | null {
+	const lines = output.split("\n");
+	let verdict: "approved" | "changes_requested" | "blocked" | null = null;
+	let message = "";
+	const changes: string[] = [];
+	let inChanges = false;
+
+	for (const line of lines) {
+		const lower = line.toLowerCase();
+
+		if (lower.includes("## verdict:")) {
+			if (lower.includes("approved")) {
+				verdict = "approved";
+			} else if (
+				lower.includes("changes_requested") ||
+				lower.includes("changes requested")
+			) {
+				verdict = "changes_requested";
+			} else if (lower.includes("blocked")) {
+				verdict = "blocked";
+			}
+			continue;
+		}
+
+		if (lower.includes("## changes needed:") || lower.includes("changes:")) {
+			inChanges = true;
+			continue;
+		}
+
+		if (inChanges && line.trim().match(/^\d+\./)) {
+			changes.push(line.trim());
+			continue;
+		}
+
+		if (verdict && line.trim()) {
+			message += line + "\n";
+		}
+	}
+
+	if (!verdict) return null;
+
+	return {
+		verdict,
+		message: message.trim(),
+		changes: changes.length > 0 ? changes : undefined,
+	};
+}
+
+/**
+ * Review angles for parallel review
+ */
+export const REVIEW_ANGLES = [
+	{
+		name: "correctness",
+		description:
+			"Verify implementation matches requirements and handles edge cases",
+	},
+	{
+		name: "tests",
+		description: "Check test coverage and validity",
+	},
+	{
+		name: "complexity",
+		description:
+			"Look for unnecessary complexity and opportunities to simplify",
+	},
+];
+
+/**
+ * Build parallel review prompt
+ */
+export function buildParallelReviewPrompt(
+	codeFiles: string[],
+	projectPath: string,
+): string {
+	return `Run parallel reviewers on this code:
+
+1. **correctness** - Verify implementation matches requirements and handles edge cases
+2. **tests** - Check test coverage and validity
+3. **complexity** - Look for unnecessary complexity
+
+Files: ${codeFiles.join(", ")}
+Project: ${projectPath}
+
+Use pi-subagents to spawn 3 parallel reviewers. Wait for all results, then synthesize into a final verdict.`;
+}
+
+/**
+ * Format review summary for blackboard
+ */
+export function formatReviewSummary(result: ReviewResult): string {
+	const lines = [
+		`## Review Result - Iteration ${result.iteration}`,
+		"",
+		`**Verdict:** ${result.verdict.toUpperCase()}`,
+		"",
+	];
+
+	if (result.message) {
+		lines.push("### Message");
+		lines.push(result.message);
+		lines.push("");
+	}
+
+	if (result.changesNeeded && result.changesNeeded.length > 0) {
+		lines.push("### Changes Needed");
+		for (const change of result.changesNeeded) {
+			lines.push(`- ${change}`);
+		}
+		lines.push("");
+	}
+
+	if (result.issues && result.issues.length > 0) {
+		lines.push("### Issues Found");
+		for (const issue of result.issues) {
+			lines.push(`- [${issue.severity}] ${issue.type}: ${issue.description}`);
+			if (issue.location) {
+				lines.push(`  Location: ${issue.location}`);
+			}
+			if (issue.suggestion) {
+				lines.push(`  Suggestion: ${issue.suggestion}`);
+			}
+		}
+	}
+
+	return lines.join("\n");
+}

package/packages/write-review/src/trigger.ts

@@ -0,0 +1,133 @@
+/**
+ * Wiki Prompt Trigger
+ *
+ * Detects when an agent reads a prompt from {project}/wiki/*
+ * This triggers the write-review loop.
+ */
+
+import { existsSync } from "fs";
+import { join, relative } from "path";
+import type { ReviewTriggerContext } from "./types.js";
+
+const DEFAULT_WIKI_DIR = "wiki";
+
+/**
+ * Detect if a file path is a wiki prompt
+ */
+export function isWikiPrompt(filePath: string, projectPath: string): boolean {
+	const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+	const normalizedPath = filePath.replace(/\\/g, "/");
+	const normalizedWiki = wikiDir.replace(/\\/g, "/");
+
+	return (
+		normalizedPath.startsWith(normalizedWiki + "/") ||
+		normalizedPath.startsWith(normalizedWiki + "\\")
+	);
+}
+
+/**
+ * Extract prompt metadata from wiki path
+ */
+export function parseWikiPrompt(
+	filePath: string,
+	projectPath: string,
+): { category: string; filename: string } | null {
+	const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+	const rel = relative(wikiDir, filePath).replace(/\\/g, "/");
+
+	if (!rel || rel.startsWith("..")) return null;
+
+	const parts = rel.split("/");
+	if (parts.length >= 2) {
+		return {
+			category: parts[0],
+			filename: parts.slice(1).join("/"),
+		};
+	}
+	return {
+		category: "root",
+		filename: parts[0],
+	};
+}
+
+/**
+ * Get all wiki prompt files in a project
+ */
+export function getWikiPrompts(
+	projectPath: string,
+): { path: string; category: string; filename: string }[] {
+	const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+
+	if (!existsSync(wikiDir)) {
+		return [];
+	}
+
+	const prompts: { path: string; category: string; filename: string }[] = [];
+
+	function scanDir(dir: string): void {
+		const { readdirSync, statSync } = require("fs");
+		try {
+			for (const entry of readdirSync(dir)) {
+				const fullPath = join(dir, entry);
+				const stat = statSync(fullPath);
+				if (stat.isDirectory()) {
+					scanDir(fullPath);
+				} else if (
+					stat.isFile() &&
+					(entry.endsWith(".md") || entry.endsWith(".txt"))
+				) {
+					const relPath = relative(wikiDir, fullPath).replace(/\\/g, "/");
+					const parts = relPath.split("/");
+					prompts.push({
+						path: fullPath,
+						category: parts[0],
+						filename: parts.slice(1).join("/"),
+					});
+				}
+			}
+		} catch {
+			// Ignore permission errors
+		}
+	}
+
+	scanDir(wikiDir);
+	return prompts;
+}
+
+/**
+ * Create trigger context from a wiki read event
+ */
+export function createTriggerContext(
+	filePath: string,
+	projectPath: string,
+	triggerType: ReviewTriggerContext["triggerType"] = "wiki_read",
+): ReviewTriggerContext | null {
+	if (!isWikiPrompt(filePath, projectPath)) {
+		return null;
+	}
+
+	const parsed = parseWikiPrompt(filePath, projectPath);
+	if (!parsed) return null;
+
+	return {
+		projectPath,
+		promptFile: filePath,
+		promptContent: "", // Will be filled by caller
+		triggerType,
+	};
+}
+
+/**
+ * Check if current working directory has wiki prompts
+ */
+export function hasWikiPrompts(projectPath: string): boolean {
+	const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+	return existsSync(wikiDir);
+}
+
+/**
+ * Get wiki directory path
+ */
+export function getWikiDir(projectPath: string): string {
+	return join(projectPath, DEFAULT_WIKI_DIR);
+}

package/packages/write-review/src/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Write-Review Loop Types
+ *
+ * State machine for two-agent write-review coordination.
+ */
+
+/**
+ * Review phases
+ */
+export type ReviewPhase =
+	| "idle"
+	| "writing"
+	| "pending_review"
+	| "reviewing"
+	| "approved"
+	| "blocked"
+	| "changes_requested";
+
+/**
+ * Review verdict
+ */
+export type Verdict = "approved" | "changes_requested" | "blocked";
+
+/**
+ * Blackboard status record
+ */
+export interface WriteReviewStatus {
+	projectPath: string;
+	phase: ReviewPhase;
+	writerDone: boolean;
+	writerMessage?: string;
+	iteration: number;
+	verdict?: Verdict;
+	verdictMessage?: string;
+	reviewerStarted?: string; // ISO timestamp
+	codeFiles?: string[]; // Files written
+	changesRequested?: string[]; // Changes needed
+	approvedAt?: string; // ISO timestamp
+	blockedAt?: string; // ISO timestamp
+	updatedAt: string;
+	createdAt: string;
+}
+
+/**
+ * Review trigger context
+ */
+export interface ReviewTriggerContext {
+	projectPath: string;
+	promptFile: string;
+	promptContent: string;
+	triggerType: "wiki_read" | "manual" | "code_written";
+}
+
+/**
+ * Extension config
+ */
+export interface WriteReviewConfig {
+	debug?: boolean;
+	blackboardDir?: string; // Default: "{project}/.write-review"
+	wikiDir?: string; // Default: "{project}/wiki"
+	enabled?: boolean;
+}
+
+/**
+ * Agent roles
+ */
+export const AGENT_ROLES = {
+	WRITER: "writer", // Minimax - reads wiki, writes code
+	REVIEWER: "reviewer", // Uses pi-subagents review-loop
+	HELPER: "helper", // worker - notes tasks to todo
+} as const;
+
+export type AgentRole = (typeof AGENT_ROLES)[keyof typeof AGENT_ROLES];
+
+/**
+ * State transition helpers
+ */
+export function isTerminalPhase(phase: ReviewPhase): boolean {
+	return phase === "approved" || phase === "blocked";
+}
+
+export function needsReview(phase: ReviewPhase): boolean {
+	return phase === "pending_review" || phase === "reviewing";
+}
+
+export function canWrite(phase: ReviewPhase): boolean {
+	return (
+		phase === "idle" || phase === "writing" || phase === "changes_requested"
+	);
+}

package/prompts/agents/reviewer.md

@@ -0,0 +1,57 @@
+---
+description: Reviewer agent - evaluate code quality and request changes
+argument-hint: "<task context>"
+---
+# Reviewer Agent
+
+You are the **REVIEWER** agent. Your job is to evaluate code quality and request fixes.
+
+## Review Criteria
+
+1. **Correctness** - Does it solve the problem?
+2. **Type Safety** - TypeScript types correct?
+3. **Edge Cases** - Handles null/undefined/empty?
+4. **Security** - No injection vulnerabilities?
+5. **Performance** - No obvious O(n^2) loops?
+6. **Testability** - Can be unit tested?
+
+## Your Workflow
+
+1. Read the code artifacts from blackboard
+2. Evaluate against review criteria
+3. Write your findings to the blackboard
+4. Issue verdict:
+   - `APPROVED` - Code is ready
+   - `CHANGES_REQUESTED` - Issues found
+   - `BLOCKED` - Critical issues
+
+## Blackboard Location
+
+```
+{project}/.write-review/status.json
+```
+
+## Verdict Format
+
+```
+## REVIEW FINDINGS
+
+### Issues Found
+- [issue description]
+
+## VERDICT: CHANGES_REQUESTED
+
+Please fix the issues above.
+```
+
+Or:
+
+```
+## REVIEW FINDINGS
+
+No critical issues found.
+
+## VERDICT: APPROVED
+
+Code is ready for build/commit.
+```

package/prompts/agents/writer.md

@@ -0,0 +1,42 @@
+---
+description: Writer agent - implement code and wait for review verdict
+argument-hint: "<task description>"
+---
+# Writer Agent
+
+You are the **WRITER** agent. Your job is to implement code based on the task.
+
+## Task
+
+$@
+
+## Your Workflow
+
+1. Read and understand the task
+2. Implement the code
+3. Write your artifacts to the blackboard
+4. Write `## WRITER_DONE` when finished
+5. Wait for review verdict
+6. If `CHANGES_REQUESTED`, update code accordingly
+7. Acknowledge each verdict
+
+## Blackboard Location
+
+```
+{project}/.write-review/status.json
+```
+
+## Important Rules
+
+- Do NOT build or commit until you receive `APPROVED`
+- Write code only in the assigned files
+- Keep artifacts focused and complete
+- Respond to each verdict acknowledgment
+
+## Verdict Response
+
+When you receive a verdict:
+
+- `APPROVED`: Acknowledge and proceed to build/commit
+- `CHANGES_REQUESTED`: Update the code and rewrite `## WRITER_DONE`
+- `BLOCKED`: Stop and wait for human intervention

package/prompts/slash-commands.md

@@ -0,0 +1,40 @@
+---
+description: Show available slash commands and usage hints
+---
+# Slash Commands Reference
+
+Type `/` in the editor to see autocomplete.
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/wr` | Start write-review loop (writer + reviewer) |
+| `/writer` | Activate writer agent for a task |
+| `/reviewer` | Activate reviewer agent |
+| `/tdb` | Connect to TencentDB |
+| `/tdb-setup` | Setup TencentDB connection |
+| `/cl` | Code review for changelog |
+
+## Write-Review Loop
+
+```
+/wr Create a new API endpoint
+```
+
+1. Writer implements code
+2. Reviewer checks quality
+3. Loop until APPROVED
+4. Build/commit when ready
+
+## Status File
+
+Check review status:
+
+```
+cat .write-review/status.json
+```
+
+## More Info
+
+See `prompts/write-review.md` for full documentation.

package/prompts/tencentdb-connect.md

@@ -0,0 +1,35 @@
+---
+description: Connect to your own TencentDB-Agent-Memory server
+argument-hint: "<action>"
+---
+# TencentDB-Agent-Memory Connection Setup
+
+## Available Actions
+
+Use `/tencentdb-connect` with one of these actions:
+
+| Action | Description |
+|--------|-------------|
+| `connect` | Connect to an existing server |
+| `deploy` | Deploy a new server |
+| `test` | Test current connection |
+| `status` | Check server health |
+
+## Connect to Existing Server
+
+Run `/tencentdb-connect connect` and provide:
+
+1. **Server URL** - Your TencentDB server address
+   - Example: `https://memory.your-domain.com`
+   
+2. **Service ID** - Usually `default`
+
+3. **User Key** - Provided by server admin
+
+## Deploy New Server
+
+Run `/tencentdb-connect deploy` for guided VPS deployment.
+
+## Test Connection
+
+Run `/tencentdb-connect test` to verify your setup.

package/prompts/tencentdb-setup.md

@@ -0,0 +1,101 @@
+---
+description: Interactively configure TencentDB-Agent-Memory connection
+argument-hint: "<server-url> [service-id] [user-key]"
+---
+# Setup TencentDB-Agent-Memory Connection
+
+${1:---}
+
+## Configuration Options
+
+**Arguments:**
+- `$1` = Server URL (e.g., `https://memory.example.com`)
+- `$2` = Service ID (default: `default`)
+- `$3` = User Key (from server admin)
+
+## Step-by-Step Setup
+
+### Step 1: Enter Server URL
+
+Please provide your TencentDB-Agent-Memory server URL:
+
+```
+https://your-server.com
+```
+
+### Step 2: Enter Service ID
+
+Enter your service ID (or press Enter for `default`):
+
+```
+default
+```
+
+### Step 3: Enter User Key
+
+Enter your user key:
+
+```
+your-user-key-here
+```
+
+## Configuration Methods
+
+### Option A: Environment File (.env)
+
+Create or update `.env` in your project:
+
+```bash
+TENANTDB_URL=${1:-https://your-server.com}
+TENANTDB_SERVICE_ID=${2:-default}
+TENANTDB_USER_KEY=${3}
+```
+
+### Option B: Settings JSON
+
+Add to `.pi/settings.json`:
+
+```json
+{
+  "tencentdb": {
+    "url": "${1:-https://your-server.com}",
+    "serviceId": "${2:-default}",
+    "userKey": "${3}"
+  }
+}
+```
+
+## Verification
+
+Test your connection:
+
+```bash
+curl -X GET "${1:-https://your-server.com}/health" \
+  -H "x-tdai-service-id: ${2:-default}" \
+  -H "x-tdai-user-key: ${3}"
+```
+
+Expected response:
+```json
+{"status": "ok", "version": "1.0.0"}
+```
+
+## Usage Examples
+
+### Search Knowledge
+```bash
+curl -X POST "${1}/api/v1/memory/search" \
+  -H "x-tdai-service-id: ${2}" \
+  -H "x-tdai-user-key: ${3}" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "your search query"}'
+```
+
+### Sync Skills
+```bash
+curl -X POST "${1}/api/v1/skills/sync" \
+  -H "x-tdai-service-id: ${2}" \
+  -H "x-tdai-user-key: ${3}" \
+  -H "Content-Type: application/json" \
+  -d '{"skills": [...]}'
+```