pi-simple-background-tasks 0.0.0-stage → 0.1.0

package/src/core/shell-policy.ts

@@ -0,0 +1,180 @@
+import type {
+  BeforeAgentStartEvent,
+  BeforeAgentStartEventResult,
+} from '@earendil-works/pi-coding-agent';
+import {
+  type ResolvedShellPolicy,
+  resolveShellPolicy,
+  type ShellPolicySnapshot,
+} from './common.js';
+
+export const SHELL_POLICY_SECTION = 'pi_background_shell_policy';
+const SHELL_POLICY_OPEN = `<${SHELL_POLICY_SECTION}>`;
+const SHELL_POLICY_CLOSE = `</${SHELL_POLICY_SECTION}>`;
+
+interface ShellPolicyPromptEvent {
+  readonly systemPrompt: unknown;
+  readonly systemPromptOptions?: unknown;
+}
+
+function promptObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function unsupportedPrompt(field: string): Error {
+  return new Error(`pi_bg_shell_prompt_unsupported: invalid ${field}`);
+}
+
+export interface ShellPolicyInitializationOptions {
+  readonly platform?: NodeJS.Platform | undefined;
+  readonly env?: NodeJS.ProcessEnv | undefined;
+  readonly activationCwd?: string | undefined;
+}
+
+function displayedArgs(policy: ShellPolicySnapshot): string[] {
+  return [...policy.argvPrefix, policy.dialect === 'cmd' ? '"<command>"' : '<command>'];
+}
+
+/** Stable, non-secret guidance generated from the same selection used for spawning. */
+export function shellPolicyGuidance(policy: ShellPolicySnapshot): string {
+  const launch = JSON.stringify({
+    policy: policy.policy,
+    executable: policy.executable,
+    dialect: policy.dialect,
+    args: displayedArgs(policy),
+  });
+  const lines = [
+    `bg_run and /bg execute commands with the activation shell policy ${launch}.`,
+    'The executable and arguments are passed directly to process spawn; the executable path is never interpolated into another shell command.',
+  ];
+
+  if (policy.dialect === 'user-non-posix') {
+    lines.push(
+      'This inherited user shell is not classified as POSIX or Bash. Do not generate Bash/POSIX syntax or assume Bash startup files for bg_run or /bg.',
+      'Bash remediation: set PI_BG_POSIX_SHELL=bash before starting or reloading Pi; optionally set PI_BG_POSIX_SHELL_PATH to an absolute executable Bash path.',
+    );
+  } else if (policy.dialect === 'bash') {
+    lines.push(
+      'Generate Bash syntax for bg_run and /bg. Commands use Bash -c, never -lc, so login-shell startup files are not loaded implicitly.',
+    );
+  } else if (policy.dialect === 'posix') {
+    lines.push(
+      'Generate portable POSIX shell syntax for bg_run and /bg; do not assume Bash-only syntax. Commands use -c and do not request login-shell startup.',
+    );
+  } else {
+    lines.push(
+      'Generate Windows cmd.exe syntax for bg_run and /bg. The POSIX shell-selection variables do not change Windows execution.',
+    );
+  }
+
+  return lines.join('\n');
+}
+
+export function renderShellPolicyGuidanceBlock(policy: ShellPolicySnapshot): string {
+  return `${SHELL_POLICY_OPEN}\n${shellPolicyGuidance(policy)}\n${SHELL_POLICY_CLOSE}`;
+}
+
+/** Replace this package's section without disturbing guidance owned by another hook. */
+export function upsertShellPolicyGuidance(
+  systemPrompt: string,
+  policy: ShellPolicySnapshot,
+): string {
+  const block = renderShellPolicyGuidanceBlock(policy);
+  const start = systemPrompt.indexOf(SHELL_POLICY_OPEN);
+  if (start >= 0) {
+    const close = systemPrompt.indexOf(SHELL_POLICY_CLOSE, start + SHELL_POLICY_OPEN.length);
+    if (close >= 0) {
+      return `${systemPrompt.slice(0, start)}${block}${systemPrompt.slice(close + SHELL_POLICY_CLOSE.length)}`;
+    }
+  }
+  return systemPrompt.length > 0 ? `${systemPrompt}\n\n${block}` : block;
+}
+
+/**
+ * Array prompts are host-owned ordered sections (OMP 18.3.0). Never stringify or
+ * join them. Update the first complete owned block within one element, otherwise
+ * append one dedicated element; retain every other element, including empty ones.
+ */
+function upsertShellPolicySections(
+  parts: readonly unknown[],
+  policy: ShellPolicySnapshot,
+): string[] {
+  const sections: string[] = [];
+  for (const part of parts) {
+    // Iteration visits sparse holes as undefined, unlike Array.every/map.
+    if (typeof part !== 'string') throw unsupportedPrompt('systemPrompt array element');
+    sections.push(part);
+  }
+  const index = sections.findIndex((section) => {
+    const start = section.indexOf(SHELL_POLICY_OPEN);
+    return start >= 0 && section.indexOf(SHELL_POLICY_CLOSE, start + SHELL_POLICY_OPEN.length) >= 0;
+  });
+  const existing = sections[index];
+  if (existing === undefined) sections.push(renderShellPolicyGuidanceBlock(policy));
+  else sections[index] = upsertShellPolicyGuidance(existing, policy);
+  return sections;
+}
+
+/**
+ * Preserve Pi's chained string/structured-section contracts and OMP's string[]
+ * contract. Optional structured state is inspected only for string prompts.
+ */
+export function applyShellPolicyGuidance(
+  event: ShellPolicyPromptEvent & { readonly systemPrompt: string },
+  policy: ShellPolicySnapshot,
+): BeforeAgentStartEventResult | undefined;
+export function applyShellPolicyGuidance(
+  event: ShellPolicyPromptEvent & { readonly systemPrompt: readonly string[] },
+  policy: ShellPolicySnapshot,
+): { systemPrompt: string[] };
+export function applyShellPolicyGuidance(
+  event: ShellPolicyPromptEvent,
+  policy: ShellPolicySnapshot,
+): BeforeAgentStartEventResult | { systemPrompt: string[] } | undefined;
+export function applyShellPolicyGuidance(
+  event: ShellPolicyPromptEvent,
+  policy: ShellPolicySnapshot,
+): BeforeAgentStartEventResult | { systemPrompt: string[] } | undefined {
+  if (!promptObject(event)) throw unsupportedPrompt('before_agent_start event');
+  const prompt = event.systemPrompt;
+  if (Array.isArray(prompt)) return { systemPrompt: upsertShellPolicySections(prompt, policy) };
+  if (typeof prompt !== 'string')
+    throw unsupportedPrompt('systemPrompt (expected string or string[])');
+
+  const options = event.systemPromptOptions;
+  if (options !== undefined && options !== null) {
+    if (!promptObject(options)) throw unsupportedPrompt('systemPromptOptions');
+    const sections = options.sections;
+    if (sections !== undefined && sections !== null) {
+      if (!promptObject(sections)) throw unsupportedPrompt('systemPromptOptions.sections');
+      const forced = options.forceSystemPrompt;
+      if (forced !== undefined && typeof forced !== 'string') {
+        throw unsupportedPrompt('systemPromptOptions.forceSystemPrompt');
+      }
+      // Validate before mutating host-owned sections. Preserve the existing Pi
+      // mutation contract, including forced prompts that hide structured sections.
+      sections[SHELL_POLICY_SECTION] = shellPolicyGuidance(policy);
+      if (typeof forced === 'string') {
+        options.forceSystemPrompt = upsertShellPolicyGuidance(forced, policy);
+      }
+      return undefined;
+    }
+  }
+  return { systemPrompt: upsertShellPolicyGuidance(prompt, policy) };
+}
+
+export function createShellPolicyGuidanceHandler(policy: ResolvedShellPolicy) {
+  return (event: BeforeAgentStartEvent): BeforeAgentStartEventResult | undefined =>
+    applyShellPolicyGuidance(event, policy);
+}
+
+/** Resolve once at extension activation; the returned object is deeply frozen. */
+export function initializeShellPolicy(
+  options: ShellPolicyInitializationOptions = {},
+): ResolvedShellPolicy {
+  return resolveShellPolicy(
+    options.platform ?? process.platform,
+    options.env ?? process.env,
+    options.activationCwd ?? process.cwd(),
+  );
+}

