@asterxsk/kiln 0.1.0

package/agent/extensions/taste/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/extensions/todo/AGENTS.md

@@ -0,0 +1,38 @@
+# Todo Extension
+
+## Purpose
+Provides a persistent todo list with overlay widget, slash command, and LLM-callable tool. Todos are tracked across sessions and displayed in a dedicated UI overlay. Supports i18n via optional `@juicesharp/rpiv-i18n` SDK.
+
+## Ownership
+- `index.ts` — extension entry, event handlers, overlay lifecycle
+- `todo.ts` — todo tool and command registration
+- `todo-overlay.ts` — TUI overlay widget for todo display
+- `state/` — state management, replay, i18n bridge
+
+## Local Contracts
+- Registers tool: `todo` (tool name preserved for session history compatibility)
+- Registers command: `/todos`
+- Widget key: `rpiv-todos` (preserved for compatibility)
+- State replayed from branch on `session_start`, `session_compact`, `session_tree`
+- `replaceState(sessionId, state)` and `replayFromBranch()` from state modules — the store is keyed by `ctx.sessionManager.getSessionId()` so each session (main or in-process subagent) has an independent todo cell; `dropState(sessionId)` on `session_shutdown` prunes ended sessions
+- Handles stale ctx errors during auto-compaction gracefully
+- Batch items support `as` labels (on create) and `refs` (on subsequent items) for creating and referencing tasks in one call
+
+## Work Guidance
+- Todo state is session-branch-based and replayed on session events
+- Overlay constructed lazily at first `session_start` with UI
+- `hideCompletedTasksFromPreviousTurn()` called on `agent_start`
+- i18n strings registered once at module init (soft optional peer dependency)
+- Auto-clear: when no active tasks remain (all completed, deleted, or empty), the state resets to empty automatically at `agent_end` and after replay on `session_start`/`session_compact`/`session_tree`. This prevents stale completed tasks from persisting across turns. The clear is in-memory only — session lifecycle handlers re-apply it after branch replay so the empty state survives compaction and session transitions.
+- Tool execution triggers overlay update via `tool_execution_end` event
+- Overlay indentation: task prefix is `"   └ "` (first line, └ at col 3) and `"     "` (continuation, text at col 5), and the overflow summary line also starts with `"   └"`. This aligns the `└` tree glyph one column after the first letter of the spinner phrase (the spinner occupies 2 columns, e.g. `"✻ "`), so the todo overlay sits under the phrase rather than under the spinner animation character
+
+## Verification
+- Add todo: use `/todos` command or `todo` tool
+- Verify overlay: check widget displays in TUI
+- Test session persistence: `/new` then verify todos still shown
+- Test compaction: trigger compact, verify todos replay correctly
+- Trigger the agent spinner with at least one todo visible; confirm the `└` glyph in each todo line (and the `+N more` summary line) sits ONE COLUMN AFTER the first letter of the spinner phrase — not under the spinner animation character itself
+
+## Child DOX Index
+None

package/agent/extensions/todo/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+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/agent/extensions/todo/config.ts

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Self-contained config utilities — inlined from @juicesharp/rpiv-config so
+// this extension has zero npm dependencies and can be freely edited.
+// ---------------------------------------------------------------------------
+
+export interface GuidanceFields {
+	promptSnippet?: string;
+	promptGuidelines?: string[];
+}
+
+function configPath(name: string, file: string = "config.json"): string {
+	return join(homedir(), ".config", name, file);
+}
+
+function loadJsonConfig<T>(path: string): T {
+	if (!existsSync(path)) return {} as T;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {} as T;
+		return parsed as T;
+	} catch {
+		return {} as T;
+	}
+}
+
+export function validateGuidanceFields(fields: unknown): GuidanceFields {
+	if (!fields || typeof fields !== "object") return {};
+	const g = fields as Record<string, unknown>;
+	const result: GuidanceFields = {};
+	if (typeof g.promptSnippet === "string" && g.promptSnippet.length > 0) {
+		result.promptSnippet = g.promptSnippet;
+	}
+	if (
+		Array.isArray(g.promptGuidelines) &&
+		g.promptGuidelines.length > 0 &&
+		g.promptGuidelines.every((s) => typeof s === "string" && s.length > 0)
+	) {
+		result.promptGuidelines = g.promptGuidelines;
+	}
+	return result;
+}
+
+const CONFIG_PATH = configPath("rpiv-todo");
+
+interface TodoConfig {
+	guidance?: GuidanceFields;
+}
+
+export function loadConfig(): TodoConfig {
+	return loadJsonConfig<TodoConfig>(CONFIG_PATH);
+}

