pi-harness-runtime 1.1.445 → 1.1.446

package/packages/skills/src/sync-source.ts

@@ -0,0 +1,114 @@
+/**
+ * The skill sync: where the skills come from, and which script performs it.
+ *
+ * The source tree is installation data, not a constant of the product: the
+ * package must not guess a path on the operator's machine, and it must not
+ * print one either. The operator names the directory with an environment
+ * variable, and every message the package prints uses that name.
+ *
+ * The script is the other half and it belongs to the package, so it is
+ * found relative to the module - it works wherever the package was
+ * installed.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The environment variable that names the directory the operator wants to
+ * sync skills FROM.
+ */
+export const SKILLS_SOURCE_ENV = "PI_HARNESS_SKILLS_SOURCE";
+
+/**
+ * Expand a leading `~` to the home directory.
+ *
+ * A shell expands `~`, a program does not, and the operator writes the
+ * value the way they would write it on a command line.
+ */
+export function expandHome(path: string): string {
+	if (path === "~") return homedir();
+	if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+	return path;
+}
+
+/**
+ * The directory the operator configured as the skill source, if any.
+ */
+export function getSkillsSource(): string | undefined {
+	const raw = process.env[SKILLS_SOURCE_ENV]?.trim();
+	if (!raw) return undefined;
+	return expandHome(raw);
+}
+
+/**
+ * The source the operator asked for on the command line, if any.
+ *
+ * The `--from` argument wins over the environment variable, because the
+ * argument is the more specific statement.
+ */
+export function getSkillsSourceFromArgs(args: string[]): string | undefined {
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === "--from" || arg === "-f") return args[i + 1];
+		if (arg.startsWith("--from=")) return expandHome(arg.slice("--from=".length));
+	}
+	return getSkillsSource();
+}
+
+/**
+ * The path of the sync script that ships with this package.
+ *
+ * The script lives in `scripts/` at the package root, and this module
+ * lives in `packages/skills/src/` (or in `packages/skills/dist/` when the
+ * package is compiled), so the script is three levels up. Finding it
+ * relative to the module works wherever the package was installed - the
+ * source of the skills is the operator's business, the script is ours.
+ *
+ * An installation without the script is a real state: the caller reports
+ * it instead of spawning a path that does not exist.
+ */
+export function syncSkillsScriptPath(
+	moduleUrl: string = import.meta.url,
+): string | undefined {
+	const path = fileURLToPath(
+		new URL("../../../scripts/sync-skills.ts", moduleUrl),
+	);
+	return existsSync(path) ? path : undefined;
+}
+
+/**
+ * The hint that tells the operator how to sync skills, when it applies.
+ *
+ * The hint applies when the harness skills directory exists but is empty
+ * and the configured source directory holds skills. It returns undefined
+ * when there is nothing to suggest.
+ */
+export function skillsSyncHint(): string | undefined {
+	try {
+		const harnessDir = join(homedir(), ".pi-harness-runtime", "skills");
+		if (!existsSync(harnessDir)) return undefined;
+
+		const entries = readdirSync(harnessDir).filter((n: string) => n !== "harness-runtime");
+		if (entries.length > 0) return undefined; // Has user skills, nothing to suggest
+
+		const source = getSkillsSource();
+		if (!source) return undefined;
+		if (!existsSync(source)) return undefined;
+
+		const skillEntries = readdirSync(source).filter((n: string) =>
+			existsSync(join(source, n, "SKILL.md")),
+		);
+		if (skillEntries.length === 0) return undefined;
+
+		return (
+			`[pi-harness] ${skillEntries.length} skill(s) found in ${source}. ` +
+			`Sync them: bun scripts/sync-skills.ts --from ${source}`
+		);
+	} catch {
+		// Non-fatal — ignore errors
+		return undefined;
+	}
+}

package/packages/todo-bd-sync/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/todo-bd-sync",
-  "version": "1.1.445",
+  "version": "1.1.446",
   "description": "Two-way sync between rpiv-todo overlay and bd issue tracker",
   "type": "module",
   "main": "src/index.ts",

package/packages/token-estimation/package.json

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

package/packages/tooling-preference/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tooling-preference",
-  "version": "1.1.445",
+  "version": "1.1.446",
   "description": "pi-harness-runtime — JS/TS tooling preference (Biome vs ESLint/Prettier) proposal",
   "type": "module",
   "main": "./dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/trajectory",
