@aliou/pi-processes 0.10.9 → 0.11.0

package/extensions/processes/notifications/service.ts

@@ -1,8 +1,8 @@
 import type { EventBus } from "@earendil-works/pi-coding-agent";
 
 import type { ProcessManager } from "../../../src/manager";
-import { CHANNELS } from "../../../src/protocol";
 import type { ManagerEvent, ProcessInfo } from "../../../src/types";
+import { CHANNELS } from "../../shared/protocol";
 import { classifyProcessEnd } from "./classify";
 import {
   type CompiledLogMatcher,
@@ -90,6 +90,9 @@ export function createNotificationService(deps: NotificationServiceDeps): {
     const kind = classifyProcessEnd(info);
 
     if (isIntentionalStop) {
+      const details = buildLifecycleDetails(info, kind, "context");
+      events.emit(CHANNELS.NOTIFICATION, details);
+
       cleanupMatcherState(info.id);
       registry.unregister(info.id);
       return;

package/extensions/processes/notifications/types.ts

@@ -1,6 +1,6 @@
 // Re-export the protocol-safe notification types so the core extension and the
 // protocol layer cannot drift apart. The canonical shape lives in
-// `src/protocol/notifications.ts`; these names keep existing import sites
+// `extensions/shared/protocol/notifications.ts`; these names keep existing import sites
 // stable while guaranteeing structural compatibility with the events emitted on
 // CHANNELS.NOTIFICATION.
 export type {
@@ -8,4 +8,4 @@ export type {
   ProcessProtocolNotificationKind as ProcessNotificationKind,
   ProcessProtocolNotificationLogMatch as ProcessNotificationLogMatchDetails,
   ProcessProtocolNotificationPayload as ProcessNotificationDetails,
-} from "../../../src/protocol";
+} from "../../shared/protocol";

package/extensions/processes/tools/notify.ts

@@ -1,17 +1,9 @@
-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;
+import type { NotifyLogMatchParamsType, NotifyParamsType } from "./schema";
 
 const DEFAULT_NOTIFY_CONFIG = {
   // A backgrounded process usually outlives the turn that started it, and
@@ -29,120 +21,66 @@ const DEFAULT_NOTIFY_CONFIG = {
   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: [] };
-  }
+export const MAX_NOTIFY_LOG_MATCHERS = MAX_LOG_MATCHERS_PER_PROCESS;
+export const MAX_NOTIFY_PATTERN_LENGTH = MAX_LOG_MATCH_PATTERN_LENGTH;
 
-  if (!isRecord(input)) {
-    throw new Error("process start notify must be an object");
-  }
+// Input arrives already validated against the TypeBox schema in ./schema.ts
+// (Pi validates tool call arguments before execute). Only semantic checks the
+// schema cannot express remain here: whitespace-only patterns (would match
+// every line) and regex validity.
 
-  const logMatches = input.logMatches;
+export function normalizeNotifyConfig(
+  input: NotifyParamsType | undefined,
+): NotifyConfig {
+  if (!input) {
+    return { ...DEFAULT_NOTIFY_CONFIG, logMatches: [] };
+  }
 
   return {
-    onSuccess:
-      normalizeAttention(input.onSuccess, "notify.onSuccess") ??
-      DEFAULT_NOTIFY_CONFIG.onSuccess,
-    onFailure:
-      normalizeAttention(input.onFailure, "notify.onFailure") ??
-      DEFAULT_NOTIFY_CONFIG.onFailure,
-    onKilled:
-      normalizeAttention(input.onKilled, "notify.onKilled") ??
-      DEFAULT_NOTIFY_CONFIG.onKilled,
-    logMatches: normalizeLogMatches(logMatches),
+    onSuccess: input.onSuccess ?? DEFAULT_NOTIFY_CONFIG.onSuccess,
+    onFailure: input.onFailure ?? DEFAULT_NOTIFY_CONFIG.onFailure,
+    onKilled: input.onKilled ?? DEFAULT_NOTIFY_CONFIG.onKilled,
+    logMatches: normalizeLogMatches(input.logMatches ?? [], {
+      actionLabel: "process start",
+      pathPrefix: "notify.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,
+  input: NotifyLogMatchParamsType[],
   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, options));
+}
 
-  return input.map((entry, index) =>
-    normalizeLogMatch(entry, index, { actionLabel, pathPrefix }),
-  );
+function normalizeLogMatches(
+  input: NotifyLogMatchParamsType[],
+  options: { actionLabel: string; pathPrefix: string },
+): LogMatcherConfig[] {
+  return input.map((entry, index) => normalizeLogMatch(entry, index, options));
 }
 
-export function normalizeLogMatch(
-  input: unknown,
+function normalizeLogMatch(
+  input: NotifyLogMatchParamsType,
   index: number,
-  options?: { actionLabel?: string; pathPrefix?: string },
+  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`);
-  }
+  const path = `${options.pathPrefix}[${index}]`;
 
   // 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`,
+      `${options.actionLabel} ${path}.pattern must not be empty or whitespace-only`,
     );
   }
 
-  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";
+  const mode = input.mode ?? "literal";
 
   if (mode === "regex") {
     validateRegex(input.pattern, path);
@@ -151,43 +89,12 @@ export function normalizeLogMatch(
   return {
     pattern: input.pattern,
     mode,
-    stream,
-    repeat,
-    on,
+    stream: input.stream ?? "both",
+    repeat: input.repeat ?? false,
+    on: input.on ?? "turn",
   };
 }
 
-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);

package/extensions/processes/tools/schema.ts

@@ -48,7 +48,7 @@ export const PROCESS_NOTIFY_LOG_MATCH_STREAMS = [
   "both",
 ] as const;
 
-const NotifyLogMatchParams = Type.Object({
+export const NotifyLogMatchParams = Type.Object({
   pattern: Type.String({
     maxLength: MAX_NOTIFY_PATTERN_LENGTH,
     description:
@@ -140,7 +140,7 @@ const NotifyProperties = {
   ),
 };
 
-const NotifyParams = Type.Object(NotifyProperties, {
+export const NotifyParams = Type.Object(NotifyProperties, {
   description:
     "Notify settings. Attention: turn wakes an idle agent, context only reaches an agent still working, ignore never notifies.",
 });
@@ -248,6 +248,9 @@ export const ProcessesParams = Type.Object({
 
 export type ProcessesParamsType = Static<typeof ProcessesParams>;
 
+export type NotifyParamsType = Static<typeof NotifyParams>;
+export type NotifyLogMatchParamsType = Static<typeof NotifyLogMatchParams>;
+
 export type ProcessAction = ProcessesParamsType["action"];
 export type ProcessListStatusFilter =
   (typeof PROCESS_LIST_STATUS_FILTERS)[number];

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

@@ -1,7 +1,6 @@
 import type { ProcessManager } from "../../../../src/manager";
 import type { ProcessInfo } from "../../../../src/types";
 import { LIVE_STATUSES } from "../../../../src/types";
-import { isRecord } from "../../../../src/utils/is-record";
 import type {
   LogMatcherConfig,
   NotificationRegistry,
@@ -187,7 +186,7 @@ function applyWatchUpdate(
   }
 
   if (mode === "append" || mode === "replace") {
-    const normalized = normalizeLogMatchItems(items, {
+    const normalized = normalizeLogMatchItems(items as never, {
       actionLabel: "process update",
       pathPrefix: "watches.items",
     });
@@ -205,46 +204,22 @@ function applyWatchUpdate(
   throw new Error(`unsupported watch update mode: ${String(mode)}`);
 }
 
-interface RawRemoveItem {
-  index?: number;
-  pattern?: string;
-  mode?: string;
-  stream?: string;
-  repeat?: boolean;
-  on?: string;
-}
-
-function normalizeWatchRemoveSpecs(items: unknown[]): WatchRemoveSpec[] {
-  return items.map((raw, index) => {
-    if (!isRecord(raw)) {
-      throw new Error(
-        `process update watches.items[${index}] must be an object`,
-      );
-    }
-
-    const item = raw as RawRemoveItem;
-
+// Watch items arrive already validated against the WatchUpdateItemParams
+// schema (Pi validates tool call arguments before execute). Only semantic
+// checks the schema cannot express remain here.
+type WatchUpdateItem = NonNullable<
+  NonNullable<ProcessesParamsType["watches"]>["items"]
+>[number];
+
+function normalizeWatchRemoveSpecs(
+  items: WatchUpdateItem[],
+): WatchRemoveSpec[] {
+  return items.map((item, index) => {
     if (item.index !== undefined) {
-      if (
-        typeof item.index !== "number" ||
-        !Number.isInteger(item.index) ||
-        item.index < 0
-      ) {
-        throw new Error(
-          `process update watches.items[${index}].index must be a non-negative integer`,
-        );
-      }
-
       return { index: item.index };
     }
 
     if (item.pattern !== undefined) {
-      if (typeof item.pattern !== "string") {
-        throw new Error(
-          `process update watches.items[${index}].pattern must be a string`,
-        );
-      }
-
       if (item.pattern.trim().length === 0) {
         throw new Error(
           `process update watches.items[${index}].pattern must not be empty`,
@@ -265,10 +240,10 @@ function normalizeWatchRemoveSpecs(items: unknown[]): WatchRemoveSpec[] {
 
       return {
         pattern: item.pattern,
-        mode: item.mode as WatchRemoveSpec["mode"],
-        stream: item.stream as WatchRemoveSpec["stream"],
+        mode: item.mode,
+        stream: item.stream,
         repeat: item.repeat,
-        on: item.on as WatchRemoveSpec["on"],
+        on: item.on,
       };
     }
 

package/extensions/processes-debug/index.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { requestStart } from "../processes/client";
+
+/**
+ * Debug extension for pi-processes.
+ *
+ * This extension is NOT listed in `package.json` under `pi.extensions`.
+ * Load it explicitly via `pi -ne -e ~/pi-processes-debug/`.
+ *
+ * It provides "programmatic" control over process management by exposing
+ * slash commands that go through the core extension's protocol channels,
+ * so processes started here are fully visible to the agent's `process` tool.
+ * This lets you start a background process during debugging without needing
+ * to prompt the agent.
+ */
+export default async function processesDebugExtension(
+  pi: ExtensionAPI,
+): Promise<void> {
+  const events = pi.events;
+
+  pi.registerCommand("debug:ps:start", {
+    description:
+      "Start a background process (debug). Usage: /debug:ps:start <name> <command>",
+    handler: async (args: string, ctx) => {
+      const parsed = parseStartArgs(args);
+      if (!parsed) {
+        ctx.ui.notify("Usage: /debug:ps:start <name> <command>", "warning");
+        return;
+      }
+
+      const result = await requestStart(events, {
+        name: parsed.name,
+        command: parsed.command,
+        cwd: ctx.cwd,
+      });
+
+      if (result.ok) {
+        ctx.ui.notify(
+          `Started ${result.process.name} (${result.process.id}) — pid ${result.process.pid}`,
+          "info",
+        );
+      } else {
+        ctx.ui.notify(`Failed to start process: ${result.error}`, "warning");
+      }
+    },
+  });
+}
+
+interface ParsedStartArgs {
+  name: string;
+  command: string;
+}
+
+function parseStartArgs(args: string): ParsedStartArgs | null {
+  const trimmed = args.trim();
+  if (!trimmed) return null;
+
+  const firstSpace = trimmed.indexOf(" ");
+  if (firstSpace === -1) return null;
+
+  const name = trimmed.slice(0, firstSpace);
+  const command = trimmed.slice(firstSpace + 1).trim();
+  if (!command) return null;
+
+  return { name, command };
+}

package/extensions/processes-dock/client.ts

@@ -1,4 +1,5 @@
 import type { EventBus } from "@earendil-works/pi-coding-agent";
+import type { ProcessInfo } from "../../src/types";
 import {
   CHANNELS,
   type ProcessProtocolConfig,
@@ -6,8 +7,7 @@ import {
   type RequestConfigPayload,
   type RequestGetPayload,
   type RequestListPayload,
-} from "../../src/protocol";
-import type { ProcessInfo } from "../../src/types";
+} from "../shared/protocol";
 
 export type ProcessLogLine = { type: "stdout" | "stderr"; text: string };
 

package/extensions/processes-dock/widget/setup.ts

@@ -3,15 +3,14 @@ import type {
   ExtensionContext,
   Theme,
 } from "@earendil-works/pi-coding-agent";
+import { LIVE_STATUSES, type ProcessInfo } from "../../../src/types";
+import { buildDroppedOutputLine, trimToBudget } from "../../shared/line-buffer";
 import {
   CHANNELS,
   type CommandPinPayload,
+  type ProcessesOutputChangedPayload,
   type ProcessProtocolNotificationPayload,
-} from "../../../src/protocol";
-import { LIVE_STATUSES, type ProcessInfo } from "../../../src/types";
-import { isRecord } from "../../../src/utils/is-record";
-import { buildDroppedOutputLine, trimToBudget } from "../../shared/line-buffer";
-import { isOutputChangedPayload } from "../../shared/output-payload";
+} from "../../shared/protocol";
 import {
   type ProcessLogLine,
   requestCombinedOutput,
@@ -342,6 +341,9 @@ export function setupDockWidgets(
   };
 
   const handleStarted = () => {
+    // Set synchronously so a process that exits within the scheduleRefresh
+    // throttle window still counts as "seen running" for auto-close.
+    hasSeenRunningProcess = true;
     if (config.widget.dockDefaultState === "expanded") state.actions.expand();
     else if (config.widget.dockDefaultState === "collapsed") {
       state.actions.collapse();
@@ -349,11 +351,8 @@ export function setupDockWidgets(
     scheduleRefresh();
   };
 
-  const handleOutputChanged = (payload: unknown) => {
-    if (!isOutputChangedPayload(payload)) {
-      scheduleRefresh();
-      return;
-    }
+  const handleOutputChanged = (rawPayload: unknown) => {
+    const payload = rawPayload as ProcessesOutputChangedPayload;
     if (
       (!payload.appendedText || payload.appendedText.length === 0) &&
       !payload.droppedLines
@@ -383,7 +382,6 @@ export function setupDockWidgets(
 
   const handlePin = (payload: unknown) => {
     const command = payload as CommandPinPayload;
-    if (!isCommandPinPayload(command)) return;
     // COMMAND_PIN can arrive before the dock's throttled CHANGED refresh has
     // run. Refresh the local snapshot first so expand/pin renders immediately
     // against the current process list.
@@ -427,8 +425,9 @@ export function setupDockWidgets(
     }),
   );
   disposers.push(
-    events.on(CHANNELS.NOTIFICATION, (payload) => {
-      if (!isLogMatchNotification(payload)) return;
+    events.on(CHANNELS.NOTIFICATION, (rawPayload) => {
+      const payload = rawPayload as ProcessProtocolNotificationPayload;
+      if (payload.kind !== "log_match" || !payload.logMatch) return;
       const list = notifyMarkers.get(payload.processId) ?? [];
       list.push({ line: payload.logMatch.line, timestamp: payload.timestamp });
       if (list.length > MAX_NOTIFY_MARKERS_PER_PROCESS) {
@@ -486,30 +485,6 @@ function isLogsConnectionError(
   return "ok" in connection && connection.ok === false;
 }
 
-function isLogMatchNotification(
-  payload: unknown,
-): payload is ProcessProtocolNotificationPayload & {
-  kind: "log_match";
-  logMatch: NonNullable<ProcessProtocolNotificationPayload["logMatch"]>;
-} {
-  return (
-    isRecord(payload) &&
-    payload.kind === "log_match" &&
-    typeof payload.processId === "string" &&
-    typeof payload.timestamp === "number" &&
-    isRecord(payload.logMatch) &&
-    typeof payload.logMatch.line === "string"
-  );
-}
-
-function isCommandPinPayload(payload: unknown): payload is CommandPinPayload {
-  return (
-    isRecord(payload) &&
-    (typeof payload.id === "string" || payload.id === null) &&
-    typeof payload.reply === "function"
-  );
-}
-
 function safeReply<T>(reply: (result: T) => void, result: T): void {
   try {
     reply(result);

package/extensions/processes-logs/client.ts

@@ -1,12 +1,12 @@
 import type { EventBus } from "@earendil-works/pi-coding-agent";
+import type { ProcessInfo } from "../../src/types";
 import {
   CHANNELS,
   type ProcessProtocolConfig,
   type RequestConfigPayload,
   type RequestGetPayload,
   type RequestListPayload,
-} from "../../src/protocol";
-import type { ProcessInfo } from "../../src/types";
+} from "../shared/protocol";
 
 export function requestProcessList(events: EventBus): ProcessInfo[] {
   let processes: ProcessInfo[] = [];

package/extensions/processes-logs/commands/logs.ts

@@ -4,9 +4,9 @@ import type {
   ExtensionCommandContext,
   Theme,
 } from "@earendil-works/pi-coding-agent";
-import type { ProcessProtocolConfig } from "../../../src/protocol";
 import type { ProcessInfo } from "../../../src/types";
 import { sanitizeForDisplay } from "../../shared/display-text";
+import type { ProcessProtocolConfig } from "../../shared/protocol";
 import { requestConfig, requestProcess, requestProcessList } from "../client";
 import { allProcessCompletions } from "../completions";
 import { LogOverlayComponent } from "../components/log-overlay-component";