@narumitw/pi-subagents 3.2.0 → 3.3.0

package/src/settings.ts

@@ -0,0 +1,142 @@
+import fs from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+export interface SubagentSettings {
+  showWidget: boolean;
+  showJobId: boolean;
+  showTools: boolean;
+  showTiming: boolean;
+}
+
+export const DEFAULT_SUBAGENT_SETTINGS: Readonly<SubagentSettings> = Object.freeze({
+  showWidget: true,
+  showJobId: true,
+  showTools: true,
+  showTiming: true,
+});
+
+const SETTINGS_KEYS = Object.keys(DEFAULT_SUBAGENT_SETTINGS) as (keyof SubagentSettings)[];
+
+type SettingsDocument = {
+  document?: Record<string, unknown>;
+  diagnostics: string[];
+};
+
+export function subagentSettingsPath(): string {
+  return join(getAgentDir(), "pi-subagents.json");
+}
+
+/** User-only settings with in-process ordering; this does not lock other Pi processes. */
+export class SubagentSettingsStore {
+  private effective: SubagentSettings = { ...DEFAULT_SUBAGENT_SETTINGS };
+  private tail: Promise<void> = Promise.resolve();
+
+  constructor(readonly userPath: string) {}
+
+  get settings(): SubagentSettings {
+    return { ...this.effective };
+  }
+
+  load(): Promise<{ settings: SubagentSettings; diagnostics: string[] }> {
+    return this.enqueue(async () => {
+      const loaded = await readDocument(this.userPath);
+      const settings = normalizeSettings(loaded.document ?? {}, loaded.diagnostics);
+      this.effective = settings;
+      return { settings: this.settings, diagnostics: loaded.diagnostics };
+    }).catch((error: unknown) => ({
+      settings: this.settings,
+      diagnostics: [readDiagnostic(this.userPath, error)],
+    }));
+  }
+
+  save(key: keyof SubagentSettings, value: boolean, signal: AbortSignal): Promise<SubagentSettings> {
+    return this.enqueue(async () => {
+      signal.throwIfAborted();
+      if (!SETTINGS_KEYS.includes(key) || typeof value !== "boolean") {
+        throw new Error("Invalid subagent settings update");
+      }
+      const loaded = await readDocument(this.userPath);
+      signal.throwIfAborted();
+      if (!loaded.document) {
+        throw new Error(`Cannot save subagent settings: ${loaded.diagnostics.join("; ")}`);
+      }
+      // Read again for each save and patch only the requested key, including after a failed save.
+      const document = { ...loaded.document, [key]: value };
+      const settings = normalizeSettings(document, []);
+      const parent = dirname(this.userPath);
+      await fs.mkdir(parent, { recursive: true });
+      signal.throwIfAborted();
+      const temporary = await fs.mkdtemp(join(parent, ".pi-subagents-"));
+      try {
+        signal.throwIfAborted();
+        const staged = join(temporary, "settings.json");
+        await fs.writeFile(staged, `${JSON.stringify(document, null, 2)}\n`, { flag: "wx", signal });
+        signal.throwIfAborted();
+        await fs.rename(staged, this.userPath);
+        // Rename is the commit point. Cancellation or cleanup must not turn a commit into a failure.
+        this.effective = settings;
+        return this.settings;
+      } finally {
+        await fs.rm(temporary, { recursive: true, force: true }).catch(() => {});
+      }
+    });
+  }
+
+  flush(): Promise<void> {
+    return this.tail;
+  }
+
+  private enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    const previous = this.tail;
+    // Register immediately so other stores and Pi file operations retain request order too.
+    const result = withFileMutationQueue(this.userPath, async () => {
+      await previous;
+      return operation();
+    });
+    this.tail = result.then(
+      () => {},
+      () => {},
+    );
+    return result;
+  }
+}
+
+async function readDocument(path: string): Promise<SettingsDocument> {
+  let text: string;
+  try {
+    text = await fs.readFile(path, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return { document: {}, diagnostics: [] };
+    }
+    return { diagnostics: [readDiagnostic(path, error)] };
+  }
+  let document: unknown;
+  try {
+    document = JSON.parse(text);
+  } catch {
+    return { diagnostics: [`Cannot load subagent settings at ${path}: invalid JSON`] };
+  }
+  if (typeof document !== "object" || document === null || Array.isArray(document)) {
+    return { diagnostics: [`Cannot load subagent settings at ${path}: expected a JSON object`] };
+  }
+  return { document: document as Record<string, unknown>, diagnostics: [] };
+}
+
+function normalizeSettings(document: Record<string, unknown>, diagnostics: string[]): SubagentSettings {
+  const settings = { ...DEFAULT_SUBAGENT_SETTINGS };
+  for (const key of SETTINGS_KEYS) {
+    if (!Object.hasOwn(document, key)) continue;
+    if (typeof document[key] === "boolean") {
+      settings[key] = document[key];
+    } else {
+      diagnostics.push(`Ignored invalid subagent setting ${key}: expected a boolean`);
+    }
+  }
+  return settings;
+}
+
+function readDiagnostic(path: string, error: unknown): string {
+  return `Cannot load subagent settings at ${path}: ${error instanceof Error ? error.message : String(error)}`;
+}