-  "version": "1.1.445",
+  "version": "1.1.446",
   "description": "Trajectory capture for the write-review loop — persists cycle records for learning",
   "type": "module",
   "main": "./dist/src/index.js",

package/packages/tui/package.json

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

package/packages/two-phase-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/two-phase-review",
-  "version": "1.1.445",
+  "version": "1.1.446",
   "description": "pi-harness-runtime — two-phase implementation and review workflow (queue review signals, gate the phase, scope the diff)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/types",
-  "version": "1.1.445",
+  "version": "1.1.446",
   "description": "Shared TypeScript types for pi-harness-runtime packages",
   "type": "module",
   "main": "./dist/index.js",

package/packages/webmcp-tester/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/webmcp-tester",
-  "version": "1.1.445",
+  "version": "1.1.446",
   "description": "WebMCP-powered E2E testing for pi-harness - natural language test scenarios",
   "type": "module",
   "main": "./dist/index.js",

package/packages/wiki/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/wiki",
-  "version": "1.1.445",
+  "version": "1.1.446",
   "description": "LLM Wiki integration for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/write-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/write-review",
-  "version": "1.1.445",
+  "version": "1.1.446",
   "description": "Two-agent write-review loop with blackboard coordination",
   "type": "module",
   "main": "src/index.ts",

package/CLAUDE.md

@@ -1,77 +0,0 @@
-# Project Instructions for AI Agents
-
-This file provides instructions and context for AI coding agents working on this project.
-
-<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
-## Beads Issue Tracker
-
-This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
-
-### Quick Reference
-
-```bash
-bd ready              # Find available work
-bd show <id>          # View issue details
-bd update <id> --claim  # Claim work
-bd close <id>         # Complete work
-```
-
-### Rules
-
-- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
-- Run `bd prime` for detailed command reference and session close protocol
-- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
-
-## Session Completion
-
-**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
-
-**MANDATORY WORKFLOW:**
-
-1. **File issues for remaining work** - Create issues for anything that needs follow-up
-2. **Run quality gates** (if code changed) - Tests, linters, builds
-3. **Update issue status** - Close finished work, update in-progress items
-4. **PUSH TO REMOTE** - This is MANDATORY:
-   ```bash
-   git pull --rebase
-   bd dolt push
-   git push
-   git status  # MUST show "up to date with origin"
-   ```
-5. **Clean up** - Clear stashes, prune remote branches
-6. **Verify** - All changes committed AND pushed
-7. **Hand off** - Provide context for next session
-
-**CRITICAL RULES:**
-- Work is NOT complete until `git push` succeeds
-- NEVER stop before pushing - that leaves work stranded locally
-- NEVER say "ready to push when you are" - YOU must push
-- If push fails, resolve and retry until it succeeds
-<!-- END BEADS INTEGRATION -->
-
-
-## Build & Test
-
-_Add your build and test commands here_
-
-```bash
-# Example:
-# npm install
-# npm test
-```
-
-## Architecture Overview
-
-_Add a brief overview of your project architecture_
-
-## Conventions & Patterns
-
-### Git Workflow
-
-After running `git status`, **ALWAYS** run `git add --all` before asking about committing. Never assume changes are staged.
-
-```bash
-git status  # inspect changes
-git add --all  # stage everything
-git commit    # then proceed
-```

package/TODO-todo-bd-sync.md