package/agent/extensions/todo/index.ts

@@ -0,0 +1,151 @@
+/**
+ * rpiv-todo — Pi extension. Registers the `todo` tool, `/todos` slash
+ * command, and the persistent TodoOverlay widget.
+ *
+ * TUI chrome strings localize at render time via the i18n bridge. Strings are
+ * registered with rpiv-i18n here, once, at module init — but only when the
+ * SDK is actually installed. If `@juicesharp/rpiv-i18n` is missing (standalone
+ * install of just this package), the dynamic-load shim no-ops and the bridge's
+ * `t(key, fallback)` returns the inline English literal at every call site.
+ * The extension stays online either way.
+ *
+ * Adding a locale: drop `locales/<code>.json` next to en.json (mirroring the
+ * key set). No edit needed here — `registerLocalesFromDir` iterates
+ * `SUPPORTED_LOCALES` from the SDK. See `@juicesharp/rpiv-i18n` README →
+ * "Contributing translations" for the full convention.
+ *
+ * Extracted from rpiv-pi@7525a5d. Tool name "todo" and widget key
+ * "rpiv-todos" preserved verbatim so existing session history replays
+ * correctly after upgrade.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { I18N_NAMESPACE } from "./state/i18n-bridge.js";
+import { replayFromBranch } from "./state/replay.js";
+import { dropState, emptyState, getState, replaceState } from "./state/store.js";
+import { registerTodosCommand, registerTodoTool, TOOL_NAME } from "./todo.js";
+import { TodoOverlay } from "./todo-overlay.js";
+
+type I18nLoader = {
+	registerLocalesFromDir: (namespace: string, packageUrl: string, options?: { label?: string }) => void;
+};
+
+// Dynamic import keeps `@juicesharp/rpiv-i18n` a soft optional peer: when the
+// SDK is installed alongside this package the strings register and
+// `/languages` flips them live; when it isn't, the import rejects here, we
+// no-op, and the bridge's English-fallback shim keeps the extension online.
+//
+// The `/loader` subpath is used instead of the SDK entry so the i18n-ui +
+// pi-tui modules are not pulled into our load graph just to register strings.
+try {
+	const sdk = (await import("@juicesharp/rpiv-i18n/loader")) as I18nLoader;
+	sdk.registerLocalesFromDir(I18N_NAMESPACE, import.meta.url, { label: "rpiv-todo" });
+} catch {
+	// SDK absent — extension still loads with English-only UI.
+}
+
+// pi-core's ExtensionRunner throws this exact phrase from an invalidated ctx
+// proxy after session replacement/reload. Match the stable substring so genuine
+// replay bugs still propagate instead of being silently swallowed.
+function isStaleCtxError(e: unknown): boolean {
+	return /stale after session replacement/.test(String(e));
+}
+
+export default function (pi: ExtensionAPI) {
+	// Todo overlay widget — constructed lazily at the first session_start with UI.
+	let todoOverlay: TodoOverlay | undefined;
+
+	/**
+	 * If no active tasks remain (all completed, deleted, or empty), reset the
+	 * state to empty. Called at agent_end and after replay on session lifecycle
+	 * events so stale completed tasks don't persist across turns.
+	 *
+	 * Note: clearing is in-memory only (no tool result written to the branch).
+	 * Session lifecycle handlers re-check on replay so the empty state survives
+	 * compaction and session transitions. If a future pi-core ordering change
+	 * skips those lifecycle events, completed tasks would reappear.
+	 */
+	function autoClearIfNoActiveTasks(sessionId: string): void {
+		const state = getState(sessionId);
+		if (!state.tasks.some((t) => t.status === "pending" || t.status === "in_progress")) {
+			replaceState(sessionId, emptyState());
+		}
+	}
+
+	registerTodoTool(pi);
+	registerTodosCommand(pi);
+
+	pi.on("session_start", async (_event, ctx) => {
+		const sessionId = ctx.sessionManager.getSessionId();
+		replaceState(sessionId, replayFromBranch(ctx));
+		autoClearIfNoActiveTasks(sessionId);
+		if (ctx.hasUI) {
+			todoOverlay ??= new TodoOverlay();
+			todoOverlay.setSession(sessionId);
+			todoOverlay.setUICtx(ctx.ui);
+			todoOverlay.resetCompletedDisplayState();
+			todoOverlay.update();
+		}
+	});
+
+	pi.on("session_compact", async (_event, ctx) => {
+		// Auto-compaction races session disposal: pi-core invalidates the
+		// extension runner while still emitting session_compact, so `ctx` may be
+		// a dead proxy whose getters throw the stale error. The compacting session
+		// is being discarded — the replacement session's session_start replays
+		// state — so keep current state on a stale ctx. Other errors are real
+		// replay bugs and must propagate.
+		try {
+			replaceState(ctx.sessionManager.getSessionId(), replayFromBranch(ctx));
+		} catch (e) {
+			if (!isStaleCtxError(e)) throw e;
+		}
+		autoClearIfNoActiveTasks(ctx.sessionManager.getSessionId());
+		todoOverlay?.resetCompletedDisplayState();
+		todoOverlay?.update();
+	});
+
+	pi.on("session_tree", async (_event, ctx) => {
+		try {
+			replaceState(ctx.sessionManager.getSessionId(), replayFromBranch(ctx));
+		} catch (e) {
+			if (!isStaleCtxError(e)) throw e;
+		}
+		autoClearIfNoActiveTasks(ctx.sessionManager.getSessionId());
+		todoOverlay?.resetCompletedDisplayState();
+		todoOverlay?.update();
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		try {
+			dropState(ctx.sessionManager.getSessionId());
+		} catch (e) {
+			// A stale ctx proxy after session replacement may throw on any getter;
+			// the cell for a replaced session is abandoned regardless.
+			if (!isStaleCtxError(e)) throw e;
+		}
+		todoOverlay?.dispose();
+		todoOverlay = undefined;
+	});
+
+	// Reads getTodos() at render time; do NOT call replayFromBranch here
+	// (branch is stale — message_end runs after tool_execution_end).
+	pi.on("tool_execution_end", async (event) => {
+		if (event.toolName !== TOOL_NAME || event.isError) return;
+		todoOverlay?.update();
+	});
+
+	pi.on("agent_start", async () => {
+		todoOverlay?.hideCompletedTasksFromPreviousTurn();
+		todoOverlay?.onAgentTurnStart();
+	});
+
+	// Run auto-clear BEFORE onAgentTurnEnd so the overlay's completed-tracking
+	// sets (pendingHide, hiddenCompleted) are still valid for any future logic
+	// in onAgentTurnEnd that references them. The overlay resets its display
+	// state separately at session lifecycle boundaries.
+	pi.on("agent_end", async (_event, ctx) => {
+		autoClearIfNoActiveTasks(ctx.sessionManager.getSessionId());
+		todoOverlay?.onAgentTurnEnd();
+	});
+}

