@asterxsk/kiln 0.1.0

package/agent/extensions/file-search/src/process.ts

@@ -0,0 +1,146 @@
+import { dirname, join } from "node:path";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import { Effect, FileSystem, Stream } from "effect";
+import { ChildProcess } from "effect/unstable/process";
+import type { CapturedOutput } from "./output.ts";
+
+const STDERR_MAX_BYTES = 64 * 1024;
+
+interface PreviewState {
+  readonly decoder: TextDecoder;
+  preview: string;
+  totalBytes: number;
+  lineBreaks: number;
+  trailingLineBreaks: number;
+  truncated: boolean;
+}
+
+function makePreviewState(): PreviewState {
+  return {
+    decoder: new TextDecoder(),
+    preview: "",
+    totalBytes: 0,
+    lineBreaks: 0,
+    trailingLineBreaks: 0,
+    truncated: false,
+  };
+}
+
+function observeStdout(state: PreviewState, chunk: Uint8Array) {
+  state.totalBytes += chunk.byteLength;
+  for (const byte of chunk) {
+    if (byte === 0x0a) {
+      state.lineBreaks++;
+      state.trailingLineBreaks++;
+    } else {
+      state.trailingLineBreaks = 0;
+    }
+  }
+
+  if (state.truncated) return;
+  state.preview += state.decoder.decode(chunk, { stream: true });
+  const truncation = truncateHead(state.preview, {
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: DEFAULT_MAX_BYTES,
+  });
+  if (truncation.truncated) {
+    state.preview = truncation.content;
+    state.truncated = true;
+  }
+}
+
+function finishStdout(state: PreviewState, fullOutputPath: string) {
+  if (!state.truncated) state.preview += state.decoder.decode();
+  const totalBytes = state.totalBytes - state.trailingLineBreaks;
+  const lineCount =
+    totalBytes === 0 ? 0 : state.lineBreaks - state.trailingLineBreaks + 1;
+  return {
+    preview: state.preview,
+    lineCount,
+    totalBytes,
+    truncated: state.truncated,
+    fullOutputPath: state.truncated ? fullOutputPath : undefined,
+  } satisfies CapturedOutput;
+}
+
+function collectStderr<E, R>(stream: Stream.Stream<Uint8Array, E, R>) {
+  return Stream.runFold(
+    stream,
+    () => Buffer.alloc(0),
+    (captured, chunk) => {
+      if (captured.byteLength >= STDERR_MAX_BYTES) return captured;
+      const remaining = STDERR_MAX_BYTES - captured.byteLength;
+      return Buffer.concat([captured, chunk.subarray(0, remaining)]);
+    },
+  ).pipe(Effect.map((bytes) => bytes.toString("utf8")));
+}
+
+export function executeSearchProcess(options: {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly tempPrefix: string;
+}) {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const directory = yield* fs.makeTempDirectory({
+      prefix: options.tempPrefix,
+    });
+    const fullOutputPath = join(directory, "output.txt");
+    let retainDirectory = false;
+
+    return yield* Effect.gen(function* () {
+      const preview = makePreviewState();
+      const process = yield* ChildProcess.make(options.command, options.args, {
+        cwd: options.cwd,
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const result = yield* Effect.all(
+        {
+          exitCode: process.exitCode,
+          stdout: process.stdout.pipe(
+            Stream.tap((chunk) =>
+              Effect.sync(() => observeStdout(preview, chunk)),
+            ),
+            Stream.run(fs.sink(fullOutputPath)),
+          ),
+          stderr: collectStderr(process.stderr),
+        },
+        { concurrency: "unbounded" },
+      );
+      const output = finishStdout(preview, fullOutputPath);
+      retainDirectory = output.truncated;
+      return {
+        code: Number(result.exitCode),
+        stderr: result.stderr,
+        output,
+      };
+    }).pipe(
+      Effect.ensuring(
+        Effect.suspend(() =>
+          retainDirectory
+            ? Effect.void
+            : fs
+                .remove(directory, { recursive: true, force: true })
+                .pipe(Effect.orDie),
+        ),
+      ),
+    );
+  }).pipe(Effect.scoped);
+}
+
+export function discardCapturedOutput(output: CapturedOutput) {
+  if (!output.fullOutputPath) return Effect.void;
+  const directory = dirname(output.fullOutputPath);
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.remove(directory, { recursive: true, force: true });
+  });
+}

package/agent/extensions/file-search/src/prompt.ts