@@ -1,124 +0,0 @@
-# TODO: Complete todo-bd-sync Implementation
-
-## Status: Phase 1 & 2 Complete
-
-### What was implemented
-
-1. **Package structure** (`packages/todo-bd-sync/`)
-   - ✅ `src/types.ts` - Type definitions for TodoTask, BdIssue, IdMappingRegistry
-   - ✅ `src/detector.ts` - Dependency detection (rpiv-todo, bd CLI)
-   - ✅ `src/sync.ts` - Two-way sync logic (todo ↔ bd)
-   - ✅ `src/index.ts` - Main API with TodoBdSync class
-   - ✅ `src/extension.ts` - pi-coding-agent extension entry
-   - ✅ `src/todo-reminder.ts` - Auto-reminder for continuing todos
-   - ✅ `package.json` - Package manifest
-
-2. **Integration into main extension**
-   - ✅ Added import and lazy initialization to `index.ts`
-
-3. **Documentation**
-   - ✅ `docs/todo-bd-sync.md` - Full documentation with auto-reminder feature
-   - ✅ `README.md` - Added section and commands
-
----
-
-## New: Auto-Reminder Feature (Phase 2)
-
-### Problem Fixed
-
-- **Bug**: LLM completes tasks but stays silent about remaining todos
-- **User had to manually ask**: "continue with todos" or "wrap up"
-
-### Solution
-
-The `todo-reminder.ts` module injects reminders when todos remain:
-
-**Prerequisite**: Tasks must be created with `bd create` (not via `/todo` command).
-
-```typescript
-// After agent completes a task:
-// Checks bd for remaining todos
-// Injects message:
-"Remaining todos detected:
-[bd-a1b2] Review PR (pending)
-
-Please continue with the next pending task or ask the user which to prioritize."
-```
-
-### How It Works
-
-1. Hooks into `agent_end` and `tool_execution_end`
-2. Calls `bd ready --json` to check remaining todos
-3. If pending tasks exist, sends reminder via `pi.sendUserMessage()`
-4. 5-second cooldown to prevent spam
-
----
-
-## Remaining Tasks
-
-### P1: Test Basic Integration
-
-```bash
-# Restart pi and test
-pi
-
-# Check if todo-bd-sync is enabled
-/bd-todo-status
-```
-
-### P2: Test Auto-Reminder
-
-1. Create a multi-step task via bd:
-
-   ```bash
-   bd create "Build API" -p 2
-   bd create "Add tests" --parent <parent-id>
-   bd create "Deploy" --parent <parent-id>
-   ```
-
-2. Ask LLM to work on it:
-
-   ```
-   Build the API and manage tasks with bd
-   ```
-
-3. After completing a task, verify reminder is injected:
-   - Should see message about remaining todos
-   - LLM should offer to continue
-
-### P3: Tune Reminder Behavior
-
-- Adjust cooldown (currently 5 seconds)
-- Customize reminder message template
-- Test with various task counts
-
----
-
-## Files Summary
-
-| File | Purpose |
-|------|---------|
-| `src/types.ts` | Type definitions |
-| `src/detector.ts` | Check dependencies |
-| `src/sync.ts` | bd CLI integration |
-| `src/todo-reminder.ts` | **NEW: Auto-reminder injection** |
-| `src/index.ts` | Main API |
-| `src/extension.ts` | Extension entry |
-
----
-
-## Testing Plan
-
-1. **Basic sync**: Create bd issue → verify sync
-2. **Auto-reminder**: Multi-step task → verify reminder appears
-3. **Integration**: Full workflow test
-
----
-
-## Notes
-
-- The implementation uses lazy imports to avoid breaking if dependencies are missing
-- bd CLI must be installed for full functionality
-- rpiv-todo is optional (fallback mode available)
-- Auto-reminder does NOT modify the overlay (it works fine)
-- Only injects context to prompt LLM to continue

package/auto-resume-fix-prompt.md

