@asterxsk/kiln 0.2.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 asterxsk
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 asterxsk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -18,20 +18,7 @@ Dotfiles rot. Extensions drift out of sync. A fresh machine means an afternoon o
 One line, then you're done:
 
 ```bash
-# npm / bun (recommended — no Defender flag, no git needed)
 npx @asterxsk/kiln --yes
-# or: npm i -g @asterxsk/kiln && kiln --yes
-# or: bunx @asterxsk/kiln --yes
-```
-
-```bash
-# macOS / Linux / Git Bash (classic)
-curl -fsSL https://raw.githubusercontent.com/asterxsk/kiln/main/agent/install.sh | sh
-```
-
-```powershell
-# Windows PowerShell (5.1 or 7+)
-powershell -NoProfile -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/asterxsk/kiln/main/agent/install.ps1 -UseBasicParsing | iex"
 ```
 
 What the installer does:
@@ -68,7 +55,7 @@ cp kiln/agent/{AGENTS.md,keybindings.json,settings.json} ~/.pi/agent/
 - **Safe installer** — public HTTPS clone, atomic overwrites, narrow backups of only the files it replaces. Your config is never collateral damage.
 - **Forge-first UX** — `theme: forge`, fullscreen TUI, high thinking by default. Built for long sessions.
 - **Secret-free by construction** — `auth.json`, `sessions/`, `trust.json`, `models-store.json`, `bin/`, and `themes/.pi` are `.gitignore`'d. The repo holds config, never credentials.
-- **Cross-platform** — `install.sh` for macOS/Linux/Git Bash, `install.ps1` for PowerShell.
+- **Cross-platform** — one Node installer for macOS, Linux, and Windows.
 
 ### Extensions
 
@@ -101,12 +88,10 @@ Each extension lives at `agent/extensions/{name}/index.ts` and installs independ
     ├── README.md                # pointer → ../README.md
     ├── settings.json            # canonical settings (the installer never overwrites yours)
     ├── keybindings.json         # TUI keybindings
-    ├── install.sh               # macOS/Linux installer
-    ├── install.ps1              # Windows installer
     └── extensions/              # self-contained pi extensions
 ```
 
-Tracked paths only: `agent/extensions`, `agent/settings.json`, `agent/keybindings.json`, `agent/AGENTS.md`, `agent/install.*`, `README.md`. Everything else is local-only.
+Tracked paths only: `agent/extensions`, `agent/settings.json`, `agent/keybindings.json`, `agent/AGENTS.md`, `README.md`. Everything else is local-only.
 
 ---
 
@@ -157,7 +142,7 @@ The house rules, merged into every session: *think before coding*, *simplicity f
 ```bash
 git clone https://github.com/asterxsk/kiln.git
 cd kiln
