pi-harness-runtime 1.1.423 → 1.1.424

package/scripts/verify-package-contents.ts

@@ -35,7 +35,13 @@ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const verifyTarball = process.argv.includes("--pack");
 
 interface Problem {
-	kind: "missing-dist" | "missing-import" | "missing-tarball" | "missing-package";
+	kind:
+		| "missing-dist"
+		| "missing-import"
+		| "missing-tarball"
+		| "missing-package"
+		| "forbidden-path"
+		| "missing-plugin";
 	detail: string;
 }
 
@@ -53,6 +59,37 @@ const SHIPPED_ROOT_FILES = [
 	"windows.ts",
 ];
 
+/**
+ * Paths that must never reach the published package.
+ *
+ * `.pi/` holds per-machine extension state and the user's private skills.
+ * `.pi-lens/` holds a local tool policy directory. The skill payload
+ * directories hold skill content: skills live in the user's own Qdrant
+ * collection and in the installation-local skill store, never in the
+ * published repository.
+ *
+ * `packages/skills/` is NOT in this list: that package is the runtime
+ * implementation that loads, queries and indexes skills.
+ */
+const FORBIDDEN_PACKAGE_PREFIXES = [
+	".pi/",
+	".pi-lens/",
+	"skills/",
+	".agents/skills/",
+	".claude/skills/",
+];
+
+/** The plugin directory that ships with the package. */
+const PLUGIN_DIR = "plugins";
+
+/** The files a shipped herdr plugin must contain. */
+const REQUIRED_PLUGIN_FILES = [
+	"plugins/herdr-clipboard/herdr-plugin.toml",
+	"plugins/herdr-clipboard/paste.sh",
+	"plugins/herdr-clipboard/start-bridge.sh",
+	"plugins/herdr-clipboard/tmux-watch.sh",
+];
+
 function listFiles(dir: string, filter: (file: string) => boolean): string[] {
 	if (!existsSync(dir)) return [];
 	const out: string[] = [];
@@ -98,6 +135,68 @@ const STATIC_IMPORT = /import\s+(type\s+)?[^;]*?from\s*["']([^"']+)["']/g;
 const DYNAMIC_IMPORT = /import\s*\(\s*["']([^"']+)["']\s*\)/g;
 const SIDE_EFFECT_IMPORT = /(?:^|\n)\s*import\s*["']([^"']+)["']/g;
 
+/**
+ * The published package must not carry a skill payload or a local state
+ * directory, and it must carry the plugin that the postinstall copies.
+ *
+ * The check runs on the git index, because that is what the release commits
+ * and what npm packs from.
+ */
+function checkPackageLayout(): void {
+	const tracked = spawnSync("git", ["ls-files"], {
+		cwd: ROOT,
+		encoding: "utf8",
+	});
+	const files =
+		tracked.status === 0 ? tracked.stdout.split("\n").filter(Boolean) : [];
+
+	for (const file of files) {
+		const posix = file.split("\\").join("/");
+		for (const prefix of FORBIDDEN_PACKAGE_PREFIXES) {
+			if (posix.startsWith(prefix)) {
+				problems.push({
+					kind: "forbidden-path",
+					detail: `${posix} is tracked - ${prefix} must not be committed`,
+				});
+				break;
+			}
+		}
+	}
+
+	for (const required of REQUIRED_PLUGIN_FILES) {
+		if (!files.includes(required)) {
+			problems.push({
+				kind: "missing-plugin",
+				detail: `${required} is not tracked - the plugin would not ship`,
+			});
+		}
+	}
+}
+
+/**
+ * The postinstall copies the plugin from the package root.
+ *
+ * When the source directory moved to `plugins/` the copy script kept its
+ * old path, and the plugin silently stopped being installed.
+ */
+function checkPluginCopySource(): void {
+	const script = join(ROOT, "scripts", "copy-plugins.js");
+	if (!existsSync(script)) {
+		problems.push({
+			kind: "missing-plugin",
+			detail: "scripts/copy-plugins.js is missing - the plugin would not be installed",
+		});
+		return;
+	}
+	const source = readFileSync(script, "utf8");
+	if (!source.includes(`"${PLUGIN_DIR}"`)) {
+		problems.push({
+			kind: "missing-plugin",
+			detail: `scripts/copy-plugins.js does not read from the ${PLUGIN_DIR}/ directory`,
+		});
+	}
+}
+
 function checkImports(): void {
 	for (const file of shippedSourceFiles()) {
 		const content = readFileSync(file, "utf8");
@@ -306,6 +405,28 @@ async function inspectTarball(): Promise<void> {
 		return;
 	}
 
+	for (const file of files) {
+		const posix = file.split("\\").join("/");
+		for (const prefix of FORBIDDEN_PACKAGE_PREFIXES) {
+			if (posix.startsWith(prefix)) {
+				problems.push({
+					kind: "forbidden-path",
+					detail: `${posix} is in the tarball - ${prefix} must not be published`,
+				});
+				break;
+			}
+		}
+	}
+
+	for (const required of REQUIRED_PLUGIN_FILES) {
+		if (!files.includes(required)) {
+			problems.push({
+				kind: "missing-plugin",
+				detail: `${required} is not in the tarball`,
+			});
+		}
+	}
+
 	const inTarball = new Set(files);
 	for (const { file, specifier, target } of runtimeImports.values()) {
 		const relativeTarget = relative(ROOT, target).split("\\").join("/");
@@ -321,6 +442,8 @@ async function inspectTarball(): Promise<void> {
 	}
 }
 
+checkPackageLayout();
+checkPluginCopySource();
 checkImports();
 checkPackageEntries();
 checkStaleOutputs();

package/skills/harness-runtime/SKILL.md

@@ -1,300 +0,0 @@
----
-description: Local-first, provider-agnostic AI coding harness runtime for pi.dev with quota management and multi-model coordination
----
-
-# Harness Runtime — pi Extension
-
-## CRITICAL: Todo List Rule
-
-**When you identify 2+ tasks, issues, or jobs — add ALL of them to the Todo list immediately.**
-
-Do NOT just list them in text. Use the `todo` tool to create tracked tasks:
-
-```bash
-# Creating multiple tasks at once
-bd create "Fix initialRemotionData not defined" -p 2
-bd create "Fix dictionary.title undefined" -p 2
-bd create "Replace Film icon with themed icon" -p 2
-```
-
-**Rule**: If you write something like:
-
-- "There are 3 issues: ..."
-- "I found several problems: ..."
-- "Let me fix these: 1) X 2) Y 3) Z"
-- "Here are the tasks to do: ..."
-
-**Then you MUST create Todo items for each one.** Single-issue fixes don't need tracking.
-
-**Why**: Agents often identify issues verbally but forget to track them. This rule ensures nothing slips through.
-
-## Remote Server Commands (SSH)
-
-**ALWAYS use detached SSH pattern to prevent long hangs.**
-
-### Anti-Pattern (blocks SSH, hangs indefinitely)
-
-```bash
-# WRONG - SSH blocks waiting for background process
-ssh user@host "kill old; sleep 2; uvicorn ... &"
-# SSH never returns because it waits for uvicorn
-```
-
-### Correct Pattern (fast exit, process stays on server)
-
-```bash
-# CORRECT - SSH exits fast, process continues on server
-ssh -o BatchMode=yes user@host \
-  "kill -9 OLD_PID 2>/dev/null; sleep 1; \
-   cd /path/to/service && \
-   nohup .venv/bin/uvicorn amos_api.main:app --host 0.0.0.0 --port 8100 \
-   > /tmp/uvicorn.log 2>&1 & \
-   echo 'UVICORN_STARTED'"
-```
-
-**Key changes:**
-
-- `nohup ... &` — detaches from SSH session
-- `> /tmp/uvicorn.log 2>&1` — captures output to file
-- `echo 'UVICORN_STARTED'` — SSH exits fast with confirmation
-- `-o BatchMode=yes` — non-interactive, fails fast on auth issues
-
-**Why this matters**: A bare `&` in SSH keeps the shell open. `nohup` + redirect + `echo` ensures SSH exits immediately while the process runs on the server.
-
-**For long-running commands**, add a timeout guard:
-
-```bash
-timeout 60s ssh -o BatchMode=yes user@host "long-command; echo DONE"
-```
-
-**Status:** v0.3.0 | **RFCs:** 18 defined | **Implementation:** Phase 1-6
-
-## Overview
-
-pi-harness-runtime is a local-first, provider-agnostic AI coding harness runtime for pi.dev. It coordinates multiple AI models to complete software engineering tasks with minimal human intervention.
-
-## Core Architecture
-
-```
-Human Requirement
-  -> /harness start <requirement>
-      -> Master Planner (creates task graph)
-      -> Loop Runtime (executes tasks)
-          -> Provider Router (selects best model)
-          -> BlackBoard (coordination)
-          -> Checkpoint Manager (resumability)
-          -> Quota Manager (avoid exhaustion)
-          -> Scheduler (pause/resume)
-          -> Repair Engine (auto-fix failures)
-      -> /harness status (report)
-```
-
-## Commands
-
-### Usage Commands
-
-| Command | Description |
-| --------- | ------------- |
-| `/usage` | Show full status (local tracking + provider mirror) |
-| `/usage refresh` | Force refresh quota from MiniMax console |
-| `/usage today` | Today's usage + 5h window |
-| `/usage week` | This week's usage + lifetime |
-| `/usage reset` | Clear provider mirror |
-
-### Harness Commands
-
-| Command | Description |
-| --------- | ------------- |
-| `/harness start <requirement>` | Start a new harness job |
-| `/harness status` | Show current job status |
-| `/harness tasks` | List all tasks |
-| `/harness pause` | Pause the current job |
-| `/harness resume` | Resume a paused job |
-| `/harness cancel` | Cancel the current job |
-
-### Authentication Commands
-
-| Command | Description |
-| --------- | ------------- |
-| `/harness auth minimax` | Authenticate with MiniMax (opens browser) |
-| `/harness auth check` | Check MiniMax auth status |
-| `/harness auth scrape` | Scrape MiniMax usage (silent, uses saved profile) |
-
-**First-time setup:**
-
-```bash
-harness-auth auth
-# -> Opens Chrome browser, login once, profile auto-saves
-# Or: bun packages/auth/src/run-minimax-auth.ts auth
-```
-
-**Subsequent usage:**
-
-```bash
-harness-auth scrape
-# -> Silent scraping with saved profile
-# Or: bun packages/auth/src/run-minimax-auth.ts scrape
-```
-
-## Job State Machine
-
-```
-created -> planning -> queued -> running -> testing -> reviewing
-    v        v         v        v         v
-cancelled  blocked   waiting_human  repairing  ready_for_client
-                                        v            v
-                                  paused_quota    archived
-```
-
-### State Transitions
-
-| From | Valid Transitions |
-| ------ | ----------------- |
-| created | planning |
-| planning | queued, cancelled |
-| queued | running, cancelled, waiting_human |
-| running | testing, reviewing, repairing, paused_quota, blocked, waiting_human, cancelled |
-| testing | reviewing, running, repairing, paused_quota, waiting_human, cancelled |
-| reviewing | repairing, running, ready_for_client, paused_quota, waiting_human, cancelled |
-| repairing | running, testing, reviewing, paused_quota, waiting_human, cancelled |
-| paused_quota | running, waiting_human, cancelled |
-
-## Task Graph
-
-Tasks are organized as a DAG (Directed Acyclic Graph):
-
-- Tasks with dependencies are marked `pending` until all dependencies are `done`
-- Tasks without dependencies start as `ready`
-- Only `ready` tasks are picked for execution
-
-## Key Components
-
-### JobStateMachine (`harness/job-state-machine.ts`)
-
-- Manages job lifecycle states
-- Emits events on every transition
-- Auto-checkpoints to disk
-
-### TaskGraphManager (`harness/task-graph.ts`)
-
-- DAG-based task representation
-- Tracks task status and dependencies
-- Computes topological execution order
-
-### MasterPlanner (`harness/master-planner.ts`)
-
-- Converts requirements to task graphs
-- Heuristic planner (no LLM needed)
-- LLM-based planner (with provider config)
-
-### RepairEngine (`harness/repair-engine.ts`)
-
-- Converts failures to repair tasks
-- Retry policy with exponential backoff
-- Auto-escalation after max retries
-
-### SharedBlackboard (`harness/blackboard.ts`)
-
-- File-based agent coordination
-- Next-action queue
-- Agent registry and locks
-
-### LoopRuntime (`harness/loop-runtime.ts`)
-
-- Core execution loop
-- Picks ready tasks, executes, tests, reviews
-- Handles failures and quota exhaustion
-
-### ContextWindowManager (`harness/context-window-manager.ts`)
-
-- Tracks context usage per provider
-- Warning at 80%, critical at 95%
-- Truncation strategy
-
-### AgentHandoffProtocol (`harness/agent-handoff.ts`)
-
-- Clean agent transitions
-- Context transfer
-- Handoff validation
-
-### E2ETestEngine (`harness/e2e/test-engine.ts`)
-
-- Scenario-based E2E testing
-- Screenshot/video on failure
-- Playwright runner integration
-
-### ProjectDetector (`harness/project-detector/detector.ts`)
-
-- Auto-detect: Frappe, Next.js, React, Django, Laravel
-- Seed strategy recommendation
-- E2E strategy recommendation
-
-## Providers
-
-### Provider Adapter (`packages/providers/adapters.ts`)
-
-- MiniMax, OpenAI adapters
-- Unified error parsing
-- Quota signal extraction
-
-### Quota Manager (`packages/quota-manager/quota-manager.ts`)
-
-- Collects signals from API, Playwright, local estimates
-- Tracks 5h, daily, weekly, monthly windows
-- Selects best available provider
-
-### Worktree Manager (`packages/worktree/worktree.ts`)
-
-- Git worktree per task
-- Isolated workspaces
-- Diff tracking
-
-## Usage Example
-
-```typescript
-// Start a new job
-/harness start Build a REST API with authentication
-
-// Monitor progress
-/harness status
-/harness tasks
-
-// Pause when quota is low
-/harness pause
-
-// Resume when quota resets
-/harness resume
-
-// Cancel if needed
-/harness cancel
-```
-
-## Data Directory
-
-All harness data is stored in `~/.pi/harness/`:
-
-```
-~/.pi/harness/
-  jobs/
-    <job-id>/
-      checkpoint.json
-      events.jsonl
-      task-graph.json
-      blackboard/
-      repair-tasks.jsonl
-      handoffs/
-```
-
-## Testing
-
-Run tests with:
-
-```bash
-pi-harness-runtime@latest
-```
-
-## Related Skills
-
-- `form-state-persistence-fix` — Step data persistence patterns
-- `frappe-gl-preview` — GL entry preview pattern
-- `frappe-workflow` — Workflow debugging patterns