@@ -1,189 +0,0 @@
-# Auto-Resume Fix After Context Overflow Compaction
-
-## Problem Statement
-
-After context overflow compaction with `willRetry=false`, the agent does NOT automatically resume. The session pauses waiting for user input, even though context-mode has a resume snapshot that should be delivered.
-
-## Root Cause Analysis
-
-### The Compaction Flow
-
-1. **Context overflow occurs** -> `_checkCompaction()` is called
-2. **For overflow with `stopReason === "stop"`** (the common case):
-   - `willRetry = assistantMessage.stopReason !== "stop"` -> **FALSE**
-   - Calls `_runAutoCompaction("overflow", false)`
-3. **Inside `_runAutoCompaction`** (line 1685):
-
-   ```javascript
-   return this.agent.hasQueuedMessages();  // <-  Returns FALSE for overflow case!
-   ```
-
-4. **Result**: Session pauses waiting for user input
-
-### Why Context-Mode Resume Wasn't Delivered
-
-Context-mode builds resume snapshot in `session_before_compact` and stores it in DB:
-
-```javascript
-// From extension.js
-pi.on("session_before_compact", () => {
-    const snapshot = buildResumeSnapshot(allEvents, { compactCount });
-    db.upsertResume(_sessionId, snapshot, allEvents.length);
-});
-```
-
-But resume was only injected in `before_agent_start` via the `context` hook:
-
-```javascript
-pi.on("before_agent_start", async (event, ctx) => {
-    const resume = db.getResume(_sessionId);
-    if (resume && !resume.consumed && resume.snapshot) {
-        parts.push(resume.snapshot);
-        db.markResumeConsumed(_sessionId);
-    }
-    // ...
-});
-```
-
-**Problem**: `before_agent_start` only fires when a **new prompt is submitted**. After overflow compaction with `willRetry=false`, no prompt is submitted -> resume is never delivered.
-
-## Solution Implemented: Post-Compaction Message Queue
-
-Added a new extension API `queuePostCompactionMessage()` that allows extensions to queue messages that should be delivered after compaction completes, even when `willRetry=false`.
-
-### Flow After Fix
-
-1. `session_before_compact` -> Build resume snapshot in DB
-2. `session_compact` -> Queue resume via `ctx.queuePostCompactionMessage()`
-3. After compaction completes -> `drainPostCompactionMessages()` delivers queued messages
-4. Agent continues and delivers resume automatically
-
-## Files Changed
-
-### 1. `pi-coding-agent/dist/core/extensions/types.d.ts`
-
-Added new API to `ExtensionContext` and `ExtensionContextActions`:
-
-```typescript
-// ExtensionContext
-/**
- * Queue a message to be delivered after compaction completes.
- * When willRetry=false (e.g. overflow without context recovery), the agent
- * will continue and deliver these queued messages before pausing for user input.
- * Useful for resuming context-mode's snapshot after overflow compaction.
- */
-queuePostCompactionMessage(message: { role: string; content: string }): void;
-
-// ExtensionContextActions
-queuePostCompactionMessage: (message: { role: string; content: string }) => void;
-```
-
-### 2. `pi-coding-agent/dist/core/extensions/runner.js`
-
-Added new methods to `ExtensionRunner`:
-
-```javascript
-// Instance variable
-_postCompactionMessages = [];
-
-// Method to queue messages (called from extension context)
-queuePostCompactionMessageFn = (message) => {
-    this._postCompactionMessages.push(message);
-};
-
-// Method to get and clear messages (called by agent-session after compaction)
-drainPostCompactionMessages() {
-    if (this.staleMessage) {
-        return [];  // Don't drain if stale
-    }
-    const messages = this._postCompactionMessages;
-    this._postCompactionMessages = [];
-    return messages;
-}
-
-// Check if runner is stale (without throwing)
-isStale() {
-    return Boolean(this.staleMessage);
-}
-```
-
-### 3. `pi-coding-agent/dist/core/agent-session.js`
-
-Modified `_runAutoCompaction()` to check for and deliver post-compaction messages:
-
-```javascript
-// After compaction completes (line 1682)
-this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
-
-if (willRetry) {
-    // ... existing retry logic
-    return true;
-}
-
-// Check for post-compaction messages from extensions
-if (this._extensionRunner && !this._extensionRunner.isStale()) {
-    const postCompactionMessages = this._extensionRunner.drainPostCompactionMessages();
-    for (const msg of postCompactionMessages) {
-        await this.agent.followUp(msg.content);
-    }
-    if (postCompactionMessages.length > 0) {
-        return true; // Continue to deliver the queued messages
-    }
-}
-
-// Fall back to existing behavior
-return this.agent.hasQueuedMessages();
-```
-
-### 4. `context-mode/build/adapters/pi/extension.js`
-
-Modified `session_compact` handler to queue resume:
-
-```javascript
-pi.on("session_compact", (event, ctx) => {
-    try {
-        if (!_sessionId)
-            return;
-        db.incrementCompactCount(_sessionId);
-
-        // Queue resume snapshot for post-compaction delivery when willRetry=false
-        if (!event.willRetry) {
-            const resume = db.getResume(_sessionId);
-            if (resume && !resume.consumed && resume.snapshot) {
-                ctx.queuePostCompactionMessage?.({
-                    role: "user",
-                    content: resume.snapshot,
-                });
-                db.markResumeConsumed(_sessionId);
-            }
-        }
-    }
-    catch {
-        // best effort
-    }
-});
-```
-
-## Testing
-
-To verify the fix works:
-
-1. **Trigger context overflow** with a long conversation
-2. **Observe compaction happens automatically**
-3. **Agent continues WITHOUT user input**
-4. **Resume snapshot is delivered** and agent continues working
-
-Check with:
-
-```bash
-pi
-# Run a long conversation that triggers overflow
-# Verify agent continues automatically after compaction
-/ctx-stats
-```
-
-## Backward Compatibility
-
-- The new `queuePostCompactionMessage` API is optional (uses `?.` when calling)
-- Extensions that don't use it continue to work unchanged
-- Existing behavior for `willRetry=true` cases is preserved