@asterxsk/kiln 0.2.0 → 0.3.0

package/agent.bak.20260905-190020/extensions/goal/index.ts

@@ -0,0 +1,155 @@
+/**
+ * goal — keep the agent working until the goal is achieved.
+ *
+ * Commands:
+ *   /goal <prompt>   Research → design → plan → implement → verify, looping
+ *                    until you confirm the goal is achieved.
+ *   /goal            Prompts for the goal interactively.
+ *
+ * After the agent settles, this extension asks whether to keep working, mark
+ * the goal achieved, or pause. "Keep working" re-engages the agent until the
+ * goal is done. See README.md for the phase-by-phase workflow.
+ */
+
+import { homedir } from "node:os";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+const HOME = homedir().replace(/\\/g, "/");
+const BRAINSTORMING_SKILL = `${HOME}/.agents/skills/brainstorming/SKILL.md`;
+const WRITING_PLANS_SKILL = `${HOME}/.agents/skills/writing-plans/SKILL.md`;
+
+/** Shared closing instruction for every /goal pass. */
+const REPORT_TAIL = "When you finish a pass, report what is done, what remains, and whether the goal is achieved.";
+
+/** The goal the agent is currently working toward, or null when idle. */
+let activeGoal: string | null = null;
+
+function shortGoal(goal: string): string {
+	const s = goal.replace(/\s+/g, " ").trim();
+	return s.length > 60 ? `${s.slice(0, 60)}…` : s;
+}
+
+function buildInstruction(goal: string): string {
+	return [
+		"You are executing a /goal workflow: research, then design, then plan, then implement and verify — working until the goal is achieved.",
+		"",
+		"GOAL:",
+		goal,
+		"",
+		"Work through the phases in order.",
+		"",
+		"PHASE 1 — RESEARCH",
+		"- Use web_search to research the goal: relevant technologies, existing libraries and approaches, best practices, constraints, and open questions.",
+		"- Gather grounded facts to inform the design; cite what you learn in the design doc.",
+		"",
+		"PHASE 2 — DESIGN",
+		`- First read the brainstorming skill: ${BRAINSTORMING_SKILL}. Follow it.`,
+		"- Ask clarifying questions one at a time (use ask_user when a choice can be enumerated) to pin down purpose, constraints, and success criteria.",
+		"- Propose 2-3 approaches with trade-offs and a recommendation; present the design in sections and get approval after each section.",
+		"- When the design is approved, save it to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and ask the user to review it.",
+		"- STOP here and wait for the user to approve the design doc. Do not begin later phases until the user explicitly approves.",
+		"",
+		"PHASE 3 — PLAN",
+		`- First read the writing-plans skill: ${WRITING_PLANS_SKILL}. Follow it.`,
+		"- Write a detailed, bite-sized implementation plan with no placeholders and save it to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md.",
+		"",
+		"PHASE 4 — IMPLEMENT AND VERIFY",
+		"- Implement the plan: write the actual code, tests, and docs.",
+		"- Run the tests and any verification; fix failures until everything passes.",
+		"- Verify the goal is actually achieved and working, not just that code was written.",
+		"",
+		REPORT_TAIL,
+	].join("\n");
+}
+
+function buildContinueInstruction(goal: string): string {
+	return [
+		`Continue working toward the goal: ${goal}`,
+		"",
+		"Review the current state and resume the /goal workflow from where you left off, respecting the phase gates:",
+		"- If the design has not been approved yet: present the design and STOP for approval. Do not plan or implement until the user approves.",
+		"- If the design is approved but the plan is not written: follow the writing-plans skill and write the plan.",
+		"- Otherwise: implement and verify, fixing failures until everything passes.",
+		"If you are blocked or need a decision, ask the user.",
+		REPORT_TAIL,
+	].join("\n");
+}
+
+async function runGoal(pi: ExtensionAPI, ctx: ExtensionCommandContext, goal: string): Promise<void> {
+	activeGoal = goal;
+	if (ctx.isIdle()) {
+		await pi.sendUserMessage(buildInstruction(goal));
+	} else {
+		await pi.sendUserMessage(buildInstruction(goal), { deliverAs: "followUp" });
+	}
+	ctx.ui.notify("goal: working until achieved", "info");
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("goal", {
+		description:
+			"Keep the agent working until a goal is achieved: web research, brainstorming design, writing-plans plan, implement and verify",
+		handler: async (args, ctx) => {
+			let goal = (args ?? "").trim();
+			if (!goal) {
+				if (!ctx.hasUI) {
+					console.error("Usage: /goal <goal> - work on it until it is achieved");
+					return;
+				}
+				const typed = await ctx.ui.input("What goal would you like to achieve?", "e.g. add a /goal extension to pi");
+				goal = (typed ?? "").trim();
+				if (!goal) return;
+			}
+			await runGoal(pi, ctx, goal);
+		},
+	});
+
+	// Re-engage the agent after each settle until the goal is achieved.
+	pi.on("agent_settled", async (_event, ctx) => {
+		if (!activeGoal) return;
+
+		// The interactive loop needs the TUI: awaiting a dialog from inside
+		// the settle handler can deadlock RPC clients, and print/JSON modes
+		// can't prompt at all. Stop the loop rather than spin.
+		if (ctx.mode !== "tui") {
+			activeGoal = null;
+			return;
+		}
+
+		const choice = await ctx.ui.select(`Goal: ${shortGoal(activeGoal)}`, [
+			"Continue working toward the goal",
+			"Goal achieved - stop",
+			"Pause - stop checking",
+		]);
+
+		// Esc / cancel → pause, so the loop never runs away.
+		if (!choice || choice === "Pause - stop checking") {
+			activeGoal = null;
+			ctx.ui.notify("goal: paused - take over manually", "info");
+			return;
+		}
+
+		if (choice === "Goal achieved - stop") {
+			activeGoal = null;
+			ctx.ui.notify("goal: marked achieved", "info");
+			return;
+		}
+
+		// "Continue working toward the goal"
+		if (ctx.isIdle()) {
+			await pi.sendUserMessage(buildContinueInstruction(activeGoal));
+		} else {
+			await pi.sendUserMessage(buildContinueInstruction(activeGoal), { deliverAs: "followUp" });
+		}
+		ctx.ui.notify("goal: continuing...", "info");
+	});
+
+	// Reset state on session boundaries so a stale goal never leaks into a
+	// fresh session (or across /reload).
+	pi.on("session_start", () => {
+		activeGoal = null;
+	});
+	pi.on("session_shutdown", () => {
+		activeGoal = null;
+	});
+}

