pi-harness-runtime 1.1.144 → 1.1.145

package/packages/paperclip-integration/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pi-harness/paperclip-integration",
+  "version": "1.1.145",
+  "description": "Paperclip API integration: poll agent inbox, route tasks to pi.dev, Telegram alerts",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --skipLibCheck"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  }
+}

package/packages/paperclip-integration/src/index.ts

@@ -0,0 +1,326 @@
+/**
+ * Paperclip Integration — RFC-00XX
+ *
+ * Connects pi-harness-runtime to Paperclip's control plane.
+ *
+ * Architecture:
+ *   Paperclip (control plane) → REST API → pi-harness inbox watcher
+ *   → Telegram alerts → pi.dev agent executes → Paperclip task updates
+ *
+ * Key flows:
+ *   1. Poll Paperclip inbox (assigned tasks) → route to pi.dev via sendUserMessage
+ *   2. Emit Telegram alerts for all task state changes
+ *   3. Update Paperclip issue status on task completion/failure
+ *
+ * Paperclip API base: https://api.paperclip.inc/api
+ * Auth: Bearer token (agent API key)
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PaperclipConfig {
+	/** Paperclip API base URL */
+	baseUrl: string;
+	/** Agent API key (bearer token) */
+	apiKey: string;
+	/** Company ID for company-scoped endpoints */
+	companyId?: string;
+	/** Poll interval in ms (default: 30000 = 30s) */
+	pollIntervalMs?: number;
+	/** Called with a Telegram-friendly summary when a task is detected */
+	onTaskDetected?: (task: PaperclipIssue) => void;
+	/** Called when task status changes */
+	onTaskStatusChange?: (task: PaperclipIssue, oldStatus: string) => void;
+}
+
+export interface PaperclipIssue {
+	id: string;
+	identifier: string; // e.g. "PAP-39"
+	title: string;
+	status: string;
+	priority?: string;
+	assigneeId?: string;
+	assigneeName?: string;
+	description?: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface PaperclipAgentMe {
+	id: string;
+	name: string;
+	email: string;
+	companyId: string;
+	companyName: string;
+	role: string;
+}
+
+// ---------------------------------------------------------------------------
+// Paperclip Client
+// ---------------------------------------------------------------------------
+
+export class PaperclipClient {
+	private readonly baseUrl: string;
+	private readonly apiKey: string;
+	private readonly headers: Record<string, string>;
+
+	constructor(config: PaperclipConfig) {
+		this.baseUrl = config.baseUrl.replace(/\/$/, "");
+		this.apiKey = config.apiKey;
+		this.headers = {
+			Authorization: `Bearer ${this.apiKey}`,
+			"Content-Type": "application/json",
+		};
+	}
+
+	/**
+	 * Get current agent's identity and company context
+	 */
+	async getAgentMe(): Promise<PaperclipAgentMe> {
+		const res = await this.request<PaperclipAgentMe>("GET", "/api/agents/me");
+		return res;
+	}
+
+	/**
+	 * Get inbox issues assigned to this agent (mine-tab equivalent)
+	 */
+	async getInbox(companyId: string): Promise<PaperclipIssue[]> {
+		const params = new URLSearchParams({
+			status: "todo,in_progress,needs_review",
+			assigneeId: "me",
+		});
+		const res = await this.request<{ issues: PaperclipIssue[] }>(
+			"GET",
+			`/api/companies/${companyId}/issues?${params}`,
+		);
+		return res.issues ?? [];
+	}
+
+	/**
+	 * Get a single issue by ID or human-readable identifier
+	 */
+	async getIssue(issueIdOrIdentifier: string): Promise<PaperclipIssue> {
+		// Try as identifier first (PAP-39), then as UUID
+		try {
+			return await this.request<PaperclipIssue>("GET", `/api/issues/${issueIdOrIdentifier}`);
+		} catch {
+			return await this.request<PaperclipIssue>(
+				"GET",
+				`/api/issues/by-identifier/${issueIdOrIdentifier}`,
+			);
+		}
+	}
+
+	/**
+	 * Update issue status
+	 */
+	async updateIssueStatus(
+		issueIdOrIdentifier: string,
+		status: string,
+	): Promise<PaperclipIssue> {
+		return this.request<PaperclipIssue>("PATCH", `/api/issues/${issueIdOrIdentifier}`, { body: JSON.stringify({ status }) });
+	}
+
+	/**
+	 * Add a comment to an issue
+	 */
+	async addComment(issueId: string, body: string): Promise<void> {
+		await this.request("POST", `/api/issues/${issueId}/comments`, { body: JSON.stringify({ body }) });
+	}
+
+	private async request<T>(
+		method: string,
+		path: string,
+		options: { body?: string } = {},
+	): Promise<T> {
+		const url = path.startsWith("http")
+			? path
+			: `${this.baseUrl}${path}`;
+
+		const res = await fetch(url, {
+			method,
+			headers: this.headers,
+			body: options.body,
+		});
+
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(
+				`Paperclip API ${method} ${path} failed (${res.status}): ${text}`,
+			);
+		}
+
+		return res.json() as Promise<T>;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Paperclip Watcher — polls inbox, routes tasks to pi.dev
+// ---------------------------------------------------------------------------
+
+export interface PaperclipWatcherOptions {
+	/** pi-harness Telegram nc() helper */
+	nc: (event: string, ctx: Record<string, unknown>) => Promise<void>;
+	/** pi.dev sendUserMessage function */
+	sendUserMessage: (content: string, opts?: { deliverAs?: string }) => void;
+	/** Optional: update Paperclip issue status after routing */
+	onRouted?: (issue: PaperclipIssue) => Promise<void>;
+	/** Poll interval in ms (default: 30s) */
+	pollIntervalMs?: number;
+}
+
+export class PaperclipWatcher {
+	private client: PaperclipClient;
+	private options: PaperclipWatcherOptions;
+	private timer: ReturnType<typeof setInterval> | null = null;
+	private seenIds = new Set<string>();
+	private companyId: string | null = null;
+	private agentName: string = "agent";
+
+	constructor(config: PaperclipConfig, options: PaperclipWatcherOptions) {
+		this.client = new PaperclipClient(config);
+		this.options = options;
+	}
+
+	/**
+	 * Start polling the Paperclip inbox
+	 */
+	async start(): Promise<void> {
+		// Fetch agent identity
+		try {
+			const me = await this.client.getAgentMe();
+			this.companyId = me.companyId;
+			this.agentName = me.name;
+			console.error(`[paperclip] Agent: ${me.name} @ ${me.companyName}`);
+		} catch (err) {
+			console.error(
+				`[paperclip] Failed to get agent identity: ${err instanceof Error ? err.message : String(err)}`,
+			);
+			return;
+		}
+
+		// Initial poll
+		await this.poll();
+
+		// Schedule polling
+		const interval = this.options.pollIntervalMs ?? 30_000;
+		this.timer = setInterval(() => {
+			void this.poll();
+		}, interval);
+	}
+
+	/**
+	 * Stop polling
+	 */
+	stop(): void {
+		if (this.timer) {
+			clearInterval(this.timer);
+			this.timer = null;
+		}
+	}
+
+	/**
+	 * Manually trigger a poll (useful after Telegram command)
+	 */
+	async pollNow(): Promise<void> {
+		await this.poll();
+	}
+
+	private async poll(): Promise<void> {
+		if (!this.companyId) return;
+
+		try {
+			const issues = await this.client.getInbox(this.companyId);
+
+			for (const issue of issues) {
+				// Skip already-seen issues
+				if (this.seenIds.has(issue.id)) continue;
+				this.seenIds.add(issue.id);
+
+				// Route to Telegram
+				this.options.nc("TaskCompleted", {
+					requirement: `[Paperclip] ${issue.identifier}: ${issue.title}`,
+					taskTitle: issue.title,
+					taskId: issue.id,
+					error: `New task assigned: ${issue.priority ? `P${issue.priority}` : ""}`,
+				});
+
+				// Route to pi.dev
+				const body = `[Paperclip task assigned to ${this.agentName}]\n\n` +
+					`**${issue.identifier}**: ${issue.title}\n` +
+					`Status: ${issue.status}${issue.priority ? `\nPriority: ${issue.priority}` : ""}\n` +
+					`\n${issue.description ?? ""}`;
+
+				try {
+					this.options.sendUserMessage(body, { deliverAs: "steer" });
+				} catch {
+					// pi.dev may not be ready
+				}
+
+				// Mark as in_progress in Paperclip
+				this.options.onRouted?.(issue);
+			}
+		} catch (err) {
+			console.error(
+				`[paperclip] Poll failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Auto-init from env / keys file
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if Paperclip is configured
+ */
+export function hasPaperclipConfig(): boolean {
+	const apiKey =
+		process.env.PAPERCLIP_API_KEY ||
+		process.env.PAPERCLIP_API_KEY;
+	if (!apiKey) {
+		const homedir = process.env.HOME || process.env.USERPROFILE || "/home/frappe";
+		try {
+			const { readFileSync, existsSync } = require("fs");
+			const path = `${homedir}/.pi-harness-runtime/keys/paperclip-api-key.txt`;
+			if (existsSync(path)) {
+				const key = readFileSync(path, "utf8").trim();
+				return key.length > 10;
+			}
+		} catch {
+			// ignore
+		}
+	}
+	return !!apiKey;
+}
+
+/**
+ * Get Paperclip config from environment / keys file
+ */
+export function getPaperclipConfig(): PaperclipConfig | null {
+	const apiKey =
+		process.env.PAPERCLIP_API_KEY ||
+		process.env.PAPERCLIP_API_KEY;
+	const baseUrl =
+		process.env.PAPERCLIP_BASE_URL ||
+		"https://api.paperclip.inc/api";
+
+	if (!apiKey) {
+		const homedir = process.env.HOME || process.env.USERPROFILE || "/home/frappe";
+		try {
+			const { readFileSync, existsSync } = require("fs");
+			const path = `${homedir}/.pi-harness-runtime/keys/paperclip-api-key.txt`;
+			if (!existsSync(path)) return null;
+			const key = readFileSync(path, "utf8").trim();
+			if (!key || key.length < 10) return null;
+			return { apiKey: key, baseUrl };
+		} catch {
+			return null;
+		}
+	}
+
+	return { apiKey, baseUrl };
+}

package/packages/performance-optimizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/performance-optimizer",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Performance optimization analyzer for pi-harness runtime (RFC-0056)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/privilege-broker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/privilege-broker",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Privilege Broker — capability registry and command executor for autonomous runtime (RFC-0101 §7)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/project-analyzer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/project-analyzer",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Project analysis system for pi-harness-runtime - detects frameworks, rules, and project structure",
   "type": "module",
   "main": "./dist/index.js",

package/packages/project-bootstrap/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/project-bootstrap",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Project scaffolding from typed ProjectSpec",
   "type": "module",
   "main": "./dist/index.js",

package/packages/projection-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/projection-engine",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/prompt-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/prompt-compiler",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Deterministic prompt compiler for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/prompt-versioning/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/prompt-versioning",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "type": "module",
   "description": "Version control for prompts with rollback support (RFC-0019)",
   "main": "dist/index.js",

package/packages/provider-adapter-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/provider-adapter-sdk",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "SDK for building, testing, and registering AI provider adapters",
   "type": "module",
   "main": "./dist/index.js",

package/packages/provider-router/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/provider-router",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Enhanced Provider Router for pi-harness-runtime — intelligent routing with capabilities, costs, and quotas",
   "type": "module",
   "main": "./dist/provider-router.js",

package/packages/provider-selector/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/provider-selector",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Multi-Provider Selector — route requests by cost, quality, and latency (RFC-0012)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/providers/package.json

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

package/packages/qdrant-skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/qdrant-skills",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Qdrant vector search integration for Hermes-style skill system",
   "type": "module",
   "main": "./dist/index.js",

package/packages/quota-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/quota-manager",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "pi-harness-runtime — quota-manager",
   "type": "module",
   "main": "./dist/index.js",

package/packages/rate-limiter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/rate-limiter",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "type": "module",
   "description": "Rate limiting with token bucket algorithm (RFC-0023)",
   "main": "dist/index.js",

package/packages/react-vite-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/react-vite-plugin",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "React/Vite framework analysis — components, config, TypeScript setup",
   "type": "module",
   "main": "./dist/index.js",

package/packages/release-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/release-manager",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "type": "module",
   "description": "Release management for pi-harness",
   "main": "dist/index.js",

package/packages/requirement-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/requirement-compiler",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Compiles raw requirements into validated CompiledRequirement with ambiguity detection and risk tagging",
   "type": "module",
   "main": "./dist/index.js",

package/packages/runtime/package.json

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

package/packages/scheduler/package.json

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

package/packages/scheduler-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/scheduler-adapter",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Scheduler Adapter — cron, systemd, launchd, internal adapters for autonomous runtime (RFC-0101 §6)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/session/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/session",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Session management system for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/session-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/session-api",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/session-export/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/session-export",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/shared-context/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/shared-context",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "pi-harness-runtime — shared-context",
   "type": "module",
   "main": "./dist/index.js",

package/packages/skill-mcp-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/skill-mcp-client",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "MCP client for Skills SaaS backend",
   "type": "module",
   "main": "./dist/index.js",

package/packages/skill-registry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/skill-registry",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Skill Registry for pi-harness-runtime — dynamic skill discovery and invocation",
   "type": "module",
   "main": "./dist/index.js",

package/packages/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/skills",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "File-based skill system with pi.dev compatibility and Hermes self-improvement",
   "type": "module",
   "main": "src/index.ts",

package/packages/sprint-planner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/sprint-planner",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "type": "module",
   "description": "Sprint planning engine for pi-harness",
   "main": "dist/index.js",

package/packages/subscription-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/subscription-engine",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/task-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/task-compiler",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Task Compiler for pi-harness-runtime — produces deterministic task DAG from CompiledRequirement",
   "type": "module",
   "main": "./dist/index.js",

package/packages/tencentdb-memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/tencentdb-memory",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "TencentDB Agent Memory client - sync skills to centralized knowledge base",
   "type": "module",
   "main": "src/index.ts",

package/packages/tencentdb-sync/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tencentdb-sync",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Sync SKILL.md skills to TencentDB-Agent-Memory server (RFC-0105/0106)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/test-data-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/test-data-generator",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Test data generation for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/test-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/test-generator",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "description": "Auto-Test Generator — generate unit and E2E tests from source code (RFC-0013)",
   "type": "module",
   "main": "./dist/index.js",