decorated-pi 0.5.4 → 0.6.0

package/{extensions → hooks}/rtk.ts

@@ -1,55 +1,20 @@
 /**
- * RTK integration — Rewrite bash commands through system-installed RTK
+ * rtk — rewrite bash commands through system-installed RTK.
  *
- * Uses `rtk rewrite` as a preflight step. If RTK is not installed on PATH,
- * this module stays inactive. When a rewritten RTK command fails, the original
- * command is executed once as a fallback.
+ * Uses `rtk rewrite` as a preflight. If RTK is not installed, this module is inactive.
+ * When a rewritten RTK command fails, the original command is executed once as fallback.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createBashToolDefinition, createLocalBashOperations, isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { createBashToolDefinition, createLocalBashOperations } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { execFileSync, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { Module, Skeleton } from "./skeleton.js";
 
-let rtkBinary: string | null = null;
-
-interface PiShellSettings {
-  shellPath?: string;
-  shellCommandPrefix?: string;
-}
-
-export interface DependencyStatus {
-  module: string;
-  label: string;
-  state: "ok" | "missing" | "n/a";
-  detail?: string;
-}
-
-function readJsonObject(filePath: string): Record<string, unknown> {
-  try {
-    if (!fs.existsSync(filePath)) return {};
-    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
-    return parsed && typeof parsed === "object" ? parsed : {};
-  } catch {
-    return {};
-  }
-}
-
-function loadPiShellSettings(cwd: string): PiShellSettings {
-  const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
-  const globalSettings = readJsonObject(path.join(agentDir, "settings.json"));
-  const projectSettings = readJsonObject(path.join(cwd, ".pi", "settings.json"));
-  const merged = { ...globalSettings, ...projectSettings } as Record<string, unknown>;
-  const result: PiShellSettings = {};
-  if (typeof merged.shellPath === "string" && merged.shellPath.trim()) result.shellPath = merged.shellPath;
-  if (typeof merged.shellCommandPrefix === "string" && merged.shellCommandPrefix.trim()) {
-    result.shellCommandPrefix = merged.shellCommandPrefix;
-  }
-  return result;
-}
+// ─── Locating RTK ─────────────────────────────────────────────────────────
 
 export function findSystemRtk(): string | null {
   try {
@@ -74,27 +39,47 @@ export function buildRtkCommand(raw: string, rtkBinaryPath: string): string {
 }
 
 export function rewriteWithRtk(command: string, rtkPath: string): string | null {
-
-  // NOTE:
-  // Some RTK versions return a non-zero exit code even when `rtk rewrite`
-  // successfully prints a rewritten command to stdout (observed locally with
-  // RTK 0.42.0 returning exit code 3 on success). Because of that, we treat
-  // non-empty stdout as the source of truth and ignore the process exit code
-  // here. Empty stdout still means “no rewrite available”.
-  const result = spawnSync(rtkPath, ["rewrite", command], {
-    encoding: "utf-8",
-    timeout: 2000,
-  });
+  const result = spawnSync(rtkPath, ["rewrite", command], { encoding: "utf-8", timeout: 2000 });
   const raw = (result.stdout ?? "").trim();
   if (!raw) return null;
   return buildRtkCommand(raw, rtkPath);
 }
 
+// ─── Bash tool registration ──────────────────────────────────────────────
+
+interface PiShellSettings {
+  shellPath?: string;
+  shellCommandPrefix?: string;
+}
+
+function readJsonObject(filePath: string): Record<string, unknown> {
+  try {
+    if (!fs.existsSync(filePath)) return {};
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function loadPiShellSettings(cwd: string): PiShellSettings {
+  const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+  const globalSettings = readJsonObject(path.join(agentDir, "settings.json"));
+  const projectSettings = readJsonObject(path.join(cwd, ".pi", "settings.json"));
+  const merged = { ...globalSettings, ...projectSettings } as Record<string, unknown>;
+  const result: PiShellSettings = {};
+  if (typeof merged.shellPath === "string" && merged.shellPath.trim()) result.shellPath = merged.shellPath;
+  if (typeof merged.shellCommandPrefix === "string" && merged.shellCommandPrefix.trim()) {
+    result.shellCommandPrefix = merged.shellCommandPrefix;
+  }
+  return result;
+}
+
 export function appendStatus(text: string, status: string): string {
   return text ? `${text}\n\n${status}` : status;
 }
 
-function formatBashCallWithTag(args: { command?: unknown; timeout?: unknown }, theme: any, showTag: boolean): string {
+export function formatBashCallWithTag(args: { command?: unknown; timeout?: unknown }, theme: any, showTag: boolean): string {
   const command = typeof args?.command === "string" ? args.command : null;
   const timeout = typeof args?.timeout === "number" ? args.timeout : undefined;
   const timeoutSuffix = timeout ? theme.fg("muted", ` (timeout ${timeout}s)`) : "";
@@ -114,56 +99,75 @@ export async function executeOriginalBash(command: string, cwd: string, timeout:
     const output = getOutput() || "(no output)";
     if (result.exitCode !== 0 && result.exitCode !== null) {
       return {
-        content: [{ type: "text" as const, text: appendStatus(output, `Command exited with code ${result.exitCode}`) }],
+        content: [{ type: "text" as const, text: output ? `${output}\n\nCommand exited with code ${result.exitCode}` : `Command exited with code ${result.exitCode}` }],
         details: undefined,
         isError: true,
       };
     }
-    return {
-      content: [{ type: "text" as const, text: output }],
-      details: undefined,
-      isError: false,
-    };
+    return { content: [{ type: "text" as const, text: output }], details: undefined, isError: false };
   } catch (err) {
     const output = getOutput();
     if (err instanceof Error && err.message === "aborted") {
-      return {
-        content: [{ type: "text" as const, text: appendStatus(output, "Command aborted") }],
-        details: undefined,
-        isError: true,
-      };
+      return { content: [{ type: "text" as const, text: output ? `${output}\n\nCommand aborted` : "Command aborted" }], details: undefined, isError: true };
     }
     if (err instanceof Error && err.message.startsWith("timeout:")) {
       const timeoutSecs = err.message.split(":")[1];
-      return {
-        content: [{ type: "text" as const, text: appendStatus(output, `Command timed out after ${timeoutSecs} seconds`) }],
-        details: undefined,
-        isError: true,
-      };
+      return { content: [{ type: "text" as const, text: output ? `${output}\n\nCommand timed out after ${timeoutSecs} seconds` : `Command timed out after ${timeoutSecs} seconds` }], details: undefined, isError: true };
     }
-    return {
-      content: [{ type: "text" as const, text: appendStatus(output, err instanceof Error ? err.message : "Command failed") }],
-      details: undefined,
-      isError: true,
-    };
+    return { content: [{ type: "text" as const, text: output ? `${output}\n\n${err instanceof Error ? err.message : "Command failed"}` : (err instanceof Error ? err.message : "Command failed") }], details: undefined, isError: true };
   }
 }
 
-export function getRtkDependencyStatuses(): DependencyStatus[] {
-  return [{
-    module: "rtk",
-    label: "rtk",
-    state: findSystemRtk() ? "ok" : "missing",
-    detail: "Install RTK so bash rewrite/tagging can activate.",
-  }];
-}
+// ─── Module + setup ──────────────────────────────────────────────────────
 
-export function setupRtkIntegration(pi: ExtensionAPI) {
+let rtkBinary: string | null = null;
+const rewrittenCommands = new Map<string, { originalCommand: string; timeout?: number }>();
+const rewriteabilityCache = new Map<string, boolean>();
+
+export const rtkModule: Module = {
+  name: "rtk",
+  hooks: {
+    tool_call: [
+      (event) => {
+        if (event.toolName !== "bash") return;
+        const command = event.input?.command;
+        if (!command || typeof command !== "string" || !command.trim()) return;
+        const rewritten = rewriteWithRtk(command, rtkBinary!);
+        rewriteabilityCache.set(command, rewritten !== null);
+        if (!rewritten) return;
+        rewrittenCommands.set(event.toolCallId, { originalCommand: command, timeout: event.input?.timeout });
+        event.input.command = rewritten;
+      },
+    ],
+    tool_result: [
+      async (event, ctx) => {
+        if (event.toolName !== "bash") return;
+        const pending = rewrittenCommands.get(event.toolCallId);
+        if (!pending) return;
+        rewrittenCommands.delete(event.toolCallId);
+        if (!event.isError) return;
+        return executeOriginalBash(pending.originalCommand, ctx.cwd, pending.timeout, ctx.signal);
+      },
+    ],
+    session_shutdown: [
+      () => {
+        rewrittenCommands.clear();
+        rewriteabilityCache.clear();
+      },
+    ],
+  },
+};
+
+export function setupRtk(sk: Skeleton, pi: ExtensionAPI): void {
   rtkBinary = findSystemRtk();
+  sk.declareDependency({
+    label: "rtk",
+    check: () => findSystemRtk() !== null,
+    hint: "Install RTK so bash rewrite/tagging can activate.",
+  });
   if (!rtkBinary) return;
 
-  const rewrittenCommands = new Map<string, { originalCommand: string; timeout?: number }>();
-  const rewriteabilityCache = new Map<string, boolean>();
+  // Register a wrapped bash tool that shows [RTK] tag in TUI.
   const shellSettings = loadPiShellSettings(process.cwd());
   const bashTool = createBashToolDefinition(process.cwd(), {
     shellPath: shellSettings.shellPath,
@@ -172,9 +176,7 @@ export function setupRtkIntegration(pi: ExtensionAPI) {
   const baseRenderCall = bashTool.renderCall?.bind(bashTool);
 
   if (baseRenderCall) {
-    bashTool.renderCall = (args, theme, context) => {
-      // Avoid calling baseRenderCall when args.command is not yet available
-      // to prevent flashing "<invalid command>" in TUI
+    bashTool.renderCall = (args: any, theme: any, context: any) => {
       const command = typeof args?.command === "string" ? args.command : "";
       if (!command) {
         const text = context.lastComponent ?? new Text("", 0, 0);
@@ -182,7 +184,6 @@ export function setupRtkIntegration(pi: ExtensionAPI) {
         text.setText(theme.fg("toolTitle", theme.bold(`$ ${placeholder}`)));
         return text;
       }
-
       const component = baseRenderCall(args, theme, context);
       const predicted = command
         ? (rewriteabilityCache.get(command) ?? (() => {
@@ -193,36 +194,12 @@ export function setupRtkIntegration(pi: ExtensionAPI) {
         : false;
       const rewritten = rewrittenCommands.has(context.toolCallId) || predicted;
       if (component instanceof Text) {
-        component.setText(formatBashCallWithTag(args as any, theme, rewritten));
+        component.setText(formatBashCallWithTag(args, theme, rewritten));
       }
       return component;
     };
   }
 
   pi.registerTool(bashTool);
-
-  pi.on("tool_call", (event) => {
-    if (!isToolCallEventType("bash", event)) return;
-    const command = event.input.command;
-    if (!command.trim()) return;
-    const rewritten = rewriteWithRtk(command, rtkBinary!);
-    rewriteabilityCache.set(command, rewritten !== null);
-    if (!rewritten) return;
-    rewrittenCommands.set(event.toolCallId, { originalCommand: command, timeout: event.input.timeout });
-    event.input.command = rewritten;
-  });
-
-  pi.on("tool_result", async (event, ctx) => {
-    if (event.toolName !== "bash") return;
-    const pending = rewrittenCommands.get(event.toolCallId);
-    if (!pending) return;
-    rewrittenCommands.delete(event.toolCallId);
-    if (!event.isError) return;
-    return executeOriginalBash(pending.originalCommand, ctx.cwd, pending.timeout, ctx.signal);
-  });
-
-  pi.on("session_shutdown", () => {
-    rewrittenCommands.clear();
-    rewriteabilityCache.clear();
-  });
+  sk.register(rtkModule);
 }

package/hooks/session-title.ts

@@ -0,0 +1,54 @@
+/**
+ * session-title — auto-derive session name from the first user message.
+ * Skips if user already manually /renamed.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Module } from "./skeleton.js";
+
+export const MAX_SESSION_TITLE_LENGTH = 80;
+
+interface SessionEntryLike {
+  type: string;
+  message?: { role: string; content?: unknown };
+}
+
+function pickFirstUserText(content: unknown): string | undefined {
+  if (typeof content === "string" && content.trim()) return content.trim();
+  if (Array.isArray(content)) {
+    for (const part of content) {
+      if (part && typeof part === "object" && part.type === "text" && typeof part.text === "string" && part.text.trim()) {
+        return part.text.trim();
+      }
+    }
+  }
+  return undefined;
+}
+
+/** Extract a single-line title from the first user message. */
+export function extractFirstMessage(entries: SessionEntryLike[]): string | undefined {
+  for (const entry of entries) {
+    if (entry.type !== "message" || !entry.message || entry.message.role !== "user") continue;
+    const raw = pickFirstUserText(entry.message.content);
+    if (!raw) continue;
+    const nl = raw.indexOf("\n");
+    const oneLine = (nl === -1 ? raw : raw.slice(0, nl)).trim();
+    if (!oneLine) continue;
+    if (oneLine.length <= MAX_SESSION_TITLE_LENGTH) return oneLine;
+    return oneLine.slice(0, MAX_SESSION_TITLE_LENGTH - 1) + "…";
+  }
+  return undefined;
+}
+
+export const sessionTitleModule: Module = {
+  name: "session-title",
+  hooks: {
+    session_start: [
+      (_event, ctx, pi) => {
+        if (ctx.sessionManager.getSessionName()) return;
+        const title = extractFirstMessage(ctx.sessionManager.getBranch());
+        if (title) (pi as any).setSessionName(title);
+      },
+    ],
+  },
+};

