@aliou/pi-processes 0.9.4 → 0.10.0

package/extensions/processes/tools/notify.ts

@@ -0,0 +1,191 @@
+import { isRecord } from "../../../src/utils/is-record";
+import {
+  MAX_LOG_MATCH_PATTERN_LENGTH,
+  MAX_LOG_MATCHERS_PER_PROCESS,
+} from "../notifications/log-matchers";
+import type { LogMatcherConfig, NotifyConfig } from "../notifications/registry";
+import type { Attention } from "../notifications/types";
+
+const ATTENTIONS = ["turn", "context", "ignore"] as const;
+const LOG_MATCH_MODES = ["literal", "regex"] as const;
+const LOG_MATCH_STREAMS = ["stdout", "stderr", "both"] as const;
+
+export const MAX_NOTIFY_LOG_MATCHERS = MAX_LOG_MATCHERS_PER_PROCESS;
+export const MAX_NOTIFY_PATTERN_LENGTH = MAX_LOG_MATCH_PATTERN_LENGTH;
+
+const DEFAULT_NOTIFY_CONFIG = {
+  onSuccess: "context",
+  onFailure: "turn",
+  // External kills (outside this manager) surface as context by default so
+  // the agent and user learn that a managed process disappeared. Intentional
+  // stops via the tool/command path are classified separately and never reach
+  // this branch.
+  onKilled: "context",
+} as const satisfies Pick<NotifyConfig, "onSuccess" | "onFailure" | "onKilled">;
+
+export function normalizeNotifyConfig(input: unknown): NotifyConfig {
+  if (input === undefined || input === null) {
+    return { ...DEFAULT_NOTIFY_CONFIG, logMatches: [] };
+  }
+
+  if (!isRecord(input)) {
+    throw new Error("process start notify must be an object");
+  }
+
+  const logMatches = input.logMatches;
+
+  return {
+    onSuccess:
+      normalizeAttention(input.onSuccess, "notify.onSuccess") ?? "context",
+    onFailure:
+      normalizeAttention(input.onFailure, "notify.onFailure") ?? "turn",
+    onKilled:
+      normalizeAttention(input.onKilled, "notify.onKilled") ?? "context",
+    logMatches: normalizeLogMatches(logMatches),
+  };
+}
+
+function normalizeLogMatches(input: unknown): LogMatcherConfig[] {
+  if (input === undefined || input === null) return [];
+
+  if (!Array.isArray(input)) {
+    throw new Error("process start notify.logMatches must be an array");
+  }
+
+  if (input.length > MAX_NOTIFY_LOG_MATCHERS) {
+    throw new Error(
+      `process start notify.logMatches supports at most ${MAX_NOTIFY_LOG_MATCHERS} matchers`,
+    );
+  }
+
+  return input.map((entry, index) => normalizeLogMatch(entry, index));
+}
+
+export function normalizeLogMatchItems(
+  input: unknown,
+  options: {
+    actionLabel: string;
+    pathPrefix: string;
+    maxItems?: number;
+  },
+): LogMatcherConfig[] {
+  const { actionLabel, pathPrefix } = options;
+  const maxItems = options.maxItems ?? MAX_NOTIFY_LOG_MATCHERS;
+
+  if (input === undefined || input === null) {
+    throw new Error(`${actionLabel} ${pathPrefix} is required`);
+  }
+
+  if (!Array.isArray(input)) {
+    throw new Error(`${actionLabel} ${pathPrefix} must be an array`);
+  }
+
+  if (input.length === 0) {
+    throw new Error(`${actionLabel} ${pathPrefix} must not be empty`);
+  }
+
+  if (input.length > maxItems) {
+    throw new Error(
+      `${actionLabel} ${pathPrefix} supports at most ${maxItems} items`,
+    );
+  }
+
+  return input.map((entry, index) =>
+    normalizeLogMatch(entry, index, { actionLabel, pathPrefix }),
+  );
+}
+
+export function normalizeLogMatch(
+  input: unknown,
+  index: number,
+  options?: { actionLabel?: string; pathPrefix?: string },
+): LogMatcherConfig {
+  const actionLabel = options?.actionLabel ?? "process start";
+  const path = `${options?.pathPrefix ?? "notify.logMatches"}[${index}]`;
+
+  if (!isRecord(input)) {
+    throw new Error(`${actionLabel} ${path} must be an object`);
+  }
+
+  if (typeof input.pattern !== "string") {
+    throw new Error(`${actionLabel} ${path}.pattern must be a string`);
+  }
+
+  // An empty or whitespace-only literal pattern matches every line
+  // (String#includes("")), and an empty regex matches every line too. Reject
+  // early so a stray "" from the model does not fire a notification per line.
+  if (input.pattern.trim().length === 0) {
+    throw new Error(
+      `${actionLabel} ${path}.pattern must not be empty or whitespace-only`,
+    );
+  }
+
+  if (input.pattern.length > MAX_NOTIFY_PATTERN_LENGTH) {
+    throw new Error(
+      `${actionLabel} ${path}.pattern must be at most ${MAX_NOTIFY_PATTERN_LENGTH} characters`,
+    );
+  }
+
+  const mode =
+    normalizeStringEnum(input.mode, LOG_MATCH_MODES, `${path}.mode`) ??
+    "literal";
+  const stream =
+    normalizeStringEnum(input.stream, LOG_MATCH_STREAMS, `${path}.stream`) ??
+    "both";
+  const repeat = normalizeBoolean(input.repeat, `${path}.repeat`) ?? false;
+  const on = normalizeAttention(input.on, `${path}.on`) ?? "turn";
+
+  if (mode === "regex") {
+    validateRegex(input.pattern, path);
+  }
+
+  return {
+    pattern: input.pattern,
+    mode,
+    stream,
+    repeat,
+    on,
+  };
+}
+
+function normalizeAttention(
+  input: unknown,
+  path: string,
+): Attention | undefined {
+  return normalizeStringEnum(input, ATTENTIONS, path);
+}
+
+function normalizeStringEnum<const T extends readonly string[]>(
+  input: unknown,
+  allowed: T,
+  path: string,
+): T[number] | undefined {
+  if (input === undefined || input === null) return undefined;
+
+  if (typeof input !== "string" || !allowed.includes(input)) {
+    throw new Error(`${path} must be one of: ${allowed.join(", ")}`);
+  }
+
+  return input;
+}
+
+function normalizeBoolean(input: unknown, path: string): boolean | undefined {
+  if (input === undefined || input === null) return undefined;
+
+  if (typeof input !== "boolean") {
+    throw new Error(`${path} must be a boolean`);
+  }
+
+  return input;
+}
+
+function validateRegex(pattern: string, path: string): void {
+  try {
+    new RegExp(pattern);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `${path}.pattern is not a valid regular expression: ${message}`,
+    );
+  }
+}