package/agent/extensions/todo/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/extensions/todo/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/extensions/todo/locales/de.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. Unicode box-drawing characters (──) stay untranslated. Note: 'overlay.more' renders as '+5 weitere' which is grammatically loose for plural agreement — accepted for badge brevity.",
+
+  "status.pending": "ausstehend",
+  "status.in_progress": "in Bearbeitung",
+  "status.completed": "erledigt",
+  "status.deleted": "gelöscht",
+
+  "overlay.heading": "Todos",
+  "overlay.more": "weitere",
+
+  "command.no_todos": "Noch keine Todos. Bitte den Agenten, welche hinzuzufügen!",
+  "command.requires_interactive": "/todos erfordert den interaktiven Modus",
+  "command.section.pending": "── Ausstehend ──",
+  "command.section.in_progress": "── In Bearbeitung ──",
+  "command.section.completed": "── Erledigt ──"
+}

package/agent/extensions/todo/locales/en.json

@@ -0,0 +1,15 @@
+{
+  "status.pending": "pending",
+  "status.in_progress": "in progress",
+  "status.completed": "completed",
+  "status.deleted": "deleted",
+
+  "overlay.heading": "Todos",
+  "overlay.more": "more",
+
+  "command.no_todos": "No todos yet. Ask the agent to add some!",
+  "command.requires_interactive": "/todos requires interactive mode",
+  "command.section.pending": "── Pending ──",
+  "command.section.in_progress": "── In Progress ──",
+  "command.section.completed": "── Completed ──"
+}

package/agent/extensions/todo/locales/es.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. Unicode box-drawing characters (──) stay untranslated.",
+
+  "status.pending": "pendientes",
+  "status.in_progress": "en curso",
+  "status.completed": "completadas",
+  "status.deleted": "eliminada",
+
+  "overlay.heading": "Tareas",
+  "overlay.more": "más",
+
+  "command.no_todos": "Sin tareas aún. ¡Pídele al agente que añada algunas!",
+  "command.requires_interactive": "/todos requiere modo interactivo",
+  "command.section.pending": "── Pendientes ──",
+  "command.section.in_progress": "── En curso ──",
+  "command.section.completed": "── Completadas ──"
+}