package/src/core/task-cleanup.ts

@@ -0,0 +1,146 @@
+import { readdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { TERMINAL_TASK_STATUS_VALUES } from './common.js';
+
+export type CleanupScope = 'one' | 'session' | 'all';
+
+export interface CleanupDeleted {
+  id: string;
+  status: string;
+  runDir: string;
+}
+
+export interface CleanupSkipped {
+  id: string;
+  status: string;
+}
+
+export interface CleanupSummary {
+  scope: CleanupScope;
+  deleted: CleanupDeleted[];
+  skipped: CleanupSkipped[];
+  notFound: string[];
+}
+
+const TERMINAL = new Set<string>(TERMINAL_TASK_STATUS_VALUES);
+
+async function listRunDirs(tasksDir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(tasksDir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => join(tasksDir, entry.name));
+  } catch {
+    return [];
+  }
+}
+
+async function listTaskIds(runDir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(runDir);
+    return entries
+      .filter((name) => name.endsWith('.json'))
+      .map((name) => name.slice(0, name.length - 5));
+  } catch {
+    return [];
+  }
+}
+
+async function readTaskStatus(jsonPath: string): Promise<string | undefined> {
+  try {
+    const raw = await readFile(jsonPath, 'utf8');
+    const parsed = JSON.parse(raw) as { status?: unknown };
+    return typeof parsed.status === 'string' ? parsed.status : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function deleteTaskFiles(runDir: string, id: string): Promise<void> {
+  await rm(join(runDir, `${id}.json`), { force: true });
+  await rm(join(runDir, `${id}.output`), { force: true });
+}
+
+async function removeEmptyRunDir(runDir: string): Promise<void> {
+  let entries: string[];
+  try {
+    entries = await readdir(runDir);
+  } catch {
+    return;
+  }
+  if (entries.length > 0) return;
+  try {
+    await rm(runDir, { recursive: true });
+  } catch {
+    // Best effort: a directory that cannot be removed is harmless.
+  }
+}
+// Delete the on-disk files (.json + .output) of finished tasks only.
+// Running tasks are never touched; they are reported in `skipped`.
+// The run directory is removed once it becomes empty.
+export async function cleanupFinishedTasks(options: {
+  tasksDir: string;
+  sessionRunDir?: string;
+  scope: CleanupScope;
+  taskId?: string;
+}): Promise<CleanupSummary> {
+  const { tasksDir, sessionRunDir, scope, taskId } = options;
+  const summary: CleanupSummary = { scope, deleted: [], skipped: [], notFound: [] };
+
+  const consider = async (runDir: string, id: string): Promise<void> => {
+    const status = await readTaskStatus(join(runDir, `${id}.json`));
+    if (status === undefined) {
+      summary.notFound.push(id);
+      return;
+    }
+    if (!TERMINAL.has(status)) {
+      summary.skipped.push({ id, status });
+      return;
+    }
+    await deleteTaskFiles(runDir, id);
+    await removeEmptyRunDir(runDir);
+    summary.deleted.push({ id, status, runDir });
+  };
+
+  if (scope === 'one') {
+    if (!taskId) {
+      summary.notFound.push('taskId is required for scope "one"');
+      return summary;
+    }
+    const matches: { runDir: string; id: string }[] = [];
+    for (const runDir of await listRunDirs(tasksDir)) {
+      for (const id of await listTaskIds(runDir)) {
+        if (id === taskId || id.startsWith(taskId)) matches.push({ runDir, id });
+      }
+    }
+    if (matches.length === 0) {
+      summary.notFound.push(taskId);
+      return summary;
+    }
+    if (matches.length > 1) {
+      summary.notFound.push(`ambiguous taskId "${taskId}": ${matches.map((m) => m.id).join(', ')}`);
+      return summary;
+    }
+    const only = matches[0];
+    if (only) await consider(only.runDir, only.id);
+    return summary;
+  }
+
+  if (scope === 'session') {
+    if (!sessionRunDir) {
+      summary.notFound.push('no tasks have been started in this session yet');
+      return summary;
+    }
+    for (const id of await listTaskIds(sessionRunDir)) {
+      await consider(sessionRunDir, id);
+    }
+    return summary;
+  }
+
+  for (const runDir of await listRunDirs(tasksDir)) {
+    for (const id of await listTaskIds(runDir)) {
+      await consider(runDir, id);
+    }
+  }
+  return summary;
+}

package/src/core/task-durable.ts

@@ -0,0 +1,65 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { replaceFileDurable, writeFileDurable } from './durable-fs.js';
+
+function signalError(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason;
+  return reason instanceof Error
+    ? reason
+    : new Error(`Task admission cancelled${reason === undefined ? '' : `: ${String(reason)}`}`);
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted === true) throw signalError(signal);
+}
+
+export async function writeFileFsynced(
+  path: string,
+  data: Buffer | string,
+  signal?: AbortSignal,
+): Promise<void> {
+  throwIfAborted(signal);
+  await mkdir(dirname(path), { recursive: true });
+  throwIfAborted(signal);
+  await writeFileDurable(path, data, signal === undefined ? {} : { signal });
+}
+
+export async function writeJsonAtomic(
+  path: string,
+  value: unknown,
+  signal?: AbortSignal,
+): Promise<void> {
+  throwIfAborted(signal);
+  await replaceFileDurable(
+    path,
+    `${JSON.stringify(value, null, 2)}\n`,
+    signal === undefined ? {} : { signal },
+  );
+}
+
+export async function closeAndFsyncOutputStream(
+  stream: NodeJS.WritableStream | undefined,
+): Promise<void> {
+  if (!stream) return;
+  await new Promise<void>((resolvePromise, reject) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      stream.off('error', fail);
+      stream.off('close', finish);
+      stream.off('finish', finish);
+      resolvePromise();
+    };
+    const fail = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      stream.off('close', finish);
+      reject(error);
+    };
+    stream.once('close', finish);
+    stream.once('finish', finish);
+    stream.once('error', fail);
+    stream.end();
+  });
+}