@@ -0,0 +1,52 @@
+/** Model-facing text for the fd and rg tools. */
+
+export const FD_TOOL_DESCRIPTION =
+  "Find files and directories by name with fd. Respects .gitignore by default. Results are limited to 1000 entries unless a higher limit is given; output is limited to 2000 lines or 50KB, and complete truncated output is saved to a temporary file.";
+
+export const FD_PROMPT_SNIPPET =
+  "Find files and directories by name with fd (fast, gitignore-aware).";
+
+export const FD_PROMPT_GUIDELINES = [
+  "Use fd as the primary tool for discovering files and directories by name, extension, or glob instead of bash with find or ls -R.",
+  "Use rg instead of fd when searching file contents rather than file names.",
+  "Keep using bash for complex multi-step workflows that pipe or post-process file listings.",
+];
+
+export const FD_PARAMETER_DESCRIPTIONS = {
+  pattern:
+    "Regex matched against file names (or a glob when glob is true). Omit to list everything under path.",
+  path: "Directory to search. Defaults to the current working directory.",
+  type: "Only return entries of this type: file, directory, or symlink.",
+  extension: "Only return files with this extension, e.g. 'ts' or 'md'.",
+  glob: "Treat pattern as a glob (e.g. '*.test.ts') instead of a regex.",
+  hidden: "Include hidden files and directories. Defaults to false.",
+  max_depth: "Maximum directory depth to descend (1-64).",
+  limit: "Maximum number of results (1-10000). Defaults to 1000.",
+};
+
+export const RG_TOOL_DESCRIPTION =
+  "Search file contents with ripgrep. Uses smart-case matching, respects .gitignore by default, and returns at most 100 matches per file unless a different limit is given. Output is limited to 2000 lines or 50KB; complete truncated output is saved to a temporary file.";
+
+export const RG_PROMPT_SNIPPET =
+  "Search file contents with ripgrep (fast regex content search).";
+
+export const RG_PROMPT_GUIDELINES = [
+  "Use rg as the primary tool for searching file contents instead of bash with grep.",
+  "Use fd instead of rg when looking for files by name rather than content.",
+  "Set fixed_strings on rg when searching for literal code snippets containing regex metacharacters.",
+  "Keep using bash for complex multi-step workflows that combine searching with other commands.",
+];
+
+export const RG_PARAMETER_DESCRIPTIONS = {
+  pattern: "Regex to search for (literal text when fixed_strings is true).",
+  path: "File or directory to search. Defaults to the current working directory.",
+  glob: "Only search files matching this glob, e.g. '*.ts' or 'src/**'.",
+  file_type:
+    "Only search files of this ripgrep type, e.g. 'ts', 'js', 'py', 'rust'.",
+  case_sensitive:
+    "true forces case-sensitive matching, false forces case-insensitive. Defaults to smart-case.",
+  fixed_strings: "Treat pattern as a literal string instead of a regex.",
+  hidden: "Search hidden files and directories. Defaults to false.",
+  context: "Lines of context to show around each match (0-20).",
+  limit: "Maximum matches per file (1-1000). Defaults to 100.",
+};

package/agent/extensions/file-search/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "plugins": [{ "name": "@effect/language-service" }]
+  },
+  "include": ["index.ts", "src/**/*.ts", "*.spec.ts"]
+}

package/agent/extensions/goal/README.md

@@ -0,0 +1,50 @@
+# goal
+
+Keep the agent working until a goal is achieved.
+
+## Command
+
+| Command | Action |
+|---|---|
+| `/goal <prompt>` | Runs the workflow below, looping until you confirm the goal is achieved |
+| `/goal` | Prompts for the goal interactively, then runs the same workflow |
+
+`/goal` with no argument opens an input dialog; if the dialog is cancelled or
+left empty, nothing runs.
+
+## Workflow
+
+`/goal <prompt>` injects an instruction into the main agent that runs four
+phases in order:
+
+1. **Research** — web-search the goal to ground the design.
+2. **Design** — follow the `brainstorming` skill; present the design for
+   approval, then save the design doc to `docs/superpowers/specs/`.
+3. **Plan** — follow the `writing-plans` skill; save a bite-sized plan to
+   `docs/superpowers/plans/`.
+4. **Implement and verify** — write the code, tests, and docs; run them and
+   fix failures until the goal actually works.
+
+### The loop
+
+After the agent settles, `/goal` asks you what to do next:
+
+- **Continue working toward the goal** — re-engages the agent to keep going,
+  respecting the phase gates (it won't skip design approval).
+- **Goal achieved - stop** — ends the loop.
+- **Pause - stop checking** — ends the loop and leaves you to take over
+  manually.
+
+The loop runs in the interactive TUI (it needs to ask you). In RPC and
+print/JSON modes there is no dialog, so the agent works a single pass and the
+loop ends. The workflow always stops after Phase 2 and waits for you to approve
+the design doc before planning and implementing.
+
+## Files
+
+- `index.ts` — registers the `/goal` command, builds the phase instruction,
+  and re-engages the agent on `agent_settled`
+- `README.md` — this file
+
+Nothing is written into the extension folder; the design and plan land in the
+project's `docs/superpowers/` tree (the skills' default locations).

package/agent/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/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/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"