package/src/subagents.ts

@@ -1,30 +1,158 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { registerCompletionRenderer } from "./completion-renderer.js";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sanitizeSubagentDisplayText } from "./display-text.js";
+import { registerMessageRenderers } from "./message-renderers.js";
+import {
+  DEFAULT_SUBAGENT_SETTINGS,
+  type SubagentSettings,
+  SubagentSettingsStore,
+  subagentSettingsPath,
+} from "./settings.js";
 import { registerSubagentTools, type SubagentToolsDependencies } from "./tools.js";
 import { createSubagentWidgetController } from "./widget.js";
 
-export type SubagentsDependencies = SubagentToolsDependencies;
+export interface SubagentsDependencies extends SubagentToolsDependencies {
+  settingsStore?: Pick<SubagentSettingsStore, "userPath" | "load" | "save" | "flush">;
+}
 
 export default function subagents(pi: ExtensionAPI, dependencies: SubagentsDependencies = {}): void {
-  registerCompletionRenderer(pi);
+  registerMessageRenderers(pi);
   const tools = registerSubagentTools(pi, dependencies);
   const widget = createSubagentWidgetController(tools.runtime);
-  let activeSession: ExtensionContext["sessionManager"] | undefined;
+  const store = dependencies.settingsStore ?? new SubagentSettingsStore(subagentSettingsPath());
+  let activeContext: ExtensionContext | undefined;
   let sessionGeneration = 0;
+  let owner = new AbortController();
+  let ready = false;
+  let menuOpen = false;
+  let settings: SubagentSettings = { ...DEFAULT_SUBAGENT_SETTINGS };
+  const menuTasks = new Set<Promise<void>>();
+  const ownsSession = (ctx: ExtensionContext) => ctx.sessionManager === activeContext?.sessionManager;
+
+  const openSettings = async (
+    ctx: ExtensionCommandContext,
+    signal: AbortSignal,
+    isCurrent: () => boolean,
+  ): Promise<"back" | "close" | "stale"> => {
+    if (signal.aborted || !isCurrent()) return "stale";
+    if (ctx.mode !== "tui") {
+      ctx.ui.notify(sanitizeSubagentDisplayText(`Edit user settings: ${store.userPath}. Then run /reload.`), "info");
+      return "back";
+    }
+    const { showSubagentSettings } = await import("./settings-ui.js");
+    if (signal.aborted || !isCurrent()) return "stale";
+    return showSubagentSettings(ctx, {
+      signal,
+      isCurrent,
+      get: () => ({ ...settings }),
+      save: (key, value, actionSignal) => {
+        actionSignal.throwIfAborted();
+        if (!isCurrent()) throw new Error("The subagents session changed.");
+        return store.save(key, value, actionSignal);
+      },
+      apply: (next) => {
+        if (!isCurrent()) return;
+        settings = { ...next };
+        widget.update(ctx, settings);
+      },
+    });
+  };
+
+  pi.registerCommand("subagents", {
+    description: "Manage subagent jobs and widget settings",
+    getArgumentCompletions: (prefix) =>
+      "settings".startsWith(prefix)
+        ? [{ value: "settings", label: "settings", description: "Configure the subagent widget" }]
+        : null,
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI || (ctx.mode !== "tui" && ctx.mode !== "rpc")) {
+        throw new Error("/subagents requires TUI or RPC mode.");
+      }
+      const route = args.trim();
+      if (route !== "" && route !== "settings") {
+        ctx.ui.notify("Usage: /subagents | /subagents settings", "warning");
+        return;
+      }
+      if (!ownsSession(ctx) || !ready || menuOpen) {
+        ctx.ui.notify("Subagent controls are loading, unavailable, or already open.", "warning");
+        return;
+      }
+      menuOpen = true;
+      const generation = sessionGeneration;
+      const signal = owner.signal;
+      const isCurrent = () => generation === sessionGeneration && ownsSession(ctx) && !signal.aborted;
+      const task = (async () => {
+        if (route === "settings") {
+          await openSettings(ctx, signal, isCurrent);
+          return;
+        }
+        const { showSubagentsMenu } = await import("./menu.js");
+        if (!isCurrent()) return;
+        await showSubagentsMenu(ctx, {
+          signal,
+          isCurrent,
+          getState: () => ({
+            settings: { ...settings },
+            settingsPath: store.userPath,
+            ...tools.runtime.inspectJobs(),
+          }),
+          cancelJob: async (jobId, actionSignal) => {
+            actionSignal.throwIfAborted();
+            if (!isCurrent()) throw new Error("The subagents session changed.");
+            await tools.runtime.cancel(jobId);
+          },
+          showSettings: (actionSignal) => openSettings(ctx, actionSignal, isCurrent),
+        });
+      })();
+      menuTasks.add(task);
+      try {
+        await task;
+      } catch (error) {
+        if (isCurrent()) {
+          ctx.ui.notify(sanitizeSubagentDisplayText(error instanceof Error ? error.message : String(error)), "error");
+        }
+      } finally {
+        menuTasks.delete(task);
+        if (isCurrent()) menuOpen = false;
+      }
+    },
+  });
 
   pi.on("session_start", async (_event, ctx) => {
-    activeSession = ctx.sessionManager;
+    owner.abort();
+    if (activeContext) widget.shutdown(activeContext);
+    owner = new AbortController();
+    activeContext = ctx;
+    ready = false;
+    menuOpen = false;
     const generation = ++sessionGeneration;
+    const isCurrent = () => generation === sessionGeneration && ownsSession(ctx) && !owner.signal.aborted;
+    // Stop old children and broker delivery before waiting for slow UI storage work.
     await tools.startSession();
-    if (generation !== sessionGeneration) return;
-    widget.start(ctx);
+    if (!isCurrent()) return;
+    await Promise.allSettled([...menuTasks]);
+    if (!isCurrent()) return;
+    const loaded = await store.load();
+    if (!isCurrent()) return;
+    settings = { ...loaded.settings };
+    ready = true;
+    widget.start(ctx, settings);
+    if (loaded.diagnostics.length > 0) {
+      const message = sanitizeSubagentDisplayText(`Subagent settings: ${loaded.diagnostics.join(" ")}`);
+      if (ctx.hasUI) ctx.ui.notify(message, "warning");
+      else throw new Error(message);
+    }
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {
-    if (ctx.sessionManager !== activeSession) return;
+    if (!ownsSession(ctx)) return;
     sessionGeneration++;
-    activeSession = undefined;
+    owner.abort();
+    ready = false;
+    menuOpen = false;
+    activeContext = undefined;
     widget.shutdown(ctx);
-    await tools.shutdown();
+    const results = await Promise.allSettled([tools.shutdown(), ...menuTasks, store.flush()]);
+    const failed = results.find((result) => result.status === "rejected");
+    if (failed?.status === "rejected") throw failed.reason;
   });
 }