package/src/core/windows-taskkill.ts

@@ -0,0 +1,263 @@
+import { spawn as nodeSpawn, type SpawnOptions } from 'node:child_process';
+import { win32 } from 'node:path';
+
+export type WindowsKillPhase = 'terminate' | 'force';
+
+export interface TaskkillOutcome {
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly stdoutTruncated: boolean;
+  readonly stderrTruncated: boolean;
+}
+
+interface TaskkillOutputStream {
+  on(event: 'data', listener: (data: Buffer | string) => void): unknown;
+}
+
+interface WindowsTaskkillChildProcess {
+  readonly stdout?: TaskkillOutputStream | null | undefined;
+  readonly stderr?: TaskkillOutputStream | null | undefined;
+  kill(signal?: NodeJS.Signals): boolean;
+  on(event: 'error', listener: (error: Error) => void): unknown;
+  on(
+    event: 'close',
+    listener: (code: number | null, signal: NodeJS.Signals | null) => void,
+  ): unknown;
+}
+
+type WindowsTaskkillSpawn = (
+  command: string,
+  args: string[],
+  options: SpawnOptions,
+) => WindowsTaskkillChildProcess;
+
+export interface WindowsTaskkillOptions {
+  readonly spawn?: WindowsTaskkillSpawn;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+  readonly maxCaptureBytes?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_CAPTURE_BYTES = 8 * 1024;
+
+class BoundedCapture {
+  private readonly chunks: Buffer[] = [];
+  private capturedBytes = 0;
+  private truncated = false;
+
+  constructor(private readonly maxBytes: number) {}
+
+  append(data: Buffer | string): void {
+    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+    if (buffer.length === 0) return;
+    const remaining = this.maxBytes - this.capturedBytes;
+    if (remaining > 0) {
+      const kept = buffer.length <= remaining ? buffer : buffer.subarray(0, remaining);
+      this.chunks.push(kept);
+      this.capturedBytes += kept.length;
+    }
+    if (buffer.length > Math.max(0, remaining)) this.truncated = true;
+  }
+
+  text(): string {
+    return Buffer.concat(this.chunks, this.capturedBytes).toString('utf8');
+  }
+
+  isTruncated(): boolean {
+    return this.truncated;
+  }
+}
+
+function lookupEnv(env: NodeJS.ProcessEnv, name: string): string | undefined {
+  const direct = env[name];
+  if (direct !== undefined) return direct;
+  const lowerName = name.toLowerCase();
+  for (const key of Object.keys(env)) {
+    if (key.toLowerCase() === lowerName) return env[key];
+  }
+  return undefined;
+}
+
+function validateWindowsRoot(raw: string, label: string): string {
+  const value = raw.trim();
+  if (value.length === 0) throw new Error(`${label} is empty; cannot resolve taskkill.exe`);
+  if (value.includes('\0'))
+    throw new Error(`${label} contains a NUL byte; cannot resolve taskkill.exe`);
+  if (!win32.isAbsolute(value)) {
+    throw new Error(`${label} must be an absolute Windows path; cannot resolve taskkill.exe`);
+  }
+  return value;
+}
+
+export function resolveTaskkillPath(env: NodeJS.ProcessEnv = process.env): string {
+  const systemRoot = lookupEnv(env, 'SystemRoot');
+  if (systemRoot !== undefined) {
+    return win32.join(validateWindowsRoot(systemRoot, 'SystemRoot'), 'System32', 'taskkill.exe');
+  }
+
+  const windir = lookupEnv(env, 'WINDIR');
+  if (windir !== undefined) {
+    return win32.join(validateWindowsRoot(windir, 'WINDIR'), 'System32', 'taskkill.exe');
+  }
+
+  throw new Error(
+    'Cannot resolve taskkill.exe: SystemRoot is missing and WINDIR fallback is missing',
+  );
+}
+
+function validatePid(pid: number): void {
+  if (!Number.isSafeInteger(pid) || pid <= 0) {
+    throw new Error(
+      `Invalid Windows taskkill pid ${String(pid)}; expected a positive safe integer`,
+    );
+  }
+}
+
+function validatePhase(phase: WindowsKillPhase): void {
+  if (phase !== 'terminate' && phase !== 'force') {
+    throw new Error(`Invalid Windows taskkill phase ${String(phase)}`);
+  }
+}
+
+function positiveFiniteInteger(value: number | undefined, fallback: number, label: string): number {
+  const candidate = value ?? fallback;
+  if (!Number.isFinite(candidate) || candidate <= 0) {
+    throw new Error(`${label} must be a positive finite number`);
+  }
+  return Math.max(1, Math.floor(candidate));
+}
+
+function outcome(
+  exitCode: number | null,
+  signal: NodeJS.Signals | null,
+  stdout: BoundedCapture,
+  stderr: BoundedCapture,
+): TaskkillOutcome {
+  return {
+    exitCode,
+    signal,
+    stdout: stdout.text(),
+    stderr: stderr.text(),
+    stdoutTruncated: stdout.isTruncated(),
+    stderrTruncated: stderr.isTruncated(),
+  };
+}
+
+function defaultSpawn(
+  command: string,
+  args: string[],
+  options: SpawnOptions,
+): WindowsTaskkillChildProcess {
+  return nodeSpawn(command, args, options);
+}
+
+export function runWindowsTaskkill(
+  pid: number,
+  phase: WindowsKillPhase,
+  options: WindowsTaskkillOptions = {},
+): Promise<TaskkillOutcome> {
+  validatePid(pid);
+  validatePhase(phase);
+  const env = options.env ?? process.env;
+  const taskkill = resolveTaskkillPath(env);
+  const timeoutMs = positiveFiniteInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 'timeoutMs');
+  const maxCaptureBytes = positiveFiniteInteger(
+    options.maxCaptureBytes,
+    DEFAULT_MAX_CAPTURE_BYTES,
+    'maxCaptureBytes',
+  );
+  const spawn = options.spawn ?? defaultSpawn;
+  const abortSignal = options.signal;
+
+  const args = ['/PID', String(pid), '/T'];
+  if (phase === 'force') args.push('/F');
+
+  if (abortSignal?.aborted) {
+    const stdout = new BoundedCapture(maxCaptureBytes);
+    const stderr = new BoundedCapture(maxCaptureBytes);
+    stderr.append('Windows taskkill was aborted before launch');
+    return Promise.resolve(outcome(null, null, stdout, stderr));
+  }
+
+  return new Promise<TaskkillOutcome>((resolve) => {
+    const stdout = new BoundedCapture(maxCaptureBytes);
+    const stderr = new BoundedCapture(maxCaptureBytes);
+    let settled = false;
+    let timeout: NodeJS.Timeout | undefined;
+    let child: WindowsTaskkillChildProcess | undefined;
+    let abortListener: (() => void) | undefined;
+
+    const settle = (result: TaskkillOutcome): void => {
+      if (settled) return;
+      settled = true;
+      if (timeout !== undefined) clearTimeout(timeout);
+      if (abortSignal !== undefined && abortListener !== undefined) {
+        abortSignal.removeEventListener('abort', abortListener);
+      }
+      resolve(result);
+    };
+
+    const stopHelper = (reason: string): void => {
+      stderr.append(reason);
+      if (child !== undefined) {
+        try {
+          child.kill('SIGKILL');
+        } catch (error) {
+          stderr.append(
+            `; helper kill failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      }
+      settle(outcome(null, null, stdout, stderr));
+    };
+
+    const spawnOptions: SpawnOptions = {
+      env,
+      shell: false,
+      windowsVerbatimArguments: false,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    };
+
+    try {
+      child = spawn(taskkill, args, spawnOptions);
+    } catch (error) {
+      stderr.append(
+        `Windows taskkill spawn failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      settle(outcome(null, null, stdout, stderr));
+      return;
+    }
+
+    child.stdout?.on('data', (data) => {
+      stdout.append(data);
+    });
+    child.stderr?.on('data', (data) => {
+      stderr.append(data);
+    });
+    child.on('error', (error) => {
+      stderr.append(`Windows taskkill spawn error: ${error.message}`);
+      settle(outcome(null, null, stdout, stderr));
+    });
+    child.on('close', (code, signal) => {
+      settle(outcome(code, signal, stdout, stderr));
+    });
+
+    abortListener = () => {
+      stopHelper('Windows taskkill was aborted');
+    };
+    abortSignal?.addEventListener('abort', abortListener, { once: true });
+
+    // This timeout is the settlement guarantee for a taskkill helper that never
+    // exits. It must keep the event loop alive: an unref'd timer lets the loop
+    // drain first and leaves this promise pending forever. `settle()` always
+    // clears it, so keeping it referenced cannot leak.
+    timeout = setTimeout(() => {
+      stopHelper(`Windows taskkill timed out after ${String(timeoutMs)}ms`);
+    }, timeoutMs);
+  });
+}