package/hooks/skeleton.ts

@@ -0,0 +1,212 @@
+/**
+ * Skeleton — the only place that calls pi.on(...) for hooks.
+ *
+ *   sk.register(module)         → installs module's hook handlers
+ *   sk.declareDependency({...}) → skeleton checks on session_start
+ *   sk.declareGuideline("...") → skeleton injects on before_agent_start
+ *   sk.install(pi)             → call once, after all setup<X> calls
+ *
+ * Handlers receive (event, ctx, pi) so they can call pi.* APIs
+ * (setSessionName, registerTool, appendEntry, etc.).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// ─── Event union ───────────────────────────────────────────────────────────
+
+export type HookEvent =
+  | "session_start"
+  | "session_shutdown"
+  | "session_compact"
+  | "session_before_compact"
+  | "before_agent_start"
+  | "agent_start"
+  | "agent_end"
+  | "input"
+  | "tool_call"
+  | "tool_result";
+
+// ─── Handler modes ─────────────────────────────────────────────────────────
+
+/** Parallel: all handlers run, return values ignored. */
+export type ParallelHandler<E extends HookEvent> = (
+  event: any,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+) => void | Promise<void>;
+
+/** Compose: next handler receives previous return value. */
+export type ComposeHandler<E extends HookEvent> = (
+  event: any,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+) => any | Promise<any>;
+
+export interface Module {
+  readonly name: string;
+  readonly hooks: {
+    session_start?: ParallelHandler<"session_start">[];
+    session_shutdown?: ParallelHandler<"session_shutdown">[];
+    session_compact?: ParallelHandler<"session_compact">[];
+    session_before_compact?: ParallelHandler<"session_before_compact">[];
+    before_agent_start?: ComposeHandler<"before_agent_start">[];
+    agent_start?: ParallelHandler<"agent_start">[];
+    agent_end?: ParallelHandler<"agent_end">[];
+    input?: ParallelHandler<"input">[];
+    tool_call?: ComposeHandler<"tool_call">[];
+    tool_result?: ComposeHandler<"tool_result">[];
+  };
+}
+
+// ─── Declarations ──────────────────────────────────────────────────────────
+
+export interface Dependency {
+  label: string;
+  check: () => boolean;
+  hint?: string;
+}
+
+/** Collected result shape for a module's declared dependency. Modules
+ *  expose a function that returns a list of these so the UI can show
+ *  "what's currently broken" for the user. The skeleton's own
+ *  `session_start` handler also walks declared dependencies, but it
+ *  uses `Dependency.check` directly rather than collecting statuses. */
+export interface DependencyStatus {
+  module: string;
+  label: string;
+  state: "ok" | "missing";
+  detail: string;
+}
+
+// ─── Skeleton ──────────────────────────────────────────────────────────────
+
+const COMPOSE_EVENTS = new Set<HookEvent>([
+  "before_agent_start",
+  "tool_call",
+  "tool_result",
+]);
+
+export interface Skeleton {
+  register(module: Module): void;
+  declareDependency(dep: Dependency): void;
+  install(pi: ExtensionAPI): void;
+  inspect(): Inspection;
+}
+
+export interface Inspection {
+  modules: string[];
+  events: Record<string, Array<{ module: string; order: number }>>;
+  dependencies: Array<{ label: string; hint?: string }>;
+}
+
+export function createSkeleton(): Skeleton {
+  const modules: Module[] = [];
+  const registry = new Map<HookEvent, Array<{ module: string; handler: (event: any, ctx: ExtensionContext, pi: ExtensionAPI) => any }>>();
+  const dependencies: Dependency[] = [];
+
+  function collect(mod: Module) {
+    for (const [event, handlers] of Object.entries(mod.hooks)) {
+      if (!handlers?.length) continue;
+      const list = registry.get(event as HookEvent) ?? [];
+      for (const handler of handlers) {
+        list.push({ module: mod.name, handler: handler as any });
+      }
+      registry.set(event as HookEvent, list);
+    }
+  }
+
+  return {
+    register(mod) {
+      modules.push(mod);
+      collect(mod);
+    },
+
+    declareDependency(dep) {
+      dependencies.push(dep);
+    },
+
+    install(pi) {
+      // Install one pi.on per event, walking registered handlers in order.
+      for (const [event, handlers] of registry) {
+        if (handlers.length === 0) continue;
+        if (COMPOSE_EVENTS.has(event)) {
+          pi.on(event as any, async (event: any, ctx: ExtensionContext) => {
+            let current = event;
+            for (const { handler } of handlers) {
+              const result = await handler(current, ctx, pi);
+              if (result !== undefined) current = result;
+            }
+            return current === event ? undefined : current;
+          });
+        } else {
+          pi.on(event as any, async (event: any, ctx: ExtensionContext) => {
+            for (const { handler } of handlers) await handler(event, ctx, pi);
+          });
+        }
+      }
+
+      // Skeleton-owned: dependency check on session_start.
+      pi.on("session_start", async (_event: any, ctx: ExtensionContext) => {
+        if (!ctx.hasUI) return;
+        const hints: string[] = [];
+        let anyMissing = false;
+        for (const dep of dependencies) {
+          let ok = false;
+          try { ok = dep.check(); } catch { ok = false; }
+          if (!ok) {
+            anyMissing = true;
+            if (dep.hint) hints.push(`  [${dep.label}] ${dep.hint}`);
+          }
+        }
+        if (anyMissing) {
+          ctx.ui.notify(`[decorated-pi] missing dependencies:\n${hints.join("\n")}`, "info");
+        }
+      });
+
+      // Skeleton-owned: system-prompt options sort for cache stability.
+      // Guideline injection is owned by `index.ts`.
+      pi.on("before_agent_start", async (event: any) => {
+        if (event.systemPromptOptions) sortSystemPromptOptions(event.systemPromptOptions);
+        return undefined;
+      });
+    },
+
+    inspect() {
+      const events: Inspection["events"] = {};
+      for (const [event, handlers] of registry) {
+        events[event] = handlers.map((h, i) => ({ module: h.module, order: i }));
+      }
+      return {
+        modules: modules.map((m) => m.name),
+        events,
+        dependencies: dependencies.map((d) => ({ label: d.label, hint: d.hint })),
+      };
+    },
+  };
+}
+
+// ─── System-prompt option sorting ─────────────────────────────────────────
+
+/** Sort all fields in systemPromptOptions alphabetically for stable system prompt. */
+export function sortSystemPromptOptions(opts: {
+  toolSnippets?: Record<string, string>;
+  selectedTools?: string[];
+  promptGuidelines?: string[];
+  skills?: Array<{ name: string; description: string; filePath: string }>;
+}) {
+  const sortedToolNames = Object.keys(opts.toolSnippets ?? {}).sort((a, b) => a.localeCompare(b));
+  const sortedToolSnippets: Record<string, string> = {};
+  for (const name of sortedToolNames) {
+    sortedToolSnippets[name] = opts.toolSnippets![name];
+  }
+  opts.toolSnippets = sortedToolSnippets;
+  if (opts.selectedTools) {
+    opts.selectedTools = sortedToolNames;
+  }
+  if (opts.promptGuidelines) {
+    opts.promptGuidelines = [...opts.promptGuidelines].sort((a, b) => a.localeCompare(b));
+  }
+  if (opts.skills) {
+    opts.skills = [...opts.skills].sort((a, b) => a.name.localeCompare(b.name));
+  }
+}