package/agent.bak.20260905-190020/extensions/goal/install.ps1

@@ -0,0 +1,23 @@
+#!/usr/bin/env pwsh
+# Per-extension installer — Windows / PowerShell
+# Installs npm dependencies for this extension. No-op if no package.json.
+$ErrorActionPreference = "Stop"
+$extDir = $PSScriptRoot
+if (-not $extDir) { $extDir = Split-Path -Parent $MyInvocation.MyCommand.Path }
+if (-not (Test-Path "$extDir/package.json")) {
+  Write-Host "  - no package.json — skipping" -ForegroundColor DarkGray
+  exit 0
+}
+if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
+  Write-Host "  x npm not found — install Node.js 22+" -ForegroundColor Red
+  exit 1
+}
+if (Test-Path "$extDir/package-lock.json") {
+  Write-Host "  - npm ci" -ForegroundColor DarkGray
+  npm --prefix $extDir ci --no-audit --no-fund
+} else {
+  Write-Host "  - npm install" -ForegroundColor DarkGray
+  npm --prefix $extDir install --no-audit --no-fund
+}
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+Write-Host "  + done" -ForegroundColor Green

package/agent.bak.20260905-190020/extensions/goal/install.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+# Per-extension installer — macOS / Linux
+# Installs npm dependencies for this extension. No-op if no package.json.
+set -eu
+EXT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ ! -f "$EXT_DIR/package.json" ]; then
+  echo "  · no package.json — skipping"
+  exit 0
+fi
+if ! command -v npm >/dev/null 2>&1; then
+  echo "  ✖ npm not found — install Node.js 22+" >&2
+  exit 1
+fi
+if [ -f "$EXT_DIR/package-lock.json" ]; then
+  echo "  · npm ci"
+  npm --prefix "$EXT_DIR" ci --no-audit --no-fund
+else
+  echo "  · npm install"
+  npm --prefix "$EXT_DIR" install --no-audit --no-fund
+fi
+echo "  ✓ done"

package/agent.bak.20260905-190020/extensions/kiln-update/README.md

@@ -0,0 +1,25 @@
+# kiln-update
+
+Nudges you when your installed kiln is behind GitHub.
+
+- On every session start it compares `~/.pi/agent/version.txt` with
+  `agent/version.txt` on the `main` branch.
+- On mismatch: `Kiln update available (X → Y) — to update kiln to the
+  newest version, run: kiln`
+- Silent when up to date, offline, or timed out (5s).
+
+## Manual check
+
+`/kiln-update` — re-check on demand.
+
+## Releasing a new version
+
+1. Make your changes.
+2. Bump `agent/version.txt` (e.g. `0.2.0` → `0.3.0`).
+3. Push to GitHub. No `npm publish` needed — `kiln` installs from git,
+   and every user gets the nudge on their next session.
+
+## Opt out
+
+`KILN_NO_UPDATE_CHECK=1`. Forks can point elsewhere with
+`KILN_VERSION_URL=https://.../version.txt`.

package/agent.bak.20260905-190020/extensions/kiln-update/index.ts