-./agent/install.sh --target /tmp/pi-test --skip-pi --skip-packages --yes
+node bin/kiln.js --target /tmp/pi-test --skip-pi --skip-packages --yes
 ls /tmp/pi-test/extensions
 ```
 

package/agent/extensions/AGENTS.md

@@ -1,68 +1,68 @@
-# extensions
-
-## Purpose
-Each subfolder is a self-contained pi extension. Pi auto-loads any `extensions/<name>/index.ts` (or `extensions/<name>/package.json` with a `pi.extensions` field).
-
-## Ownership
-- Modular extension system for Pi.
-- Registration, integration, and architecture patterns across all extensions.
-
-## Local Contracts
-- **Independence**: Each extension folder is self-contained — no extension imports from a sibling.
-- **Bridges**: Cross-extension integration uses `globalThis` bridges (e.g., `globalThis.__pi_copilot_usage`, `globalThis.__pi_goal_state`). Bridge keys are prefixed with `__pi_` and unique per extension.
-- **NPM dep safety**: Every extension with npm dependencies must guard all top-level requires/imports in a try/catch. Missing deps log a warning, register with `status: "degraded"` or `status: "disabled"`, and return early rather than crashing Pi.
-- **Graceful degradation**: When an extension's peer is missing, it degrades gracefully. Widgets and commands from other extensions continue working.
-- **Self-contained rendering**: Extensions include their own components (e.g., `CompactToolBox`) rather than importing from a shared extension to avoid tight coupling.
-- **UI Primitives**: Extensions use `ctx.ui` methods (`setHeader`, `setFooter`, `setWidget`, `notify`, `custom`, `select`, `input`) independently.
-
-## Work Guidance
-- **Adding an extension**: 
-  1. Create a new folder `extensions/<name>/`
-  2. Add an `index.ts` with a default export that receives `pi: ExtensionAPI`
-  3. Add an `AGENTS.md` explaining purpose, API surface, and how to remove
-  4. Update the Child DOX Index in this file
-  - If npm deps are needed, add `"pi": { "extensions": ["./index.ts"] }` to `package.json` and run `npm install`.
-  - **All npm imports must be guarded**: wrap `require()` or dynamic `import()` in a try/catch at the top of `index.ts` (or call a lazy init function). If the dep is missing, log a warning, register with `status: "disabled"` (if non-optional) or `status: "degraded"` (if partial functionality), and return early. See `filechanges`, `artifacts`, and `pi-hermes-memory` for reference patterns.
-- **Feature Registration Pattern**: To make the LLM aware of a new extension, add a registration call at the top of its `default export`:
-  ```ts
-  export default function (pi: ExtensionAPI) {
-    (globalThis as any).__pi_extension_features?.push({
-      name: "my-extension",
-      description: "What it does — shown in system prompt",
-      commands: ["/cmd1"],
-      tools: ["tool1"],
-      shortcuts: ["Ctrl+X"],
-    });
-  }
-  ```
-- **Removing an extension**: Delete the folder. Tools/commands/shortcuts will disappear automatically, and peers will degrade gracefully.
-
-## Verification
-- Extensions should load automatically via `index.ts` or `package.json`.
-- Missing peer extensions should not crash the host extension (verify graceful degradation).
-- New extensions should appear in the system prompt under `## Loaded Extensions` if properly registered.
-
-## Child DOX Index
-- `agentzero/` — `/init` command (create or audit AGENTS.md) and global AGENTS.md injection into system prompt
-- `artifacts/` — `create_artifact`, `scaffold_artifact`, `render_artifact`, `list_artifacts`, `delete_artifact`, and `check_artifact` tools + `/artifacts` command: save/browse standalone html/md artifacts, opening html in the default browser (with WSL support) and md in a fullscreen reader (with line numbers, arrow cursor selection, inline commenting, and review submission)
-- `compactui/` — Compact tool rendering, responsive wrapping, assistant time tracking footer, tagged thinking dimming, tool status dot, and auto-hide notifications (3s).
-- `context/` — `/context` overlay: token grid breakdown with per-category color-coded visualization
-- `destructive/` — confirms before running deletion commands (`rm`, `del`, `git rm`, `git clean -f`, …): Allow/Deny prompt, blocks by default with no UI
-- `ferment/` — Structured delivery framework (scope, phases, steps) for long-running agent tasks
-- `9router-provider/` — Local/remote 9router AI gateway provider with auto-discovered models and `/login` integration
-- `filechanges/` — `/filechanges` overlay + accept/decline; tracks file modifications per session and exposes counts for the ui-customization footer
-- `goal/` — `/goal` command — autonomous task orchestrator with pause/resume, turn tracking, history
-- `header/` — Banner header: ASCII art on the left, provider/model/version info panel on the right
-- `instruct/` — Custom system instructions: shell preference, task tracking, no emojis, plan mode guidelines
-- `perms/` — Permissions manager and checklist (`/extensions`), plus plan mode (`/plan`, `plan` tool with strict disabling of `write`/`edit`/`bash` tools)
-- `pi-hermes-memory/` — Persistent memory system with MEMORY.md, SQLite, session search, skill storage, auto-consolidation
-- `powershell/` — `powershell` tool (LLM-callable) with compactui-style rendering
-- `questions/` — `questions` tool (multi-choice TUI with optional custom-answer fallback and ASCII sketches)
-- `spinner/` — Animated star spinner with theme-aware accent color, glow effect, and fun phrases
-- `ui-customization/` — Gradient ASCII header banner + status footer showing provider, model, token I/O, context usage, git branch, worktree, file changes; Alt+C compact shortcut; theme removal
-- `subagents/` — the `subagent`/`subagent_resume`/`subagent_interrupt` tools + `/sub` and `/jobs` commands: spawn isolated pi processes with predefined agent .md files. Runs in the BACKGROUND — returns a job id immediately and pings the agent with a follow-up message when the job finishes. Agents can be `interactive` (pause between phases, resumable) and use `session: fork|lineage` to inherit or trace parent context
-- `tasks/` — `/manage_task` command — background terminal task runner with output capture, wait, cancel; persists across sessions
-- `timers/` — `/schedule` command — one-shot and repeating timers with notifications, auto-delete on fire, and overlay browser
-- `todo/` — `todo` tool + `/todos` command — structured task list with status tracking, categories, reminders, and persistent overlay widget
-- `video-extract/` — `video_extract` tool: YouTube + local video content extraction via Gemini API, ffmpeg, and yt-dlp
-
+# extensions
+
+## Purpose
+Each subfolder is a self-contained pi extension. Pi auto-loads any `extensions/<name>/index.ts` (or `extensions/<name>/package.json` with a `pi.extensions` field).
+
+## Ownership
+- Modular extension system for Pi.
+- Registration, integration, and architecture patterns across all extensions.
+
+## Local Contracts
+- **Independence**: Each extension folder is self-contained — no extension imports from a sibling.
+- **Bridges**: Cross-extension integration uses `globalThis` bridges (e.g., `globalThis.__pi_copilot_usage`, `globalThis.__pi_goal_state`). Bridge keys are prefixed with `__pi_` and unique per extension.
+- **NPM dep safety**: Every extension with npm dependencies must guard all top-level requires/imports in a try/catch. Missing deps log a warning, register with `status: "degraded"` or `status: "disabled"`, and return early rather than crashing Pi.
+- **Graceful degradation**: When an extension's peer is missing, it degrades gracefully. Widgets and commands from other extensions continue working.
+- **Self-contained rendering**: Extensions include their own components (e.g., `CompactToolBox`) rather than importing from a shared extension to avoid tight coupling.
+- **UI Primitives**: Extensions use `ctx.ui` methods (`setHeader`, `setFooter`, `setWidget`, `notify`, `custom`, `select`, `input`) independently.
+
+## Work Guidance
+- **Adding an extension**: 
+  1. Create a new folder `extensions/<name>/`
+  2. Add an `index.ts` with a default export that receives `pi: ExtensionAPI`
+  3. Add an `AGENTS.md` explaining purpose, API surface, and how to remove
+  4. Update the Child DOX Index in this file
+  - If npm deps are needed, add `"pi": { "extensions": ["./index.ts"] }` to `package.json` and run `npm install`.
+  - **All npm imports must be guarded**: wrap `require()` or dynamic `import()` in a try/catch at the top of `index.ts` (or call a lazy init function). If the dep is missing, log a warning, register with `status: "disabled"` (if non-optional) or `status: "degraded"` (if partial functionality), and return early. See `filechanges`, `artifacts`, and `pi-hermes-memory` for reference patterns.
+- **Feature Registration Pattern**: To make the LLM aware of a new extension, add a registration call at the top of its `default export`:
+  ```ts
+  export default function (pi: ExtensionAPI) {
+    (globalThis as any).__pi_extension_features?.push({
+      name: "my-extension",
+      description: "What it does — shown in system prompt",
+      commands: ["/cmd1"],
+      tools: ["tool1"],
+      shortcuts: ["Ctrl+X"],
+    });
+  }
+  ```
+- **Removing an extension**: Delete the folder. Tools/commands/shortcuts will disappear automatically, and peers will degrade gracefully.
+
+## Verification
+- Extensions should load automatically via `index.ts` or `package.json`.
+- Missing peer extensions should not crash the host extension (verify graceful degradation).
+- New extensions should appear in the system prompt under `## Loaded Extensions` if properly registered.
+
+## Child DOX Index
+- `agentzero/` — `/init` command (create or audit AGENTS.md) and global AGENTS.md injection into system prompt
+- `artifacts/` — `create_artifact`, `scaffold_artifact`, `render_artifact`, `list_artifacts`, `delete_artifact`, and `check_artifact` tools + `/artifacts` command: save/browse standalone html/md artifacts, opening html in the default browser (with WSL support) and md in a fullscreen reader (with line numbers, arrow cursor selection, inline commenting, and review submission)
+- `compactui/` — Compact tool rendering, responsive wrapping, assistant time tracking footer, tagged thinking dimming, tool status dot, and auto-hide notifications (3s).
+- `context/` — `/context` overlay: token grid breakdown with per-category color-coded visualization
+- `destructive/` — confirms before running deletion commands (`rm`, `del`, `git rm`, `git clean -f`, …): Allow/Deny prompt, blocks by default with no UI
+- `ferment/` — Structured delivery framework (scope, phases, steps) for long-running agent tasks
+- `9router-provider/` — Local/remote 9router AI gateway provider with auto-discovered models and `/login` integration
+- `filechanges/` — `/filechanges` overlay + accept/decline; tracks file modifications per session and exposes counts for the ui-customization footer
+- `goal/` — `/goal` command — autonomous task orchestrator with pause/resume, turn tracking, history
+- `header/` — Banner header: ASCII art on the left, provider/model/version info panel on the right
+- `instruct/` — Custom system instructions: shell preference, task tracking, no emojis, plan mode guidelines
+- `perms/` — Permissions manager and checklist (`/extensions`), plus plan mode (`/plan`, `plan` tool with strict disabling of `write`/`edit`/`bash` tools)
+- `pi-hermes-memory/` — Persistent memory system with MEMORY.md, SQLite, session search, skill storage, auto-consolidation
+- `powershell/` — `powershell` tool (LLM-callable) with compactui-style rendering
+- `questions/` — `questions` tool (multi-choice TUI with optional custom-answer fallback and ASCII sketches)
+- `spinner/` — Animated star spinner with theme-aware accent color, glow effect, and fun phrases
+- `ui-customization/` — Gradient ASCII header banner + status footer showing provider, model, token I/O, context usage, git branch, worktree, file changes; Alt+C compact shortcut; theme removal
+- `subagents/` — the `subagent`/`subagent_resume`/`subagent_interrupt` tools + `/sub` and `/jobs` commands: spawn isolated pi processes with predefined agent .md files. Runs in the BACKGROUND — returns a job id immediately and pings the agent with a follow-up message when the job finishes. Agents can be `interactive` (pause between phases, resumable) and use `session: fork|lineage` to inherit or trace parent context
+- `tasks/` — `/manage_task` command — background terminal task runner with output capture, wait, cancel; persists across sessions
+- `timers/` — `/schedule` command — one-shot and repeating timers with notifications, auto-delete on fire, and overlay browser
+- `todo/` — `todo` tool + `/todos` command — structured task list with status tracking, categories, reminders, and persistent overlay widget
+- `video-extract/` — `video_extract` tool: YouTube + local video content extraction via Gemini API, ffmpeg, and yt-dlp
+

package/agent/extensions/ask-user/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/ask-user/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/background-terminals/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/background-terminals/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/destructive/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/destructive/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/file-search/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/file-search/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/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`.