@aliou/pi-processes 0.11.1 → 0.12.0

package/extensions/processes/handlers/commands.ts

@@ -4,6 +4,7 @@ import type { ProcessManager } from "../../../src/manager";
 import type { KillResult } from "../../../src/types";
 import {
   CHANNELS,
+  type CommandAdoptPayload,
   type CommandClearPayload,
   type CommandKillPayload,
   type CommandStartPayload,
@@ -51,13 +52,36 @@ export function registerCommandHandlers(
 
       safeReply(command.reply, manager.clearFinished());
     }),
+    events.on(CHANNELS.COMMAND_ADOPT, (payload) => {
+      const command = payload as CommandAdoptPayload;
+
+      try {
+        const info = manager.adopt(
+          command.name,
+          command.command,
+          command.cwd,
+          command.child,
+          {
+            initialStdout: command.initialStdout,
+            initialStderr: command.initialStderr,
+            startTime: command.startTime,
+          },
+        );
+        notifications.register(info.id, {});
+        safeReply(command.reply, { ok: true, info });
+      } catch (error) {
+        safeReply(command.reply, {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }),
   ];
 
   return () => {
     for (const dispose of disposers) dispose();
   };
 }
-
 function safeReply<T>(reply: (result: T) => void, result: T): void {
   try {
     reply(result);

package/extensions/processes/notification-sender.ts

@@ -12,7 +12,12 @@ export interface ProcessNotificationSendOptions {
   deliverAs: "steer" | "followUp" | "nextTurn";
 }
 
-/** Maps a notification attention level to Pi send-message options. */
+/**
+ * Maps a notification attention level to Pi send-message options.
+ *
+ * `turn` wakes or steers the agent. Other emitted notifications wait for the
+ * next user prompt so they cannot split a tool call from its result.
+ */
 export function attentionToSendOptions(
   attention: Attention,
 ): ProcessNotificationSendOptions {
@@ -20,9 +25,9 @@ export function attentionToSendOptions(
     case "turn":
       return { triggerTurn: true, deliverAs: "steer" };
     case "context":
-      return { triggerTurn: false, deliverAs: "steer" };
+      return { triggerTurn: false, deliverAs: "nextTurn" };
     case "ignore":
-      return { triggerTurn: false, deliverAs: "steer" };
+      return { triggerTurn: false, deliverAs: "nextTurn" };
   }
 }
 

package/extensions/processes/tools/index.ts

@@ -56,7 +56,7 @@ export function registerProcessTool(
       promptGuidelines: [
         "process tool: use process start for long-running commands (dev servers, watchers, builds) instead of shell background patterns like &, nohup, or setsid; give each process a specific name and check process list first when a duplicate would be noisy.",
         "process tool: after process start, do not sleep, poll, or hold your turn. End your turn or move on. Exits and notify.logMatches matches bring you back.",
-        "process tool: attention turn wakes you when idle; context only reaches you if you are still working; ignore never notifies. Keep turn for anything whose result you need.",
+        "process tool: attention turn wakes or steers you now; context waits for the next user prompt. Ignore suppresses successful exits and external kills but retains log matches as context. Failures always notify, with ignore downgraded to context. Keep turn for anything whose result you need immediately.",
         "process tool: use notify.logMatches to get brought back on readiness or error signals instead of polling process output. If a watch is too noisy, use process update (watches.mode append/replace/remove/clear) to fix it without restarting.",
         "process tool: for the full lifecycle (start, list, output, update, write, stop, clear), notify options, use cases, and noisy-watch handling, read the pi-processes skill.",
       ],

package/extensions/processes/tools/notify.ts

@@ -6,12 +6,10 @@ import type { LogMatcherConfig, NotifyConfig } from "../notifications/registry";
 import type { NotifyLogMatchParamsType, NotifyParamsType } from "./schema";
 
 const DEFAULT_NOTIFY_CONFIG = {
-  // A backgrounded process usually outlives the turn that started it, and
-  // "context" only reaches the agent if it happens to still be streaming when
-  // the process ends. Builds, tests, and other one-shot commands are started
-  // precisely because the agent needs the result, so success defaults to a
-  // turn. Long-running servers rarely exit 0, and callers that do not want the
-  // interruption can pass onSuccess: "context".
+  // Builds, tests, and other one-shot commands are started because the agent
+  // needs the result, so success defaults to a turn. Long-running servers
+  // rarely exit 0, and callers that only need the result as future context can
+  // pass onSuccess: "context".
   onSuccess: "turn",
   onFailure: "turn",
   // External kills (outside this manager) surface as context by default so

package/extensions/processes/tools/schema.ts

@@ -142,7 +142,7 @@ const 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.",
+    "Notify settings. Attention: turn wakes or steers the agent; context waits for the next user prompt; ignore suppresses successful exits and external kills but retains log matches as context. Failures always notify, with ignore downgraded to context.",
 });
 
 export const ProcessesParams = Type.Object({

package/extensions/shared/protocol/channels.ts

@@ -18,6 +18,9 @@ export const CHANNELS = {
   COMMAND_START: "processes:command:start",
   COMMAND_KILL: "processes:command:kill",
   COMMAND_CLEAR: "processes:command:clear",
+  // Other extensions emit this to hand an already-running child process
+  // over to the manager (e.g. backgrounding a foreground tool command).
+  COMMAND_ADOPT: "processes:command:adopt",
   // Pin handled by the dock extension, if loaded.
   COMMAND_PIN: "processes:command:pin",
 

package/extensions/shared/protocol/commands.ts

@@ -1,3 +1,5 @@
+import type { ChildProcess } from "node:child_process";
+
 import type { KillResult, ProcessInfo } from "../../../src/types";
 
 // UI emits, core handles then calls reply.
@@ -33,3 +35,27 @@ export interface CommandPinPayload {
 }
 
 export type CommandPinResult = { ok: true } | { ok: false; error: string };
+
+// Another extension emits this to hand an already-running child process over
+// to the manager. The child must have been spawned in a detached process
+// group (`detached: true`) with piped stdio — the same shape the manager's
+// own spawns use — so group kill and liveness polling work on it. Payloads
+// cross the event bus by reference, so the live ChildProcess handle arrives
+// intact. If the processes extension is not loaded, no listener replies.
+export interface CommandAdoptPayload {
+  name: string;
+  command: string;
+  cwd: string;
+  child: ChildProcess;
+  /** Stdout captured before handover. */
+  initialStdout?: Buffer;
+  /** Stderr captured before handover. */
+  initialStderr?: Buffer;
+  /** When the command actually started (epoch ms). */
+  startTime?: number;
+  reply: (result: CommandAdoptResult) => void;
+}
+
+export type CommandAdoptResult =
+  | { ok: true; info: ProcessInfo }
+  | { ok: false; error: string };

package/extensions/shared/protocol/index.ts

@@ -6,6 +6,8 @@ export type {
 } from "./broadcasts";
 export { CHANNELS } from "./channels";
 export type {
+  CommandAdoptPayload,
+  CommandAdoptResult,
   CommandClearPayload,
   CommandKillPayload,
   CommandPinPayload,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-processes",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "license": "MIT",
   "type": "module",
   "private": false,

package/skills/pi-processes/SKILL.md

@@ -16,10 +16,9 @@ A started process runs in the background and the manager brings you back when so
 3. The process notifies you when:
    - a `logMatches` pattern hits (readiness, error, progress),
    - the process exits successfully (`onSuccess`, default `turn`),
-   - the process fails or crashes (`onFailure`, default `turn`),
-   - the process is killed externally (`onKilled`, default `context`, which does not wake an idle agent).
-
-   Stopping a process yourself never notifies.
+   - the process fails or crashes (`onFailure`, default `turn`; failures always notify),
+   - the process is killed externally (`onKilled`, default `context`),
+   - you stop the process intentionally (always `context`; notify config does not apply).
 4. When a watch is too noisy or wrong, fix it with `process update` — do not restart the process just to change watches.
 5. `process stop` obsolete live processes and `process clear` finished entries when they are no longer useful.
 
@@ -52,7 +51,7 @@ Good:
 }
 ```
 
-`onSuccess: "context"` here because a dev server exiting cleanly needs no reaction. Keep the default `turn` for builds, tests, and other one-shot commands whose result you need.
+`onSuccess: "context"` here because a dev server exiting cleanly needs no immediate reaction; the result becomes context on the next user prompt. Keep the default `turn` for builds, tests, and other one-shot commands whose result you need immediately.
 
 Optional `cwd` sets the working directory for the spawned command. Omit it to inherit the agent's current working directory.
 
@@ -219,8 +218,8 @@ Good:
 Exit attention:
 
 - `notify.onSuccess` — clean exit. Defaults to `turn`.
-- `notify.onFailure` — failure or crash. Defaults to `turn`.
-- `notify.onKilled` — killed from outside the tool. Defaults to `context`. Stopping a process yourself never notifies.
+- `notify.onFailure` — failure or crash. Defaults to `turn`; `ignore` is downgraded to `context` because failures always notify.
+- `notify.onKilled` — killed from outside the tool. Defaults to `context`. Intentional stops always produce context and bypass this setting.
 
 Log match watches (`notify.logMatches`, up to 20, each pattern up to 500 chars):
 
@@ -232,11 +231,11 @@ Log match watches (`notify.logMatches`, up to 20, each pattern up to 500 chars):
 
 Attention levels:
 
-- `turn` — starts an agent turn. Reaches you even when you are idle.
-- `context` — recorded in the transcript, no turn. It reaches you only if you are still working when the event fires; an idle agent is not woken and sees it on the next user message.
-- `ignore` — recorded, never notifies.
+- `turn` — wakes an idle agent or steers an active run at the next safe boundary.
+- `context` — queued for the next user prompt; it does not wake or steer the agent.
+- `ignore` — suppresses successful-exit and external-kill notifications. Log matches are retained for the next user prompt. Failure and crash notifications are also retained because failures always notify.
 
-Use `context` only when nothing needs to happen in response.
+Use `context` when nothing needs to happen immediately.
 
 ## Use cases
 
@@ -368,7 +367,7 @@ Then pick a `watches.mode`:
 }
 ```
 
-- **Silence without removing** — set the watch's `on` to `ignore` so matches are recorded but do not interrupt.
+- **Retain without interrupting** — set the watch's `on` to `ignore` so matches become context on the next user prompt.
 
 ```json
 {

package/src/manager/index.ts

@@ -1,6 +1,8 @@
+import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 
 import type {
+  AdoptProcessOptions,
   KillResult,
   ManagerEvent,
   ProcessInfo,
@@ -57,6 +59,22 @@ export class ProcessManager {
     return formatProcess(managed);
   }
 
+  /**
+   * Adopt an externally spawned child process. The child must run in a
+   * detached process group with piped stdio (see
+   * ProcessRuntimeController.adopt for the full contract).
+   */
+  adopt(
+    name: string,
+    command: string,
+    cwd: string,
+    child: ChildProcess,
+    opts?: AdoptProcessOptions,
+  ): ProcessInfo {
+    const managed = this.runtime.adopt(name, command, cwd, child, opts);
+    return formatProcess(managed);
+  }
+
   list(): ProcessInfo[] {
     return this.registry.list();
   }

package/src/manager/process-log-store.ts

@@ -13,7 +13,7 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-
+import { trimIncompleteUtf8Suffix } from "../utils/buffer";
 import type { ProcessLogPaths } from "./internal-types";
 import { MAX_LOG_FILE_BYTES, MAX_TAIL_READ_BYTES } from "./limits";
 
@@ -401,22 +401,3 @@ function decodeUtf8Bounded(buffer: Buffer, maxOutputBytes: number): string {
 
   return parts.join("");
 }
-
-function trimIncompleteUtf8Suffix(buffer: Buffer): Buffer {
-  if (buffer.length === 0) return buffer;
-  let lead = buffer.length - 1;
-  while (lead >= 0 && (buffer[lead] & 0xc0) === 0x80) lead--;
-  if (lead < 0) return Buffer.alloc(0);
-  const byte = buffer[lead];
-  const expected =
-    byte < 0x80
-      ? 1
-      : (byte & 0xe0) === 0xc0
-        ? 2
-        : (byte & 0xf0) === 0xe0
-          ? 3
-          : (byte & 0xf8) === 0xf0
-            ? 4
-            : 1;
-  return buffer.length - lead < expected ? buffer.subarray(0, lead) : buffer;
-}

package/src/manager/process-output.ts

@@ -1,4 +1,5 @@
 import type { ManagerEvent } from "../types";
+import { trimIncompleteUtf8Suffix } from "../utils/buffer";
 import type { ManagedProcessRecord } from "./internal-types";
 import {
   MAX_LINE_BYTES,
@@ -321,25 +322,3 @@ export class ProcessOutput {
     this.clearAll();
   }
 }
-
-function trimIncompleteUtf8Suffix(buffer: Buffer): Buffer {
-  if (buffer.length === 0) return buffer;
-
-  let lead = buffer.length - 1;
-  while (lead >= 0 && (buffer[lead] & 0xc0) === 0x80) lead--;
-  if (lead < 0) return Buffer.alloc(0);
-
-  const leadByte = buffer[lead];
-  const expectedLength =
-    leadByte < 0x80
-      ? 1
-      : (leadByte & 0xe0) === 0xc0
-        ? 2
-        : (leadByte & 0xf0) === 0xe0
-          ? 3
-          : (leadByte & 0xf8) === 0xf0
-            ? 4
-            : 1;
-  const actualLength = buffer.length - lead;
-  return actualLength < expectedLength ? buffer.subarray(0, lead) : buffer;
-}

package/src/manager/process-runtime-controller.ts

@@ -1,13 +1,23 @@
 import type { ChildProcess } from "node:child_process";
 
-import type { KillResult, ManagerEvent, WriteResult } from "../types";
+import type {
+  AdoptProcessOptions,
+  KillResult,
+  ManagerEvent,
+  WriteResult,
+} from "../types";
 import { LIVE_STATUSES } from "../types";
 import { isProcessGroupAlive, killProcessGroup } from "../utils";
+import { clampToTail } from "../utils/buffer";
 import { spawnCommand } from "../utils/command-executor";
 import { formatSignalInfo } from "../utils/signals";
 import type { ManagedProcessRecord } from "./internal-types";
 import { formatProcess } from "./internal-types";
-import { FINISHED_RECORD_GRACE_MS, MAX_FINISHED_RECORDS } from "./limits";
+import {
+  FINISHED_RECORD_GRACE_MS,
+  MAX_FINISHED_RECORDS,
+  MAX_TAIL_READ_BYTES,
+} from "./limits";
 import type { ProcessLogStore } from "./process-log-store";
 import type { ProcessOutput } from "./process-output";
 import type { ProcessRegistry } from "./process-registry";
@@ -41,10 +51,45 @@ export class ProcessRuntimeController {
   }
 
   start(name: string, command: string, cwd: string): ManagedProcessRecord {
+    const child = spawnCommand(command, cwd, this.getConfiguredShellPath());
+    return this.register(name, command, cwd, child, {});
+  }
+
+  /**
+   * Adopt an externally spawned child process into the manager.
+   *
+   * The child must have been spawned like `spawnCommand` spawns: in a
+   * detached process group (`detached: true`) with piped stdio, so group
+   * kill and liveness polling behave identically to started processes.
+   *
+   * `initialStdout` / `initialStderr` are pre-handover output, each
+   * prepended to the matching log and clamped to MAX_TAIL_READ_BYTES.
+   * `startTime` backdates the record to when the command actually began.
+   */
+  adopt(
+    name: string,
+    command: string,
+    cwd: string,
+    child: ChildProcess,
+    opts?: AdoptProcessOptions,
+  ): ManagedProcessRecord {
+    return this.register(name, command, cwd, child, {
+      initialStdout: opts?.initialStdout,
+      initialStderr: opts?.initialStderr,
+      startTime: opts?.startTime,
+    });
+  }
+
+  private register(
+    name: string,
+    command: string,
+    cwd: string,
+    child: ChildProcess,
+    opts: AdoptProcessOptions,
+  ): ManagedProcessRecord {
     const id = this.registry.nextId();
     const logPaths = this.logs.createLogs(id);
 
-    const child = spawnCommand(command, cwd, this.getConfiguredShellPath());
     // Spawned commands run in detached process groups so TERM/KILL can target
     // the whole tree. `unref()` keeps the manager's Node process from staying
     // alive only because a managed child still exists; extension shutdown and
@@ -57,7 +102,7 @@ export class ProcessRuntimeController {
       pid: child.pid ?? -1,
       command,
       cwd,
-      startTime: Date.now(),
+      startTime: opts.startTime ?? Date.now(),
       endTime: null,
       status: "running",
       exitCode: null,
@@ -107,14 +152,64 @@ export class ProcessRuntimeController {
       return managed;
     }
 
+    if (opts.initialStdout && opts.initialStdout.length > 0) {
+      const clamped = clampToTail(opts.initialStdout, MAX_TAIL_READ_BYTES);
+      this.logs.appendStdout(managed.stdoutFile, clamped);
+      this.output.onStdoutChunk(managed, clamped);
+    }
+    if (opts.initialStderr && opts.initialStderr.length > 0) {
+      const clamped = clampToTail(opts.initialStderr, MAX_TAIL_READ_BYTES);
+      this.logs.appendStderr(managed.stderrFile, clamped);
+      this.output.onStderrChunk(managed, clamped);
+    }
+
     this.wireStdioHandlers(managed, child);
 
     this.emit({ type: "process_started", info: formatProcess(managed) });
+    this.finalizeIfAlreadyClosed(managed, child);
     this.ensureWatcherRunning();
 
     return managed;
   }
 
+  /**
+   * An adopted child may have fully exited (close event fired) before its
+   * handlers were attached here. In that case no close event will ever
+   * reach wireStdioHandlers, so replay the close classification directly.
+   * If the child exited but its streams are still open, the pending close
+   * event will finalize the record through the normal path.
+   */
+  private finalizeIfAlreadyClosed(
+    managed: ManagedProcessRecord,
+    child: ChildProcess,
+  ): void {
+    const exited = child.exitCode !== null || child.signalCode !== null;
+    if (!exited) return;
+
+    const streamsDone =
+      (child.stdout?.destroyed ?? true) && (child.stderr?.destroyed ?? true);
+    if (!streamsDone) return;
+
+    this.releaseRuntimeHandles(managed);
+    if (managed.endTime) return;
+
+    managed.exitCode = child.exitCode;
+    managed.endTime = Date.now();
+    this.output.flush(managed);
+
+    if (child.signalCode) {
+      managed.success = false;
+      managed.endReason = "signal";
+      managed.signal = formatSignalInfo(child.signalCode);
+      this.transition(managed, "killed");
+    } else {
+      managed.success = child.exitCode === 0;
+      managed.endReason = "exit";
+      managed.signal = null;
+      this.transition(managed, "exited");
+    }
+  }
+
   transition(managed: ManagedProcessRecord, next: typeof managed.status): void {
     if (managed.status === next) return;
     managed.status = next;

package/src/types.ts

@@ -54,6 +54,16 @@ export type ManagerEvent =
     }
   | { type: "processes_changed" };
 
+/** Options for adopting an externally spawned child process. */
+export interface AdoptProcessOptions {
+  /** Pre-handover stdout; prepended to the stdout log, clamped to MAX_TAIL_READ_BYTES. */
+  initialStdout?: Buffer;
+  /** Pre-handover stderr; prepended to the stderr log, clamped to MAX_TAIL_READ_BYTES. */
+  initialStderr?: Buffer;
+  /** When the command actually started (epoch ms). Defaults to adoption time. */
+  startTime?: number;
+}
+
 export type KillResult =
   | { ok: true; info: ProcessInfo }
   | { ok: false; info: ProcessInfo; reason: "not_found" | "timeout" | "error" };

package/src/utils/buffer.ts

@@ -0,0 +1,28 @@
+/** Trim trailing bytes that form an incomplete UTF-8 code point. */
+export function trimIncompleteUtf8Suffix(buffer: Buffer): Buffer {
+  if (buffer.length === 0) return buffer;
+
+  let lead = buffer.length - 1;
+  while (lead >= 0 && (buffer[lead] & 0xc0) === 0x80) lead--;
+  if (lead < 0) return Buffer.alloc(0);
+
+  const leadByte = buffer[lead];
+  const expectedLength =
+    leadByte < 0x80
+      ? 1
+      : (leadByte & 0xe0) === 0xc0
+        ? 2
+        : (leadByte & 0xf0) === 0xe0
+          ? 3
+          : (leadByte & 0xf8) === 0xf0
+            ? 4
+            : 1;
+  const actualLength = buffer.length - lead;
+  return actualLength < expectedLength ? buffer.subarray(0, lead) : buffer;
+}
+
+/** Keep the last `maxBytes` of a buffer, trimming any incomplete UTF-8 sequence. */
+export function clampToTail(buf: Buffer, maxBytes: number): Buffer {
+  if (buf.length <= maxBytes) return buf;
+  return trimIncompleteUtf8Suffix(buf.subarray(buf.length - maxBytes));
+}

package/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { hasAnsi, stripAnsi } from "./ansi";
+export { clampToTail, trimIncompleteUtf8Suffix } from "./buffer";
 export { resolveShellExecutable, spawnCommand } from "./command-executor";
 export { formatRuntime, formatStatus, formatTimestamp } from "./format";
 export type { LineMatchMode } from "./match-line";