@@ -0,0 +1,99 @@
+/**
+ * kiln-update — tell the user when their kiln checkout is behind GitHub.
+ *
+ * Compares the installed `~/.pi/agent/version.txt` against the one on the
+ * main branch. On mismatch, shows a nudge on every session start:
+ *
+ *   Kiln update available (0.2.0 → 0.3.0) — to update kiln to the newest
+ *   version, run: kiln
+ *
+ * Failures (offline, timeout, missing file) are silent — this must never
+ * block or annoy. Bump `agent/version.txt` with every user-visible change;
+ * no npm publish is needed since `kiln` installs from GitHub.
+ *
+ * Env overrides:
+ *   KILN_VERSION_URL     Full URL of the remote version.txt (for forks).
+ *   KILN_NO_UPDATE_CHECK=1  Disable the check entirely.
+ *   PI_AGENT_DIR         Local agent dir (default ~/.pi/agent).
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const REPO = "asterxsk/kiln";
+const BRANCH = "main";
+const TIMEOUT_MS = 5000;
+
+function remoteUrl(): string {
+	return (
+		process.env.KILN_VERSION_URL ||
+		`https://raw.githubusercontent.com/${REPO}/${BRANCH}/agent/version.txt`
+	);
+}
+
+function agentDir(): string {
+	return process.env.PI_AGENT_DIR || join(homedir(), ".pi", "agent");
+}
+
+/** Installed version, or "" when unknown. */
+export function localVersion(): string {
+	try {
+		return readFileSync(join(agentDir(), "version.txt"), "utf8").trim();
+	} catch {
+		// Fall through to the checkout-relative fallback.
+	}
+	try {
+		const here = dirname(fileURLToPath(import.meta.url));
+		return readFileSync(join(here, "..", "..", "version.txt"), "utf8").trim();
+	} catch {
+		return "";
+	}
+}
+
+/** GitHub version, or "" when unreachable. Never throws. */
+export async function remoteVersion(): Promise<string> {
+	const ctrl = new AbortController();
+	const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+	try {
+		const res = await fetch(remoteUrl(), { signal: ctrl.signal });
+		if (!res.ok) return "";
+		return (await res.text()).trim();
+	} catch {
+		return "";
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/** The update to report, or null when up to date / unknown / disabled. */
+export async function checkForUpdate(): Promise<{ local: string; remote: string } | null> {
+	if (process.env.KILN_NO_UPDATE_CHECK === "1") return null;
+	const local = localVersion();
+	if (!local) return null;
+	const remote = await remoteVersion();
+	if (!remote || remote === local) return null;
+	return { local, remote };
+}
+
+function updateMessage(local: string, remote: string): string {
+	return `Kiln update available (${local} → ${remote}) — to update kiln to the newest version, run: kiln`;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		const update = await checkForUpdate();
+		if (update) ctx.ui.notify(updateMessage(update.local, update.remote), "warning");
+	});
+
+	pi.registerCommand("kiln-update", {
+		description: "Check whether kiln is behind the GitHub version",
+		handler: async (_args, ctx) => {
+			const update = await checkForUpdate();
+			if (update) ctx.ui.notify(updateMessage(update.local, update.remote), "warning");
+			else ctx.ui.notify("kiln is up to date", "info");
+		},
+	});
+}

package/agent.bak.20260905-190020/extensions/kiln-update/install.ps1

@@ -0,0 +1,23 @@
+#!/usr/bin/env pwsh
+# Per-extension installer — Windows / PowerShell
+# Installs npm dependencies for this extension. No-op if no package.json.
+$ErrorActionPreference = "Stop"
+$extDir = $PSScriptRoot
+if (-not $extDir) { $extDir = Split-Path -Parent $MyInvocation.MyCommand.Path }
+if (-not (Test-Path "$extDir/package.json")) {
+  Write-Host "  - no package.json — skipping" -ForegroundColor DarkGray
+  exit 0
+}
+if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
+  Write-Host "  x npm not found — install Node.js 22+" -ForegroundColor Red
+  exit 1
+}
+if (Test-Path "$extDir/package-lock.json") {
+  Write-Host "  - npm ci" -ForegroundColor DarkGray
+  npm --prefix $extDir ci --no-audit --no-fund
+} else {
+  Write-Host "  - npm install" -ForegroundColor DarkGray
+  npm --prefix $extDir install --no-audit --no-fund
+}
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+Write-Host "  + done" -ForegroundColor Green

package/agent.bak.20260905-190020/extensions/kiln-update/install.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+# Per-extension installer — macOS / Linux
+# Installs npm dependencies for this extension. No-op if no package.json.
+set -eu
+EXT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ ! -f "$EXT_DIR/package.json" ]; then
+  echo "  · no package.json — skipping"
+  exit 0
+fi
+if ! command -v npm >/dev/null 2>&1; then
+  echo "  ✖ npm not found — install Node.js 22+" >&2
+  exit 1
+fi
+if [ -f "$EXT_DIR/package-lock.json" ]; then
+  echo "  · npm ci"
+  npm --prefix "$EXT_DIR" ci --no-audit --no-fund
+else
+  echo "  · npm install"
+  npm --prefix "$EXT_DIR" install --no-audit --no-fund
+fi
+echo "  ✓ done"