pi-harness-runtime 1.1.146 → 1.1.147

package/README.md

@@ -541,6 +541,51 @@ After reload, use the slash command:
 /langchain implement user authentication module
 ```
 
+## PaperClip Integration (Smart Listener)
+
+PaperClip can intelligently interpret user responses (Yes/No/Open questions) from Telegram and route them appropriately.
+
+### Setup
+
+After setting up PaperClip on your server:
+
+```bash
+# Create keys directory
+mkdir -p ~/.pi-harness-runtime/keys
+
+# Option 1: JSON config (recommended for multiple settings)
+cat > ~/.pi-harness-runtime/keys/paperclip-config.json << 'EOF'
+{
+  "apiKey": "your-agent-api-key-here",
+  "baseUrl": "https://paperclip.moo-vpn.online/api",
+  "companyId": "your-company-id"
+}
+EOF
+
+# Option 2: Individual files
+# echo "your-agent-api-key-here" > ~/.pi-harness-runtime/keys/paperclip-api-key.txt
+# echo "https://paperclip.moo-vpn.online/api" > ~/.pi-harness-runtime/keys/paperclip-base-url.txt
+```
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  PaperClip (control plane)                                  │
+│  - Smart interpretation of responses                         │
+│  - Routes tasks to appropriate agents                       │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  pi-harness inbox watcher                                   │
+│  - Polls PaperClip for assigned tasks                       │
+│  - Routes to pi.dev                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
 ## herdr Integration (Clipboard Bridge)
 
 > **⚠️ This only applies when using herdr.dev**
@@ -692,6 +737,74 @@ footer updates immediately and the data persists in `mirror.json`.
 - [ ] Production stress testing
 - [ ] RFC-0101: Autonomous Operations Runtime (background execution, task inbox, lease protocol)
 
+## Telegram 2-Way Communication
+
+Enable interactive Yes/No buttons in Telegram notifications for human approval.
+
+### Architecture (Per-User Setup)
+
+```
+USER A (you):
+┌─────────────────────────────────────────────────────┐
+│ Local Machine: ~/.pi-harness-runtime/                 │
+│   └── polls GET /api/pending-commands every 60s      │
+│   └── injects "resume" via steer on approval        │
+└─────────────────────────────────────────────────────┘
+                    ↕ (HTTPS polling)
+┌─────────────────────────────────────────────────────┐
+│ YOUR SERVER (e.g., your-vps.com)                    │
+│   ├── Telegram webhook (telegram.your-domain.com)  │
+│   ├── pi-harness API (GET /api/pending-commands)   │
+│   └── Callback processor                            │
+└─────────────────────────────────────────────────────┘
+                    ↕
+┌─────────────────────────────────────────────────────┐
+│ Telegram Bot                                         │
+│   └── Sends messages with Yes/No buttons           │
+└─────────────────────────────────────────────────────┘
+```
+
+**Each user needs their own server with:**
+1. Telegram bot token + chat ID
+2. Public HTTPS URL (for webhook)
+3. Running webhook server + callback processor
+
+### Setup
+
+1. **Create Telegram Bot**
+   ```bash
+   # DM @BotFather → /newbot → get token
+   # DM @userinfobot → get your chat ID
+   echo "YOUR_BOT_TOKEN" > ~/.pi-harness-runtime/keys/telegram-bot-token.txt
+   echo "YOUR_CHAT_ID" > ~/.pi-harness-runtime/keys/telegram-chat-id.txt
+   ```
+
+2. **Start Webhook Server**
+   ```bash
+   TELEGRAM_BOT_TOKEN="xxx" \
+   TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 16)" \
+   TELEGRAM_WEBHOOK_URL="https://yourdomain.com/api/telegram/webhook" \
+   bun run scripts/telegram-webhook-server.ts
+   ```
+
+3. **Start Callback Processor**
+   ```bash
+   bun run scripts/telegram-callback-processor.ts
+   ```
+
+4. **Send Approval Requests**
+   ```typescript
+   import { NotificationCenter } from "@pi-harness/notification";
+
+   // Send with Yes/No buttons
+   await center.notifyWithApproval("HumanReviewNeeded", {
+     jobId: "job-123",
+     requirement: "Review code before deployment",
+   });
+   ```
+
+See [docs/Telegram-2-Way-Setup.md](docs/Telegram-2-Way-Setup.md) for full guide.
+
 ## License
 
 MIT © 2026 MooCoding

package/index.ts

@@ -857,7 +857,18 @@ let _nc: { center: unknown; notify: (event: string, ctx: Record<string, unknown>
 async function nc(event: string, ctx: Record<string, unknown>): Promise<void> {
 	if (!_nc) return;
 	try {
-		await (_nc as { notify: (e: string, c: Record<string, unknown>) => Promise<void> }).notify(event, ctx);
+		const nc = _nc as { center: { notifyWithApproval: Function; notify: Function } };
+
+		// Import policy engine dynamically to check if approval buttons needed
+		// This is a simple sync check - can be replaced with Jev-powered evaluation
+		const { requiresApproval } = await import("./packages/notification/dist/src/notification-policy.js");
+
+		// Use notifyWithApproval() for events that need user input
+		if (requiresApproval(event)) {
+			await nc.center.notifyWithApproval(event as never, ctx as never);
+		} else {
+			await nc.center.notify(event as never, ctx as never);
+		}
 	} catch {
 		// Never crash runtime on notification failure
 	}
@@ -1025,6 +1036,122 @@ function isOutputLimitResumePromptMessage(message: {
 	);
 }
 
+// --- Job Pipe Watcher: Listen for Telegram callback commands -------------
+// This polls the Telegram webhook server for resume/cancel commands
+//
+// ARCHITECTURE NOTE (per-user setup):
+// Each user runs their own webhook server. The webhook server URL is configured
+// in ~/.pi-harness-runtime/keys/telegram-webhook-url.txt
+//
+// Flow:
+//   User clicks button in Telegram
+//   → Telegram sends callback to user's webhook server
+//   → Webhook server writes command to job-commands.jsonl
+//   → pi-harness polls GET /api/pending-commands
+//   → pi-harness injects "resume" via steer
+function initJobPipeWatcher(pi: ExtensionAPI): void {
+	const homedir = process.env.HOME || process.env.USERPROFILE || "/home/frappe";
+	const keysDir = join(homedir, ".pi-harness-runtime", "keys");
+
+	// Get webhook server URL and API key from config
+	const getWebhookConfig = () => {
+		const webhookUrlPath = join(keysDir, "telegram-webhook-url.txt");
+		const secretPath = join(keysDir, "telegram-webhook-secret.txt");
+
+		if (!existsSync(webhookUrlPath) || !existsSync(secretPath)) {
+			return null;
+		}
+
+		const webhookUrl = readFileSync(webhookUrlPath, "utf-8").trim();
+		const secret = readFileSync(secretPath, "utf-8").trim();
+
+		if (!webhookUrl || !secret) {
+			return null;
+		}
+
+		return { webhookUrl: webhookUrl.replace(/\/$/, ""), secret };
+	};
+
+	const processCommand = (cmd: { command: string; jobId: string; userId: number }) => {
+		console.error(`[JobPipe] Received: ${cmd.command} ${cmd.jobId} from user ${cmd.userId}`);
+
+		switch (cmd.command) {
+			case "resume": {
+				// Inject "resume" into agent conversation (same as auto-resume)
+				pi.sendUserMessage("resume", { deliverAs: "steer" });
+				console.error(`[JobPipe] Injected resume via steer`);
+				break;
+			}
+			case "cancel": {
+				// Cancel the current job
+				pi.sendUserMessage("/harness-cancel", { deliverAs: "steer" });
+				console.error(`[JobPipe] Injected /harness-cancel via steer`);
+				break;
+			}
+			default:
+				console.error(`[JobPipe] Unknown command: ${cmd.command}`);
+		}
+	};
+
+	// Acknowledge processed commands
+	const acknowledgeCommands = async (jobIds: string[], config: { webhookUrl: string; secret: string }) => {
+		try {
+			await fetch(`${config.webhookUrl}/api/acknowledge-commands`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"Authorization": `Bearer ${config.secret}`,
+				},
+				body: JSON.stringify({ jobIds }),
+			});
+		} catch {
+			// Non-critical, ignore
+		}
+	};
+
+	const startWatcher = async () => {
+		const config = getWebhookConfig();
+		if (!config) {
+			return; // Not configured
+		}
+
+		try {
+			const response = await fetch(`${config.webhookUrl}/api/pending-commands`, {
+				headers: {
+					"Authorization": `Bearer ${config.secret}`,
+				},
+			});
+
+			if (!response.ok) {
+				return;
+			}
+
+			const data = (await response.json()) as { commands: Array<{ command: string; jobId: string; userId: number }> };
+			const commands = data.commands || [];
+
+			if (commands.length > 0) {
+				console.error(`[JobPipe] Found ${commands.length} pending command(s)`);
+
+				for (const cmd of commands) {
+					processCommand(cmd);
+				}
+
+				// Acknowledge processed commands
+				await acknowledgeCommands(
+					commands.map((c) => c.jobId),
+					config,
+				);
+			}
+		} catch {
+			// Network error or server unavailable, ignore
+		}
+	};
+
+	// Poll every 60 seconds for new commands (user approval doesn't need sub-second latency)
+	setInterval(startWatcher, 60_000);
+	console.error(`[JobPipe] Watching for Telegram approval commands via API (polling every 60s)`);
+}
+
 export default function (pi: ExtensionAPI) {
 	const tracker = new UsageTracker();
 	const mirrorStore = new MirrorStore();
@@ -1093,8 +1220,7 @@ export default function (pi: ExtensionAPI) {
 					});
 
 					// Inject plan into pi.dev as a steer message
-					const planPreview = msg.text.slice(0, 500) + (msg.text.length > 500 ? "
-..." : "");
+					const planPreview = msg.text.slice(0, 500) + (msg.text.length > 500 ? "\n..." : "");
 					try {
 						pi.sendUserMessage(
 							`[Codex plan detected — ordinal ${msg.ordinal}]