package/extensions/processes/tools/output/index.ts

@@ -0,0 +1,307 @@
+import {
+  formatSize,
+  type TruncationResult,
+  truncateTail,
+} from "@earendil-works/pi-coding-agent";
+
+import type { ProcessManager } from "../../../../src/manager";
+import { stripAnsi } from "../../../../src/utils";
+import type { LineMatchMode } from "../../../../src/utils/match-line";
+import { compileLineMatcher } from "../../../../src/utils/match-line";
+import type { ProcessesParamsType } from "../schema";
+import {
+  DEFAULT_OUTPUT_TAIL_LINES,
+  MAX_OUTPUT_BYTES,
+  MAX_OUTPUT_SCAN_LINES,
+  MAX_OUTPUT_TAIL_LINES,
+  type ProcessOutputMatchMode,
+  type ProcessOutputStream,
+} from "../schema";
+
+const MAX_OUTPUT_CONTENT_JSON_BYTES = 96 * 1024;
+const MAX_OUTPUT_PROCESS_NAME_BYTES = 256;
+
+export interface OutputDetails {
+  action: "output";
+  id: string;
+  processName: string;
+  processStatus: string;
+  stream: ProcessOutputStream;
+  tailLines: number;
+  pattern: string | null;
+  mode: ProcessOutputMatchMode;
+  stdoutFile: string;
+  stderrFile: string;
+  truncation?: OutputTruncationDetails;
+}
+
+export type OutputTruncationDetails = Omit<TruncationResult, "content">;
+
+interface OutputSelection {
+  stdout: string[];
+  stderr: string[];
+}
+
+export interface OutputExecutionResult {
+  content: string;
+  details: OutputDetails;
+}
+
+export function executeOutput(
+  params: ProcessesParamsType,
+  manager: ProcessManager,
+): OutputExecutionResult {
+  if (!params.id) {
+    throw new Error("process output requires id");
+  }
+
+  const process = manager.get(params.id);
+  if (!process) {
+    throw new Error(`process not found: ${params.id}`);
+  }
+
+  const stream = params.stream ?? "both";
+  const tailLines = clampTailLines(params.tailLines);
+  const mode = (params.mode ?? "literal") as LineMatchMode;
+  const pattern = params.pattern ?? null;
+
+  if (pattern && mode === "regex") {
+    validateRegex(pattern);
+  }
+
+  // Determine scan window: if filtering by pattern, read a larger bounded
+  // window so we can find matches beyond the narrow tail.
+  const scanLines = pattern ? MAX_OUTPUT_SCAN_LINES : tailLines;
+
+  const output = manager.getOutput(process.id, scanLines);
+  if (!output) {
+    throw new Error(
+      `could not read output for "${process.name}" (${process.id})`,
+    );
+  }
+
+  // Apply stream filter
+  let stdout: string[] = stream === "stderr" ? [] : output.stdout;
+  let stderr: string[] = stream === "stdout" ? [] : output.stderr;
+
+  // Apply pattern filter (filter first, then tail)
+  if (pattern) {
+    const lineMatcher = compileLineMatcher(pattern, mode);
+    stdout = stdout.filter(lineMatcher);
+    stderr = stderr.filter(lineMatcher);
+  }
+
+  // Tail to requested line count
+  stdout = stdout.slice(-tailLines);
+  stderr = stderr.slice(-tailLines);
+
+  const selection: OutputSelection = { stdout, stderr };
+  const processName = formatProcessName(process.name);
+
+  const contentParts = formatOutputContent({
+    processName,
+    id: process.id,
+    processStatus: output.status,
+    stream,
+    tailLines,
+    pattern,
+    mode,
+    ...selection,
+  });
+
+  const { content, truncation } = buildBoundedOutput(contentParts, {
+    stdoutFile: process.stdoutFile,
+    stderrFile: process.stderrFile,
+  });
+
+  const details: OutputDetails = {
+    action: "output",
+    id: process.id,
+    processName,
+    processStatus: output.status,
+    stream,
+    tailLines,
+    pattern,
+    mode,
+    stdoutFile: process.stdoutFile,
+    stderrFile: process.stderrFile,
+  };
+
+  if (truncation.truncated) {
+    const { content: _content, ...truncationDetails } = truncation;
+    details.truncation = truncationDetails;
+  }
+
+  return { content, details };
+}
+
+interface OutputContentInput extends OutputSelection {
+  processName: string;
+  id: string;
+  processStatus: string;
+  stream: ProcessOutputStream;
+  tailLines: number;
+  pattern: string | null;
+  mode: ProcessOutputMatchMode;
+}
+
+interface OutputContentParts {
+  header: string;
+  body: string;
+  guidance: string | null;
+}
+
+function formatOutputContent(input: OutputContentInput): OutputContentParts {
+  const header: string[] = [];
+  header.push(`"${input.processName}" (${input.id}) [${input.processStatus}]`);
+
+  if (input.pattern) {
+    const modeTag = input.mode === "regex" ? " (regex)" : "";
+    header.push(`filter: ${input.pattern}${modeTag}`);
+  }
+
+  const body: string[] = [];
+  const { stdout, stderr } = input;
+
+  if (stdout.length > 0) {
+    body.push("stdout:");
+    body.push(...stdout.map(stripAnsi));
+  }
+
+  if (stderr.length > 0) {
+    if (body.length > 0) body.push("");
+    body.push("stderr:");
+    body.push(...stderr.map(stripAnsi));
+  }
+
+  if (stdout.length === 0 && stderr.length === 0) {
+    body.push(input.pattern ? "No matching lines found." : "No output yet.");
+  }
+
+  return {
+    header: header.join("\n"),
+    body: body.join("\n"),
+    guidance:
+      input.processStatus === "running"
+        ? "Process is still running. Use watches instead of polling."
+        : null,
+  };
+}
+
+function buildBoundedOutput(
+  parts: OutputContentParts,
+  logFiles: { stdoutFile: string; stderrFile: string },
+): { content: string; truncation: TruncationResult } {
+  let maxBodyBytes = MAX_OUTPUT_BYTES;
+  let maxBodyLines = MAX_OUTPUT_TAIL_LINES;
+  let truncation = truncateTail(parts.body, {
+    maxBytes: maxBodyBytes,
+    maxLines: maxBodyLines,
+  });
+  let content = composeOutputContent(parts, truncation, logFiles);
+
+  // The header, guidance, truncation notice, and log paths are part of the
+  // persisted content limit. JSON escaping can expand control characters, so
+  // keep the serialized content bounded too. Reduce the body budget until the
+  // complete result fits while keeping the newest output.
+  for (let attempt = 0; attempt < 10; attempt++) {
+    const excessBytes = Buffer.byteLength(content, "utf8") - MAX_OUTPUT_BYTES;
+    const excessLines = countLines(content) - MAX_OUTPUT_TAIL_LINES;
+    const excessJsonBytes =
+      Buffer.byteLength(JSON.stringify(content), "utf8") -
+      MAX_OUTPUT_CONTENT_JSON_BYTES;
+    if (excessBytes <= 0 && excessLines <= 0 && excessJsonBytes <= 0) {
+      return { content, truncation };
+    }
+
+    maxBodyBytes = Math.max(0, maxBodyBytes - Math.max(0, excessBytes));
+    if (excessJsonBytes > 0) {
+      maxBodyBytes = Math.floor(maxBodyBytes / 2);
+    }
+    maxBodyLines = Math.max(1, maxBodyLines - Math.max(0, excessLines));
+    truncation = truncateTail(parts.body, {
+      maxBytes: maxBodyBytes,
+      maxLines: maxBodyLines,
+    });
+    content = composeOutputContent(parts, truncation, logFiles);
+  }
+
+  // Pathological metadata can consume the whole budget. Keep the final tail,
+  // which contains the truncation notice and complete-log paths, bounded.
+  const finalTruncation = truncateTail(content, {
+    maxBytes: MAX_OUTPUT_BYTES,
+    maxLines: MAX_OUTPUT_TAIL_LINES,
+  });
+  return { content: finalTruncation.content, truncation };
+}
+
+function composeOutputContent(
+  parts: OutputContentParts,
+  truncation: TruncationResult,
+  logFiles: { stdoutFile: string; stderrFile: string },
+): string {
+  const sections = [parts.header, truncation.content];
+
+  if (parts.guidance) {
+    sections.push(parts.guidance);
+  }
+
+  if (truncation.truncated) {
+    sections.push(formatTruncationNotice(truncation));
+  }
+
+  sections.push(
+    `[Complete currently-retained logs:\nstdout=${logFiles.stdoutFile}\nstderr=${logFiles.stderrFile}]`,
+  );
+  return sections.filter((section) => section.length > 0).join("\n\n");
+}
+
+function formatTruncationNotice(truncation: TruncationResult): string {
+  const limit =
+    truncation.truncatedBy === "bytes"
+      ? `${formatSize(truncation.maxBytes)} byte limit`
+      : `${truncation.maxLines} line limit`;
+  const partialNote = truncation.lastLinePartial
+    ? " (final line is a partial suffix)"
+    : "";
+  return `[Preview truncated by ${limit}${partialNote}; showing ${truncation.outputLines} lines / ${formatSize(truncation.outputBytes)} of ${truncation.totalLines} lines / ${formatSize(truncation.totalBytes)}.]`;
+}
+
+function countLines(text: string): number {
+  if (text.length === 0) return 0;
+  return text.split("\n").length;
+}
+
+function formatProcessName(name: string): string {
+  const clean = stripAnsi(name).replace(/\s+/gu, " ").trim() || "(unnamed)";
+  if (Buffer.byteLength(clean, "utf8") <= MAX_OUTPUT_PROCESS_NAME_BYTES) {
+    return clean;
+  }
+
+  const suffix = "…";
+  const buffer = Buffer.from(clean, "utf8");
+  let end = MAX_OUTPUT_PROCESS_NAME_BYTES - Buffer.byteLength(suffix, "utf8");
+  while (end > 0 && (buffer[end] ?? 0) >> 6 === 0b10) {
+    end--;
+  }
+  return `${buffer.subarray(0, end).toString("utf8")}${suffix}`;
+}
+
+function clampTailLines(value: number | undefined): number {
+  if (value === undefined || value === null) return DEFAULT_OUTPUT_TAIL_LINES;
+  const n = Math.floor(value);
+  if (n < 1) return DEFAULT_OUTPUT_TAIL_LINES;
+  if (n > MAX_OUTPUT_TAIL_LINES) return MAX_OUTPUT_TAIL_LINES;
+  return n;
+}
+
+function validateRegex(pattern: string): void {
+  try {
+    new RegExp(pattern);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `process output pattern is not a valid regular expression: ${message}`,
+    );
+  }
+}