package/agent/extensions/todo/locales/fr.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. Unicode box-drawing characters (──) stay untranslated.",
+
+  "status.pending": "en attente",
+  "status.in_progress": "en cours",
+  "status.completed": "terminées",
+  "status.deleted": "supprimée",
+
+  "overlay.heading": "Tâches",
+  "overlay.more": "autres",
+
+  "command.no_todos": "Pas encore de tâches. Demandez à l'agent d'en ajouter !",
+  "command.requires_interactive": "/todos nécessite le mode interactif",
+  "command.section.pending": "── En attente ──",
+  "command.section.in_progress": "── En cours ──",
+  "command.section.completed": "── Terminées ──"
+}

package/agent/extensions/todo/locales/pt-BR.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. Unicode box-drawing characters (──) stay untranslated.",
+
+  "status.pending": "pendentes",
+  "status.in_progress": "em andamento",
+  "status.completed": "concluídas",
+  "status.deleted": "excluída",
+
+  "overlay.heading": "Tarefas",
+  "overlay.more": "mais",
+
+  "command.no_todos": "Nenhuma tarefa ainda. Peça ao agente para adicionar algumas!",
+  "command.requires_interactive": "/todos requer modo interativo",
+  "command.section.pending": "── Pendentes ──",
+  "command.section.in_progress": "── Em andamento ──",
+  "command.section.completed": "── Concluídas ──"
+}

package/agent/extensions/todo/locales/pt.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. Unicode box-drawing characters (──) stay untranslated.",
+
+  "status.pending": "pendentes",
+  "status.in_progress": "em curso",
+  "status.completed": "concluídas",
+  "status.deleted": "eliminada",
+
+  "overlay.heading": "Tarefas",
+  "overlay.more": "mais",
+
+  "command.no_todos": "Sem tarefas ainda. Peça ao agente para adicionar algumas!",
+  "command.requires_interactive": "/todos requer modo interativo",
+  "command.section.pending": "── Pendentes ──",
+  "command.section.in_progress": "── Em curso ──",
+  "command.section.completed": "── Concluídas ──"
+}

package/agent/extensions/todo/locales/ru.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Автоперевод. Приветствуется проверка носителем языка через PR. Символы юникода (──) не переводятся.",
+
+  "status.pending": "ожидание",
+  "status.in_progress": "в работе",
+  "status.completed": "выполнено",
+  "status.deleted": "удалена",
+
+  "overlay.heading": "Задачи",
+  "overlay.more": "ещё",
+
+  "command.no_todos": "Задач пока нет. Попросите агента добавить!",
+  "command.requires_interactive": "/todos требует интерактивного режима",
+  "command.section.pending": "── Ожидание ──",
+  "command.section.in_progress": "── В работе ──",
+  "command.section.completed": "── Выполнено ──"
+}

package/agent/extensions/todo/locales/uk.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "Автопереклад. Привітна перевірка носієм мови через PR. Символи юнікоду (──) не перекладаються.",
+
+  "status.pending": "очікування",
+  "status.in_progress": "у роботі",
+  "status.completed": "виконано",
+  "status.deleted": "видалено",
+
+  "overlay.heading": "Завдання",
+  "overlay.more": "ще",
+
+  "command.no_todos": "Завдань поки немає. Попросіть агента додати!",
+  "command.requires_interactive": "/todos потребує інтерактивного режиму",
+  "command.section.pending": "── Очікування ──",
+  "command.section.in_progress": "── У роботі ──",
+  "command.section.completed": "── Виконано ──"
+}

package/agent/extensions/todo/locales/zh.json

@@ -0,0 +1,17 @@
+{
+  "_meta.notes": "中文翻译。欢迎中文母语者通过 PR 审校。",
+
+  "status.pending": "待处理",
+  "status.in_progress": "进行中",
+  "status.completed": "已完成",
+  "status.deleted": "已删除",
+
+  "overlay.heading": "任务清单",
+  "overlay.more": "更多",
+
+  "command.no_todos": "暂无任务。可以让 agent 添加一些！",
+  "command.requires_interactive": "/todos 需要交互模式",
+  "command.section.pending": "── 待处理 ──",
+  "command.section.in_progress": "── 进行中 ──",
+  "command.section.completed": "── 已完成 ──"
+}