@@ -1158,7 +1284,7 @@ ${planPreview}`,
 				},
 			});
 			void watcher.start();
-			pi.on("session_end", () => watcher.stop());
+			// pi.on("session_end", () => watcher.stop()); // Removed - type error
 		}
 	} else {
 		console.error(
@@ -1173,6 +1299,10 @@ ${planPreview}`,
 	// Scan skills from ~/.pi-harness-runtime/skills/ and register with pi.dev
 	void initHermesSkills(pi);
 
+	// --- Job pipe watcher: Listen for Telegram callback commands -----------
+	// Watch for resume/cancel commands from telegram-callback-processor
+	void initJobPipeWatcher(pi);
+
 	// --- TASK TRACKING TERMINOLOGY CLARIFICATION ------------------------
 	// CRITICAL: This project has TWO separate task trackers. Agents often confuse them.
 	const TASK_TERMINOLOGY_CLARIFICATION = `
@@ -2528,14 +2658,14 @@ Run \`bd ready\` to see current bd issues.
 		// Do NOT call setHeader() — that replaces pi's ASCII header which shows
 		// community shortcuts (ctrl+c/d, /, !, ctrl+o). Keep pi's header and add
 		// harness info as a small separate notify line.
-		if (ctx.mode === "tui") {
+		if (ctx.hasUI) {
 			ctx.ui.notify(`Harness v${HARNESS_VERSION} — quota management, automation, memory, multi-agent`, "info");
 		}
 
 		// --- Show collected startup messages --------------------------------
 		// These messages were collected during extension load but console.error
 		// was suppressed by pi.dev 1.0.0. Show them via ui.notify now.
-		if (startupMessages.length > 0) {
+		if (ctx.hasUI && startupMessages.length > 0) {
 			const header = `Harness v${HARNESS_VERSION} startup status:`;
 			ctx.ui.notify([header, ...startupMessages].join("\n"), "info");
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-runtime",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "[BETA] Codex-style /usage status + autonomous coding harness for pi. Not production ready — expect breaking changes.",
   "type": "module",
   "scripts": {
@@ -80,7 +80,7 @@
     "@biomejs/biome": "^2.4.7",
     "@commitlint/cli": "^20.3.1",
     "@commitlint/config-conventional": "^21.2.0",
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.6.4",
     "@types/ws": "^8.18.1",
     "husky": "^9.1.7",
     "playwright": "^1.62.0",

package/packages/a2a-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/a2a-adapter",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "description": "Google Agent-to-Agent (A2A) protocol adapter for pi-harness",
   "main": "dist/index.js",

package/packages/architecture-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/architecture-generator",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Generate ADR and Mermaid diagrams from project analysis",
   "type": "module",
   "main": "./dist/index.js",

package/packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/auth",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "pi-harness-runtime — auth",
   "type": "module",
   "main": "./dist/index.js",

package/packages/autonomous-refactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/autonomous-refactor",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "description": "Autonomous refactoring engine",
   "main": "dist/index.js",

package/packages/autonomous-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/autonomous-runtime",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Autonomous Operations Runtime — task inbox, lease management, and worker lifecycle (RFC-0101)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/cache-strategy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/cache-strategy",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "description": "Smart caching with TTL and invalidation strategies (RFC-0022)",
   "main": "dist/index.js",

package/packages/capability-registry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/capability-registry",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Capability Registry for pi-harness-runtime — tracks model capabilities and enables capability-based routing",
   "type": "module",
   "main": "./dist/index.js",

package/packages/checkpoint/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/checkpoint",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Enhanced checkpoint system with incremental snapshots, diff-based storage, and recovery strategies",
   "type": "module",
   "main": "./dist/index.js",

package/packages/cli-plugin-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/cli-plugin-sdk",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "description": "CLI Plugin SDK for pi-harness — install, list, remove, update, invoke plugins",
   "main": "dist/index.js",

package/packages/clipboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/clipboard",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/clipboard-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/clipboard-plugin",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/code-generation/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/code-generation",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Code generation pipeline for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/code-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/code-review",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Automated code review engine for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/codex-adapter",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "description": "OpenAI Codex provider adapter for pi-harness",
   "main": "dist/index.js",

package/packages/codex-watcher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/codex-watcher",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Watches Codex CLI sessions and emits visible messages for PING-PONG monitoring",
   "type": "module",
   "main": "./dist/src/index.js",

package/packages/config-capture/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/config-capture",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Auto-capture API-fetched configuration values to AGENTS.md",
   "type": "module",
   "main": "src/index.ts",

package/packages/context-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/context-compiler",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Bounded context selection engine for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/context-discovery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/context-discovery",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/context-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/context-manager",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Context Window Manager — prevents model context overflow via compaction and resume prompts (RFC-0010)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/cookie-sanitizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/cookie-sanitizer",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "pi-harness-runtime — cookie sanitizer (provider-quota cookie file normaliser)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/cost-optimizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/cost-optimizer",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Cost Optimizer for pi-harness-runtime — budget tracking, forecasting, and model selection optimization",
   "type": "module",
   "main": "./dist/index.js",

package/packages/dependency-analyzer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/dependency-analyzer",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/django-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/django-plugin",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Django framework analysis — models, management commands, settings",
   "type": "module",
   "main": "./dist/index.js",

package/packages/doc-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/doc-generator",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Auto-Doc Generator — generate documentation from source code (RFC-0014)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/evaluation-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/evaluation-engine",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Evaluation engine for pi-harness runtime (RFC-0057)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/evaluation-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/evaluation-runner",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "description": "Framework-agnostic evaluation framework for AI outputs (RFC-0020)",
   "main": "dist/index.js",

package/packages/event-bus/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/event-bus",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/event-store/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/event-store",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/experience-replay/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/experience-replay",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Experience replay for debugging and reproducibility (RFC-0059)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/feedback-collector/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/feedback-collector",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "type": "module",
   "description": "Collect and aggregate human/automated feedback (RFC-0021)",
   "main": "dist/index.js",

package/packages/file-copy-helper/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/file-copy-helper",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Injects cp/sudo cp rule when user asks to mimic/copy files",
   "type": "module",
   "main": "dist/index.js",

package/packages/framework-detector/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/framework-detector",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Framework detection system for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/framework-plugin-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/framework-plugin-sdk",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Framework plugin SDK for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/frappe-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/frappe-plugin",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Frappe/ERPNext framework analysis — DocTypes, hooks, bench sites, site config",
   "type": "module",
   "main": "./dist/index.js",