@pi-unipi/background-tasks 2.6.1

package/src/index.ts

@@ -0,0 +1,295 @@
+/**
+ * @pi-unipi/background-tasks — Module entry
+ *
+ * Master-toggle gate: when config `enabled` is false, this registers NOTHING
+ * (no tools, no commands, no hooks, no UI).
+ *
+ * Ported from pi-background-tasks src/extension.ts. Conventions ours:
+ * /unipi:* commands, temp-root runtime dir, UNIPI_BG_* env, update-check
+ * dropped (our updater module owns updates).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadBackgroundTasksConfig } from "./config.js";
+import { BackgroundTaskRegistry } from "./registry.js";
+import {
+  installBackgroundTaskExtensionApi,
+  type BackgroundTaskExtensionService,
+} from "./extension-api.js";
+import { registerToolsAndCommands } from "./tools.js";
+import { registerFusionExtension } from "./fusion-extension.js";
+import { registerDelegateExtension } from "./delegate-extension.js";
+import { taskDisplayName, type BgTask, type StartAttestedPiTaskOptions, type StartTaskOptions } from "./types.js";
+
+const STATUS_INTERVAL_MS = 1000;
+
+export default function backgroundTasksExtension(pi: ExtensionAPI): void {
+  const { config, warnings } = loadBackgroundTasksConfig(process.cwd());
+
+  for (const warning of warnings) {
+    console.error(`[background-tasks] ${warning}`);
+  }
+
+  if (!config.enabled) {
+    return;
+  }
+
+  const seenTaskIds = new Set<string>();
+  let currentCtx: ExtensionContext | undefined;
+  let dockOpen = false;
+  let statusInterval: NodeJS.Timeout | undefined;
+
+  const registry = new BackgroundTaskRegistry({
+    maxOutputBytes: config.maxOutputBytes,
+    maxRecentTasks: config.maxFinishedTasks,
+    onChange: () => {
+      updateUi();
+    },
+    sendCompletionNotification: (message, options) => {
+      // Our sendMessage path (same contract as reference; pi delivers followUp + triggerTurn)
+      pi.sendMessage(message as never, options as never);
+    },
+    publishTerminal: (task) => {
+      eventService.publishTerminal(task);
+    },
+  });
+  const eventService: BackgroundTaskExtensionService = installBackgroundTaskExtensionApi({
+    events: pi.events,
+    registry,
+    getContext: () => currentCtx,
+    isShuttingDown: () => registry.isShuttingDown(),
+  });
+
+  function unseenFinishedTasks(): BgTask[] {
+    return registry
+      .allTasks()
+      .filter((task) => task.status !== "running" && !seenTaskIds.has(task.id));
+  }
+
+  function clearFinishedNotices(ctx?: ExtensionContext): number {
+    const unseen = unseenFinishedTasks();
+    for (const task of unseen) seenTaskIds.add(task.id);
+    updateUi(ctx);
+    return unseen.length;
+  }
+
+  function updateUi(ctx?: ExtensionContext): void {
+    if (registry.isShuttingDown()) return;
+    const target = ctx ?? currentCtx;
+    if (!target) return;
+    try {
+      if (!target.hasUI) return;
+      const allTasks = registry.allTasks();
+      const running = allTasks.filter((task) => task.status === "running");
+      const unseenFailed = allTasks.filter((task) => task.status === "failed" && !seenTaskIds.has(task.id));
+      const unseenStopped = allTasks.filter((task) => task.status === "killed" && !seenTaskIds.has(task.id));
+      const unseenDone = allTasks.filter((task) => task.status === "completed" && !seenTaskIds.has(task.id));
+      const unseenFinishedCount = unseenFailed.length + unseenStopped.length + unseenDone.length;
+
+      target.ui.setWidget("background-tasks", undefined);
+      if (running.length === 0 && unseenFinishedCount === 0) {
+        target.ui.setStatus("background-tasks", undefined);
+        return;
+      }
+
+      const parts: string[] = [];
+      if (running.length > 0) parts.push(`${String(running.length)} running`);
+      if (unseenFailed.length > 0) parts.push(`${String(unseenFailed.length)} failed`);
+      if (unseenStopped.length > 0) parts.push(`${String(unseenStopped.length)} stopped`);
+      if (unseenDone.length > 0) parts.push(`${String(unseenDone.length)} done`);
+      const entryHint = dockOpen ? "focused" : `Shift↓${unseenFinishedCount > 0 ? " · /unipi:bg-clear" : ""}`;
+      const label = ` bg ${[...parts, entryHint].join(" · ")} `;
+      target.ui.setStatus("background-tasks", label);
+    } catch (error) {
+      console.error(
+        `[background-tasks] UI update failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      currentCtx = undefined;
+    }
+  }
+
+  async function startTask(ctx: ExtensionContext, command: string, opts: StartTaskOptions = {}): Promise<BgTask> {
+    currentCtx = ctx;
+    return registry.startTask(ctx, command, opts);
+  }
+
+  async function startAttestedPiTask(
+    ctx: ExtensionContext,
+    opts: StartAttestedPiTaskOptions,
+  ): Promise<BgTask> {
+    currentCtx = ctx;
+    return registry.startAttestedPiTask(ctx, opts);
+  }
+
+  async function openTaskManager(ctx: ExtensionContext, initialTaskId?: string): Promise<void> {
+    currentCtx = ctx;
+    if (!ctx.hasUI) {
+      ctx.ui.notify(
+        "Background task manager requires an interactive UI. Use /unipi:jobs, /unipi:logs, or the bg_status/bg_logs tools in non-interactive mode.",
+        "error",
+      );
+      return;
+    }
+    dockOpen = true;
+    updateUi(ctx);
+    try {
+      // Task manager overlay on our slot patterns — dynamic import keeps the
+      // component tree lazy. FleetView-style: bottom-center anchored overlay.
+      const { BackgroundTasksManager } = await import("./task-manager.js");
+      await ctx.ui.custom<"closed">(
+        (tui, theme, _keybindings, done) =>
+          new BackgroundTasksManager(tui, theme, done, {
+            getTasks: () => registry.allTasks(),
+            stopTask: async (task) => {
+              await registry.stopTask(registry.resolveTask(task.id), "user");
+              updateUi(ctx);
+            },
+            stopAllRunning: async () => {
+              const result = await registry.stopAllRunning("user");
+              updateUi(ctx);
+              return result;
+            },
+            rerunTask: async (task) => {
+              if (task.fusion !== undefined || task.delegate !== undefined) {
+                throw new Error(
+                  "Only shell-command tasks can be rerun from the dock; relaunch this typed workflow through its owning tool.",
+                );
+              }
+              const rerunOptions: StartTaskOptions = {
+                name: taskDisplayName(task),
+                isAgent: task.isAgent,
+                notifyOnCompletion: true,
+                triggerOnCompletion: false,
+              };
+              if (task.description !== undefined) rerunOptions.description = task.description;
+              if (task.timeoutSeconds !== undefined) rerunOptions.timeoutSeconds = task.timeoutSeconds;
+              const rerun = await startTask(ctx, task.command, rerunOptions);
+              updateUi(ctx);
+              return rerun;
+            },
+            showOutputPath: (task) => {
+              ctx.ui.notify(`Output path for ${taskDisplayName(task)} (${task.id}):\n${task.outputPath}`, "info");
+            },
+            markSeen: (taskId: string) => {
+              seenTaskIds.add(taskId);
+              updateUi(ctx);
+            },
+            markFinishedSeen: (taskIds: string[]) => {
+              for (const taskId of taskIds) seenTaskIds.add(taskId);
+              updateUi(ctx);
+            },
+            isSeen: (taskId: string) => seenTaskIds.has(taskId),
+            ...(initialTaskId ? { initialTaskId } : {}),
+          }),
+        {
+          overlay: true,
+          overlayOptions: {
+            anchor: "bottom-center",
+            width: "96%",
+            minWidth: 64,
+            maxHeight: "60%",
+            margin: { bottom: 1, left: 1, right: 1 },
+          } as never,
+        },
+      );
+    } finally {
+      dockOpen = false;
+      updateUi(ctx);
+    }
+  }
+
+  async function openSettings(ctx: ExtensionContext): Promise<void> {
+    currentCtx = ctx;
+    if (!ctx.hasUI) {
+      ctx.ui.notify(
+        "Background-tasks settings require an interactive UI. Edit ~/.unipi/config/background-tasks.json directly instead.",
+        "error",
+      );
+      return;
+    }
+    const { renderBackgroundTasksSettingsOverlay } = await import("./settings-overlay.js");
+    await ctx.ui.custom(
+      renderBackgroundTasksSettingsOverlay({ cwd: ctx.cwd ?? process.cwd() }),
+      {
+        overlay: true,
+        overlayOptions: {
+          anchor: "center",
+          width: "70%",
+          minWidth: 56,
+          margin: 2,
+        } as never,
+      },
+    );
+  }
+
+  registerToolsAndCommands({
+    pi,
+    registry,
+    startTask,
+    startAttestedPiTask,
+    openTaskManager,
+    clearFinishedNotices,
+    openSettings,
+  });
+
+  registerFusionExtension(pi, {
+    startManagedTask: async (ctx, options) => {
+      currentCtx = ctx;
+      return registry.startManagedTask(ctx, options);
+    },
+    snapshot: (task) => registry.snapshot(task),
+    updateManagedTask: (task, state, line) => registry.updateManagedTask(task, state, line),
+  });
+
+  registerDelegateExtension(pi, {
+    startDelegateTask: async (ctx, options) => {
+      currentCtx = ctx;
+      return registry.startDelegateTask(ctx, options);
+    },
+    snapshot: (task) => registry.snapshot(task),
+    resolveTask: (idOrPrefix) => registry.resolveTask(idOrPrefix),
+    claimFusionUsage: (task) => registry.claimFusionUsage(task),
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    registry.setShuttingDown(false);
+    currentCtx = ctx;
+    await registry.ensureRuntimeDir(ctx);
+    updateUi(ctx);
+    if (statusInterval) clearInterval(statusInterval);
+    statusInterval = setInterval(() => {
+      updateUi();
+    }, STATUS_INTERVAL_MS);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    registry.setShuttingDown(true);
+    currentCtx = undefined;
+    if (statusInterval) {
+      clearInterval(statusInterval);
+      statusInterval = undefined;
+    }
+    try {
+      const running = registry.allTasks().filter((task) => task.status === "running");
+      if (running.length === 0) return;
+
+      const failures: string[] = [];
+      await Promise.all(
+        running.map(async (task) => {
+          try {
+            await registry.stopTask(task, "shutdown", "Killed during Pi session shutdown/reload");
+          } catch (error) {
+            const message = `${task.id}: ${error instanceof Error ? error.message : String(error)}`;
+            failures.push(message);
+            console.error(`[background-tasks] shutdown cleanup failed for ${message}`);
+          }
+        }),
+      );
+      if (failures.length > 0 && ctx.hasUI) {
+        ctx.ui.notify(`Background task cleanup failed:\n${failures.join("\n")}`, "error");
+      }
+    } finally {
+      eventService.close();
+    }
+  });
+}

package/src/pi-launch.ts

@@ -0,0 +1,225 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import type { Stats } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, extname, isAbsolute, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface PiLaunchSpec {
+  readonly executable: string;
+  readonly argvPrefix: readonly string[];
+  readonly kind: 'path' | 'package-node-cli';
+}
+
+export interface PiLaunchDependencies {
+  readonly platform?: NodeJS.Platform;
+  readonly execPath?: string;
+  readonly resolvePackageJson?: (specifier: string) => string;
+  readonly readFile?: (path: string) => string | Buffer;
+  readonly realpath?: (path: string) => string;
+  readonly stat?: (path: string) => Pick<Stats, 'isFile'>;
+}
+
+export class PiLaunchResolutionError extends Error {
+  readonly code = 'pi_executable_resolution_failed';
+
+  constructor(message: string) {
+    super(`pi_executable_resolution_failed: ${message}`);
+    this.name = 'PiLaunchResolutionError';
+  }
+}
+
+export class PiCommandLineLimitError extends Error {
+  readonly code = 'pi_command_line_too_long';
+  readonly stage: string;
+  readonly measuredLength: number;
+  readonly limit: number;
+
+  constructor(stage: string, measuredLength: number, limit: number) {
+    super(
+      `pi_command_line_too_long: ${stage} measured UTF-16 command line length ${String(measuredLength)} exceeds limit ${String(limit)}`,
+    );
+    this.name = 'PiCommandLineLimitError';
+    this.stage = stage;
+    this.measuredLength = measuredLength;
+    this.limit = limit;
+  }
+}
+
+const PI_PACKAGE_NAME = '@earendil-works/pi-coding-agent';
+const PI_PACKAGE_MANIFEST = `${PI_PACKAGE_NAME}/package.json`;
+const WINDOWS_COMMAND_LINE_LIMIT = 32767;
+
+interface JsonRecord {
+  readonly [key: string]: unknown;
+}
+
+function defaultResolvePackageJson(specifier: string): string {
+  const requireForPi = createRequire(import.meta.url);
+  try {
+    return requireForPi.resolve(specifier);
+  } catch (manifestError) {
+    if (specifier !== PI_PACKAGE_MANIFEST) throw manifestError;
+    let packageEntry: string;
+    try {
+      packageEntry = fileURLToPath(import.meta.resolve(PI_PACKAGE_NAME));
+    } catch (entryError) {
+      throw new Error(
+        `${errorMessage(manifestError)}; package entry resolve failed: ${errorMessage(entryError)}`,
+      );
+    }
+    const diagnostics: string[] = [];
+    let dir = dirname(packageEntry);
+    for (;;) {
+      const candidate = join(dir, 'package.json');
+      try {
+        if (statSync(candidate).isFile()) return candidate;
+        diagnostics.push(`${candidate} is not a regular file`);
+      } catch (statError) {
+        diagnostics.push(`${candidate}: ${errorMessage(statError)}`);
+      }
+      const parent = dirname(dir);
+      if (parent === dir) {
+        throw new Error(
+          `${errorMessage(manifestError)}; package entry search failed: ${diagnostics.join('; ')}`,
+        );
+      }
+      dir = parent;
+    }
+  }
+}
+
+function failResolution(message: string): never {
+  throw new PiLaunchResolutionError(message);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function readPath<T>(label: string, path: string, action: () => T): T {
+  try {
+    return action();
+  } catch (error) {
+    failResolution(`${label} failed for ${path}: ${errorMessage(error)}`);
+  }
+}
+
+function isJsonRecord(value: unknown): value is JsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function parseManifest(raw: string | Buffer, manifestPath: string): JsonRecord {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(Buffer.isBuffer(raw) ? raw.toString('utf8') : raw);
+  } catch (error) {
+    failResolution(`manifest JSON is invalid at ${manifestPath}: ${errorMessage(error)}`);
+  }
+  if (!isJsonRecord(parsed)) failResolution(`manifest is not an object at ${manifestPath}`);
+  return parsed;
+}
+
+function readPiBin(manifest: JsonRecord, manifestPath: string): string {
+  const bin = manifest['bin'];
+  if (typeof bin === 'string' && bin.trim().length > 0) return bin;
+  if (isJsonRecord(bin)) {
+    const pi = bin['pi'];
+    if (typeof pi === 'string' && pi.trim().length > 0) return pi;
+  }
+  failResolution(`manifest bin.pi is missing or malformed at ${manifestPath}`);
+}
+
+function pathInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel) && !rel.split(sep).includes('..'));
+}
+
+export function resolvePiLaunch(deps: PiLaunchDependencies = {}): PiLaunchSpec {
+  const platform = deps.platform ?? process.platform;
+  if (platform !== 'win32') return { executable: 'pi', argvPrefix: [], kind: 'path' };
+
+  const resolvePackageJson = deps.resolvePackageJson ?? defaultResolvePackageJson;
+  const readFile = deps.readFile ?? readFileSync;
+  const realpath = deps.realpath ?? realpathSync;
+  const stat = deps.stat ?? statSync;
+  const execPath = deps.execPath ?? process.execPath;
+
+  let manifestPath: string;
+  try {
+    manifestPath = resolvePackageJson(PI_PACKAGE_MANIFEST);
+  } catch (error) {
+    failResolution(`package manifest resolve failed for ${PI_PACKAGE_MANIFEST}: ${errorMessage(error)}`);
+  }
+
+  const packageRoot = dirname(manifestPath);
+  const packageRootReal = readPath('package root realpath', packageRoot, () => realpath(packageRoot));
+  const manifest = parseManifest(
+    readPath('manifest read', manifestPath, () => readFile(manifestPath)),
+    manifestPath,
+  );
+  const bin = readPiBin(manifest, manifestPath);
+  const targetCandidate = join(packageRoot, bin);
+  const targetReal = readPath('bin target realpath', targetCandidate, () => realpath(targetCandidate));
+  if (!pathInside(packageRootReal, targetReal)) {
+    failResolution('Pi package bin target resolves outside the package root');
+  }
+  const targetStat = readPath('bin target stat', targetReal, () => stat(targetReal));
+  if (!targetStat.isFile()) failResolution('Pi package bin target is not a regular file');
+
+  const extension = extname(targetReal).toLowerCase();
+  if (extension === '.js' || extension === '.cjs' || extension === '.mjs') {
+    return { executable: execPath, argvPrefix: [targetReal], kind: 'package-node-cli' };
+  }
+  if (extension === '.exe' || extension === '.com') {
+    return { executable: targetReal, argvPrefix: [], kind: 'package-node-cli' };
+  }
+  failResolution(`Pi package bin target extension is unsupported: ${extension || '<none>'}`);
+}
+
+export function piLaunchArgv(launch: PiLaunchSpec, piArgs: readonly string[]): string[] {
+  return [...launch.argvPrefix, ...piArgs];
+}
+
+function renderWindowsArgument(value: string): string {
+  if (value.length > 0 && !/[ \t"]/.test(value)) return value;
+  let rendered = '"';
+  let backslashes = 0;
+  for (const char of value) {
+    if (char === '\\') {
+      backslashes += 1;
+      continue;
+    }
+    if (char === '"') {
+      rendered += '\\'.repeat(backslashes * 2 + 1);
+      rendered += '"';
+      backslashes = 0;
+      continue;
+    }
+    if (backslashes > 0) {
+      rendered += '\\'.repeat(backslashes);
+      backslashes = 0;
+    }
+    rendered += char;
+  }
+  if (backslashes > 0) rendered += '\\'.repeat(backslashes * 2);
+  rendered += '"';
+  return rendered;
+}
+
+function renderWindowsCommandLine(parts: readonly string[]): string {
+  return parts.map(renderWindowsArgument).join(' ');
+}
+
+export function assertWindowsCommandLineWithinLimit(
+  launch: PiLaunchSpec,
+  piArgs: readonly string[],
+  platform: NodeJS.Platform,
+  stage: string,
+): void {
+  if (platform !== 'win32') return;
+  const measuredLength =
+    renderWindowsCommandLine([launch.executable, ...launch.argvPrefix, ...piArgs]).length + 1;
+  if (measuredLength > WINDOWS_COMMAND_LINE_LIMIT) {
+    throw new PiCommandLineLimitError(stage, measuredLength, WINDOWS_COMMAND_LINE_LIMIT);
+  }
+}