package/src/tools.ts

@@ -11,6 +11,7 @@ import {
   sanitizeTerminalText,
   validateMessage,
 } from "./message-broker.js";
+import { BROKER_MESSAGE_TYPE } from "./message-renderers.js";
 import { modelVisibleJson, requireBoundedModelText } from "./model-output.js";
 import { assertChildCommandCapacity } from "./process.js";
 import {
@@ -32,7 +33,6 @@ import {
 
 const MAX_TASK_BYTES = 50 * 1024;
 const MAX_TOOLS = MAX_SELECTED_TOOLS;
-const MESSAGE_TYPE = "pi-subagents-message";
 const CHILD_CORE_TOOL_SET = new Set<string>(CHILD_CORE_TOOL_NAMES);
 const THINKING_LEVEL_SET = new Set<string>(SUBAGENT_THINKING_LEVELS);
 
@@ -347,7 +347,7 @@ function deliverMessage(pi: ExtensionAPI, message: BrokerInboundMessage): void {
   );
   pi.sendMessage(
     {
-      customType: MESSAGE_TYPE,
+      customType: BROKER_MESSAGE_TYPE,
       content,
       display: true,
       details: {

package/src/widget.ts

@@ -1,15 +1,19 @@
 import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth } from "@earendil-works/pi-tui";
-import { sanitizeTerminalText } from "./message-broker.js";
+import { stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { EditorStatusWidget } from "@narumitw/pi-tui-kit/editor-status-widget";
+import { sanitizeSubagentDisplayText as sanitizeLabel } from "./display-text.js";
 import type { ActiveJobDisplay, SubagentRuntime } from "./runtime.js";
+import { DEFAULT_SUBAGENT_SETTINGS, type SubagentSettings } from "./settings.js";
 
 export const SUBAGENT_WIDGET_KEY = "subagents";
 export const SUBAGENT_WIDGET_REFRESH_INTERVAL_MS = 1_000;
 
 const WIDGET_OPTIONS = { placement: "aboveEditor" } as const;
+const TASK_PREVIEW_WIDTH = 40;
 
 export interface SubagentWidgetController {
-  start(ctx: ExtensionContext): void;
+  start(ctx: ExtensionContext, settings?: SubagentSettings): void;
+  update(ctx: ExtensionContext, settings: SubagentSettings): void;
   shutdown(ctx: ExtensionContext): void;
 }
 
@@ -18,6 +22,8 @@ export function createSubagentWidgetController(runtime: SubagentRuntime): Subage
   let refreshTimer: ReturnType<typeof setInterval> | undefined;
   let unsubscribeJobs: (() => void) | undefined;
   let publishedValue: string | undefined;
+  let settings = { ...DEFAULT_SUBAGENT_SETTINGS };
+  let clearWidget: (() => void) | undefined;
 
   const ownsSession = (ctx: ExtensionContext): boolean => ctx.sessionManager === activeSession;
 
@@ -30,19 +36,17 @@ export function createSubagentWidgetController(runtime: SubagentRuntime): Subage
 
   const publish = (ctx: ExtensionContext): void => {
     if (ctx.mode !== "tui" || !ownsSession(ctx)) return;
-    const jobs = runtime.activeJobsForDisplay();
-    const value = widgetValue(jobs);
+    const jobs = settings.showWidget ? runtime.activeJobsForDisplay() : [];
+    const value = `${JSON.stringify(settings)}\n${widgetValue(jobs)}`;
     if (value === publishedValue) return;
     if (jobs.length === 0) {
       ctx.ui.setWidget(SUBAGENT_WIDGET_KEY, undefined);
     } else {
       const snapshot = jobs.map(cloneDisplayJob);
+      const preferences = { ...settings };
       ctx.ui.setWidget(
         SUBAGENT_WIDGET_KEY,
-        (_tui, theme) => ({
-          render: (width) => renderSubagentWidget(snapshot, theme, width),
-          invalidate: () => {},
-        }),
+        (_tui, theme) => createSubagentWidget(snapshot, theme, preferences),
         WIDGET_OPTIONS,
       );
     }
@@ -50,53 +54,89 @@ export function createSubagentWidgetController(runtime: SubagentRuntime): Subage
   };
 
   return {
-    start(ctx) {
+    start(ctx, preferences = DEFAULT_SUBAGENT_SETTINGS) {
       stop();
+      clearWidget?.();
+      clearWidget = undefined;
+      settings = { ...preferences };
       activeSession = ctx.sessionManager;
       publishedValue = undefined;
       if (ctx.mode !== "tui") return;
-      ctx.ui.setWidget(SUBAGENT_WIDGET_KEY, undefined);
+      clearWidget = () => ctx.ui.setWidget(SUBAGENT_WIDGET_KEY, undefined);
+      clearWidget();
       unsubscribeJobs = runtime.subscribeJobs(() => publish(ctx));
       refreshTimer = setInterval(() => publish(ctx), SUBAGENT_WIDGET_REFRESH_INTERVAL_MS);
       refreshTimer.unref();
       publish(ctx);
     },
+    update(ctx, preferences) {
+      if (!ownsSession(ctx)) return;
+      settings = { ...preferences };
+      publish(ctx);
+    },
     shutdown(ctx) {
       if (!ownsSession(ctx)) return;
       stop();
-      if (ctx.mode === "tui") ctx.ui.setWidget(SUBAGENT_WIDGET_KEY, undefined);
+      clearWidget?.();
+      clearWidget = undefined;
       publishedValue = undefined;
       activeSession = undefined;
     },
   };
 }
 
-export function renderSubagentWidget(jobs: readonly ActiveJobDisplay[], theme: Theme, width: number): string[] {
-  const renderWidth = Math.max(0, width);
-  const lines = [
-    theme.fg("borderMuted", "─".repeat(renderWidth)),
-    theme.fg("muted", `Subagents · ${jobs.length} active`),
-    ...jobs.map((job) => renderJob(job, theme)),
-  ];
-  return lines.map((line) => truncateToWidth(line, renderWidth, ""));
+export function renderSubagentWidget(
+  jobs: readonly ActiveJobDisplay[],
+  theme: Theme,
+  width: number,
+  settings: SubagentSettings = DEFAULT_SUBAGENT_SETTINGS,
+): string[] {
+  if (!settings.showWidget) return [];
+  return createSubagentWidget(jobs, theme, settings).render(width);
 }
 
-function renderJob(job: ActiveJobDisplay, theme: Theme): string {
+function createSubagentWidget(
+  jobs: readonly ActiveJobDisplay[],
+  theme: Theme,
+  settings: SubagentSettings,
+): EditorStatusWidget {
+  return new EditorStatusWidget({
+    theme,
+    renderBody: () => [
+      theme.fg("muted", `Subagents · ${jobs.length} active`),
+      ...jobs.map((job) => renderJob(job, theme, settings)),
+    ],
+  });
+}
+
+function renderJob(job: ActiveJobDisplay, theme: Theme, settings: SubagentSettings): string {
   const running = job.state === "running";
   const symbol = theme.fg(running ? "accent" : "dim", running ? "▶ " : "○ ");
   const state = theme.fg(running ? "accent" : "muted", job.state);
   const jobId = sanitizeLabel(job.jobId);
+  const taskText = sanitizeLabel(job.task);
+  // Pi's truncation adds ANSI resets; remove them before applying the callback theme.
+  const task = stripTerminalSequences(truncateToWidth(taskText, TASK_PREVIEW_WIDTH, "…"));
+  const labels = [
+    ...(settings.showJobId ? [theme.fg("text", jobId)] : []),
+    ...(visibleWidth(task) > 0 ? [theme.fg("text", task)] : []),
+    state,
+  ];
   const tools = job.tools.length > 0 ? job.tools.map(sanitizeLabel).join(", ") : "none";
   const timeout = job.timeout === undefined ? "no timeout" : formatSeconds(job.timeout);
-  const detail = ` · ${formatSeconds(Math.floor(job.elapsedMs / 1_000))} / ${timeout} · tools: ${tools}`;
-  return `${symbol}${theme.fg("text", jobId)} · ${state}${theme.fg("muted", detail)}`;
+  const details = [
+    ...(settings.showTiming ? [`${formatSeconds(Math.floor(job.elapsedMs / 1_000))} / ${timeout}`] : []),
+    ...(settings.showTools ? [`tools: ${tools}`] : []),
+  ];
+  const detail = details.length > 0 ? theme.fg("muted", ` · ${details.join(" · ")}`) : "";
+  return `${symbol}${labels.join(" · ")}${detail}`;
 }
 
 function widgetValue(jobs: readonly ActiveJobDisplay[]): string {
   return jobs
     .map(
       (job) =>
-        `${job.jobId}\0${job.state}\0${Math.floor(job.elapsedMs / 1_000)}\0${job.timeout ?? ""}\0${job.tools.join(",")}`,
+        `${job.jobId}\0${job.task}\0${job.state}\0${Math.floor(job.elapsedMs / 1_000)}\0${job.timeout ?? ""}\0${job.tools.join(",")}`,
     )
     .join("\n");
 }
@@ -105,10 +145,6 @@ function cloneDisplayJob(job: ActiveJobDisplay): ActiveJobDisplay {
   return { ...job, tools: [...job.tools] };
 }
 
-function sanitizeLabel(value: string): string {
-  return sanitizeTerminalText(value).replace(/\s+/gu, " ").trim();
-}
-
 function formatSeconds(value: number): string {
   if (value < 60) return `${formatNumber(value)}s`;
   const wholeSeconds = Math.floor(value);

package/src/completion-renderer.ts

@@ -1,58 +0,0 @@
-import { type ExtensionAPI, getMarkdownTheme, keyText } from "@earendil-works/pi-coding-agent";
-import { Box, type Component, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
-import { sanitizeTerminalText } from "./message-broker.js";
-
-export const COMPLETION_MESSAGE_TYPE = "pi-subagents-completion";
-
-function createCompletionBox(
-  children: Component[],
-  outputPad: number,
-  background: (text: string) => string,
-): Component {
-  return {
-    render(width) {
-      if (width <= 0) return [];
-      const maxPadding = Math.floor((width - 1) / 2);
-      const box = new Box(Math.min(Math.max(0, outputPad), maxPadding), 1, background);
-      for (const child of children) box.addChild(child);
-      return box.render(width);
-    },
-    invalidate() {
-      for (const child of children) child.invalidate();
-    },
-  };
-}
-
-export function registerCompletionRenderer(pi: ExtensionAPI): void {
-  pi.registerMessageRenderer(COMPLETION_MESSAGE_TYPE, (message, options, theme) => {
-    const children: Component[] = [
-      new Text(theme.fg("customMessageLabel", theme.bold(`[${COMPLETION_MESSAGE_TYPE}]`)), 0, 0),
-      new Spacer(1),
-    ];
-    if (!options.expanded) {
-      children.push(
-        new Text(
-          theme.fg("customMessageText", "Subagent job completion (") +
-            theme.fg("dim", keyText("app.tools.expand")) +
-            theme.fg("customMessageText", " to expand)"),
-          0,
-          0,
-        ),
-      );
-    } else {
-      const content =
-        typeof message.content === "string"
-          ? message.content
-          : message.content
-              .filter((part) => part.type === "text")
-              .map((part) => part.text)
-              .join("\n");
-      children.push(
-        new Markdown(sanitizeTerminalText(content), 0, 0, getMarkdownTheme(), {
-          color: (text) => theme.fg("customMessageText", text),
-        }),
-      );
-    }
-    return createCompletionBox(children, options.outputPad, (text) => theme.bg("customMessageBg", text));
-  });
-}