@asterxsk/kiln 0.1.0 → 0.3.0

package/agent/extensions/goal/install.ps1

@@ -2,6 +2,10 @@
 # Per-extension installer — Windows / PowerShell
 # Installs npm dependencies for this extension. No-op if no package.json.
 $ErrorActionPreference = "Stop"
+# Drop npm_config_allow_scripts inherited from a parent npm/npx process:
+# npm >=11 rejects it for project installs (EALLOWSCRIPTS). File config still applies.
+Remove-Item Env:\npm_config_allow_scripts -ErrorAction SilentlyContinue
+Remove-Item Env:\NPM_CONFIG_ALLOW_SCRIPTS -ErrorAction SilentlyContinue
 $extDir = $PSScriptRoot
 if (-not $extDir) { $extDir = Split-Path -Parent $MyInvocation.MyCommand.Path }
 if (-not (Test-Path "$extDir/package.json")) {

package/agent/extensions/goal/install.sh

@@ -2,6 +2,9 @@
 # Per-extension installer — macOS / Linux
 # Installs npm dependencies for this extension. No-op if no package.json.
 set -eu
+# Drop npm_config_allow_scripts inherited from a parent npm/npx process:
+# npm >=11 rejects it for project installs (EALLOWSCRIPTS). File config still applies.
+unset npm_config_allow_scripts NPM_CONFIG_ALLOW_SCRIPTS 2>/dev/null || true
 EXT_DIR="$(cd "$(dirname "$0")" && pwd)"
 if [ ! -f "$EXT_DIR/package.json" ]; then
   echo "  · no package.json — skipping"

package/agent/extensions/herdr-agent-state.ts

@@ -0,0 +1,257 @@
+// installed by herdr
+// managed by herdr; reinstalling or updating the integration overwrites this file.
+// add custom hooks/plugins beside this file instead of editing it.
+// HERDR_INTEGRATION_ID=pi
+// HERDR_INTEGRATION_VERSION=8
+// @ts-nocheck
+
+import net from "node:net";
+
+const HERDR_ENV = process.env.HERDR_ENV;
+const socketPath = process.env.HERDR_SOCKET_PATH;
+const socketEndpoint =
+  process.platform === "win32" && socketPath ? `\\\\.\\pipe\\${socketPath}` : socketPath;
+const paneId = process.env.HERDR_PANE_ID;
+const source = "herdr:pi";
+
+function enabled() {
+  return HERDR_ENV === "1" && !!socketPath && !!paneId;
+}
+
+function sendRequestAttempt(request: unknown, timeoutMs: number): Promise<boolean> {
+  if (!enabled()) {
+    return Promise.resolve(true);
+  }
+
+  return new Promise((resolve) => {
+    let done = false;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    const finish = (delivered: boolean) => {
+      if (done) return;
+      done = true;
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      socket.destroy();
+      resolve(delivered);
+    };
+
+    const socket = net.createConnection(socketEndpoint!);
+    socket.on("error", () => finish(false));
+    socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on("data", () => finish(true));
+    socket.on("end", () => finish(false));
+    timeout = setTimeout(() => finish(false), timeoutMs);
+    timeout.unref?.();
+  });
+}
+
+async function sendRequest(request: unknown): Promise<void> {
+  if (await sendRequestAttempt(request, 500)) {
+    return;
+  }
+  await sendRequestAttempt(request, 1500);
+}
+
+type AgentState = "working" | "blocked" | "idle";
+
+type QueuedState = {
+  state: AgentState;
+  message?: string;
+  seq: number;
+};
+
+let reportSeq = Date.now() * 1000;
+let currentAgentSessionId: string | undefined;
+let currentAgentSessionPath: string | undefined;
+
+function nextReportSeq(): number {
+  reportSeq += 1;
+  return reportSeq;
+}
+
+function updateSessionRef(ctx: any): void {
+  try {
+    const file = ctx?.sessionManager?.getSessionFile?.();
+    currentAgentSessionPath =
+      typeof file === "string" && file.startsWith("/") ? file : undefined;
+  } catch {
+    currentAgentSessionPath = undefined;
+  }
+
+  try {
+    const id = ctx?.sessionManager?.getSessionId?.();
+    currentAgentSessionId = typeof id === "string" && id.length > 0 ? id : undefined;
+  } catch {
+    currentAgentSessionId = undefined;
+  }
+}
+
+function withSessionRef(params: Record<string, unknown>): Record<string, unknown> {
+  if (currentAgentSessionPath) {
+    return { ...params, agent_session_path: currentAgentSessionPath };
+  }
+  if (currentAgentSessionId) {
+    return { ...params, agent_session_id: currentAgentSessionId };
+  }
+  return params;
+}
+
+function currentSessionRef(): Record<string, unknown> | undefined {
+  if (currentAgentSessionPath) {
+    return { agent_session_path: currentAgentSessionPath };
+  }
+  if (currentAgentSessionId) {
+    return { agent_session_id: currentAgentSessionId };
+  }
+  return undefined;
+}
+
+function reportSession(sessionStartSource?: string): Promise<void> {
+  const sessionRef = currentSessionRef();
+  if (!sessionRef) {
+    return Promise.resolve();
+  }
+
+  return sendRequest({
+    id: `${source}:session:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+    method: "pane.report_agent_session",
+    params: {
+      pane_id: paneId,
+      source,
+      agent: "pi",
+      seq: nextReportSeq(),
+      session_start_source: sessionStartSource,
+      ...sessionRef,
+    },
+  });
+}
+
+function sendState(state: AgentState, message?: string, seq = nextReportSeq()): Promise<void> {
+  return sendRequest({
+    id: `${source}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+    method: "pane.report_agent",
+    params: withSessionRef({
+      pane_id: paneId,
+      source,
+      agent: "pi",
+      state,
+      message,
+      seq,
+    }),
+  });
+}
+
+let sendInFlight = false;
+let queuedState: QueuedState | undefined;
+
+function queueState(state: AgentState, message?: string): void {
+  queuedState = { state, message, seq: nextReportSeq() };
+  if (!sendInFlight) {
+    void drainStateQueue();
+  }
+}
+
+async function drainStateQueue(): Promise<void> {
+  if (sendInFlight) {
+    return;
+  }
+
+  sendInFlight = true;
+  try {
+    while (queuedState) {
+      const next = queuedState;
+      queuedState = undefined;
+      await sendState(next.state, next.message, next.seq);
+    }
+  } finally {
+    sendInFlight = false;
+    if (queuedState) {
+      void drainStateQueue();
+    }
+  }
+}
+
+export default function (pi) {
+  if (!enabled()) {
+    return;
+  }
+
+  let agentActive = false;
+  let blockedCount = 0;
+  let blockedMessage: string | undefined;
+  let lastState: AgentState | undefined;
+  let lastMessage: string | undefined;
+  let rootSession = false;
+
+  function desiredState() {
+    if (blockedCount > 0) {
+      return { state: "blocked" as const, message: blockedMessage };
+    }
+    if (agentActive) {
+      return { state: "working" as const, message: undefined };
+    }
+    return { state: "idle" as const, message: undefined };
+  }
+
+  function publishState(force = false) {
+    const next = desiredState();
+    if (!force && next.state === lastState && next.message === lastMessage) {
+      return;
+    }
+    lastState = next.state;
+    lastMessage = next.message;
+    queueState(next.state, next.message);
+  }
+
+  pi.events.on("herdr:blocked", (data) => {
+    if (!rootSession) {
+      return;
+    }
+    if (!data?.active) {
+      blockedCount = Math.max(0, blockedCount - 1);
+      if (blockedCount === 0) {
+        blockedMessage = undefined;
+      }
+      publishState();
+      return;
+    }
+
+    blockedCount += 1;
+    blockedMessage = data.label;
+    publishState();
+  });
+
+  pi.on("session_start", async (event, ctx) => {
+    // TUI only: RPC/JSON/print modes are headless (no PTY herdr can display),
+    // and RPC still reports hasUI=true, so mode is the reliable gate.
+    if (ctx?.mode !== "tui") {
+      return;
+    }
+    rootSession = true;
+    updateSessionRef(ctx);
+    await reportSession(event?.reason);
+    // A reload can replace this extension mid-run without emitting another agent_start.
+    agentActive = ctx?.isIdle?.() === false;
+    publishState(true);
+  });
+
+  pi.on("agent_start", (_event, ctx) => {
+    if (!rootSession) {
+      return;
+    }
+    updateSessionRef(ctx);
+    void reportSession();
+    agentActive = true;
+    publishState();
+  });
+
+  pi.on("agent_settled", (_event, ctx) => {
+    if (!rootSession || ctx?.isIdle?.() !== true) {
+      return;
+    }
+
+    agentActive = false;
+    publishState();
+  });
+}

package/agent/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/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/extensions/kiln-update/install.ps1

@@ -0,0 +1,27 @@
+#!/usr/bin/env pwsh
+# Per-extension installer — Windows / PowerShell
+# Installs npm dependencies for this extension. No-op if no package.json.
+$ErrorActionPreference = "Stop"
+# Drop npm_config_allow_scripts inherited from a parent npm/npx process:
+# npm >=11 rejects it for project installs (EALLOWSCRIPTS). File config still applies.
+Remove-Item Env:\npm_config_allow_scripts -ErrorAction SilentlyContinue
+Remove-Item Env:\NPM_CONFIG_ALLOW_SCRIPTS -ErrorAction SilentlyContinue
+$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/extensions/kiln-update/install.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+# Per-extension installer — macOS / Linux
+# Installs npm dependencies for this extension. No-op if no package.json.
+set -eu
+# Drop npm_config_allow_scripts inherited from a parent npm/npx process:
+# npm >=11 rejects it for project installs (EALLOWSCRIPTS). File config still applies.
+unset npm_config_allow_scripts NPM_CONFIG_ALLOW_SCRIPTS 2>/dev/null || true
+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"