@haemmid/pi-processes 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning for public releases.
 
+## [0.9.1] - 2026-07-02
+
+### Added
+
+- `output`, `logs`, and `kill` accept either `id` or `name` as process selector.
+- `start` and `restart` return suggested next commands with `name="..."`.
+- Shared `resolveSelector` utility for consistent validation across actions.
+
+### Changed
+
+- Ambiguous name resolution now uses simpler error messages.
+- Tool description updated to mention id/name duality.
+
+### Fixed
+
+- `kill` test: message assertion updated for new ambiguous error format.
+
 ## [0.9.0] - 2026-07-01
 
 Initial public release of `@haemmid/pi-processes`.

package/README.md

@@ -173,22 +173,25 @@ process start "pnpm dev" name="backend-dev" cwd="/path/to/project"
 process restart "pnpm dev" name="backend-dev"
 process restart "pnpm dev" name="backend-dev" force=true
 process list
-process output id="backend-dev"
+process output id="proc_1"
+process output name="backend-dev"
 process logs id="proc_1"
+process logs name="backend-dev"
 process kill id="backend-dev"
-process kill id="proc_1" force=true
+process kill name="backend-dev" force=true
 process clear
 ```
 
 ### Field rules
 
 - `start`/`restart` require `command` and `name`.
-- `output`, `logs`, and `kill` require `id`.
+- `output`, `logs`, and `kill` accept either `id` (exact process ID) or `name` (process name).
 - `kill` accepts `force=true` to send `SIGKILL` instead of `SIGTERM`.
 - `start` refuses if a process with the same name is already running.
 - `restart` safely kills the existing process (awaited) before starting a new one.
 - `restart` accepts `force=true` to send `SIGKILL` instead of `SIGTERM`.
 - `start`/`restart` accept `cwd` to override the working directory (defaults to session cwd).
+- `output`, `logs`, and `kill` return an error if both `id` and `name` are provided.
 
 ## Killing processes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haemmid/pi-processes",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Agent-facing background process manager for Pi and pi-web automation workflows.",
   "license": "MIT",
   "type": "module",

package/src/tools/actions/kill.ts

@@ -1,66 +1,36 @@
 import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { sanitizeLine } from "../../utils";
+import { resolveSelector } from "./utils";
 
 interface KillParams {
   id?: string;
+  name?: string;
   force?: boolean;
 }
 
-function notFoundResult(id: string): ExecuteResult {
-  const message = `Process not found: ${id}`;
-  return {
-    content: [{ type: "text", text: message }],
-    details: {
-      action: "kill",
-      success: false,
-      message,
-    },
-  };
-}
-
-function ambiguousResult(
-  id: string,
-  matches: Array<{ id: string; name: string }>,
-): ExecuteResult {
-  const choices = matches
-    .map((match) => `${match.id} ("${sanitizeLine(match.name)}")`)
-    .join(", ");
-  const message =
-    `Process name is ambiguous: ${id}. ` +
-    `Use an exact process ID instead. Matches: ${choices}`;
-  return {
-    content: [{ type: "text", text: message }],
-    details: {
-      action: "kill",
-      success: false,
-      message,
-    },
-  };
-}
-
 export async function executeKill(
   params: KillParams,
   manager: ProcessManager,
 ): Promise<ExecuteResult> {
-  if (!params.id) {
+  const error = resolveSelector(params, manager);
+  if (error) {
+    return { ...error, details: { ...error.details, action: "kill" } };
+  }
+
+  const query = params.id || params.name || "";
+  const resolved = manager.resolve(query);
+  if (!resolved.ok) {
     return {
-      content: [{ type: "text", text: "Missing required parameter: id" }],
+      content: [{ type: "text", text: `Process not found: "${query}"` }],
       details: {
         action: "kill",
         success: false,
-        message: "Missing required parameter: id",
+        message: `Process not found: "${query}"`,
       },
     };
   }
 
-  const resolved = manager.resolve(params.id);
-  if (!resolved.ok) {
-    return resolved.reason === "ambiguous"
-      ? ambiguousResult(params.id, resolved.matches ?? [])
-      : notFoundResult(params.id);
-  }
-
   const proc = resolved.info;
   const force = params.force ?? false;
   const signal = force ? "SIGKILL" : "SIGTERM";

package/src/tools/actions/logs.ts

@@ -1,52 +1,31 @@
 import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { sanitizeLine } from "../../utils";
+import { resolveSelector } from "./utils";
 
 interface LogsParams {
   id?: string;
+  name?: string;
 }
 
 export function executeLogs(
   params: LogsParams,
   manager: ProcessManager,
 ): ExecuteResult {
-  if (!params.id) {
-    return {
-      content: [{ type: "text", text: "Missing required parameter: id" }],
-      details: {
-        action: "logs",
-        success: false,
-        message: "Missing required parameter: id",
-      },
-    };
+  const error = resolveSelector(params, manager);
+  if (error) {
+    return { ...error, details: { ...error.details, action: "logs" } };
   }
 
-  const resolved = manager.resolve(params.id);
+  const query = params.id || params.name || "";
+  const resolved = manager.resolve(query);
   if (!resolved.ok) {
-    if (resolved.reason === "ambiguous") {
-      const choices = (resolved.matches ?? [])
-        .map((match) => `${match.id} ("${sanitizeLine(match.name)}")`)
-        .join(", ");
-      const message =
-        `Process name is ambiguous: ${params.id}. ` +
-        `Use an exact process ID instead. Matches: ${choices}`;
-      return {
-        content: [{ type: "text", text: message }],
-        details: {
-          action: "logs",
-          success: false,
-          message,
-        },
-      };
-    }
-
-    const message = `Process not found: ${params.id}`;
     return {
-      content: [{ type: "text", text: message }],
+      content: [{ type: "text", text: `Process not found: "${query}"` }],
       details: {
         action: "logs",
         success: false,
-        message,
+        message: `Process not found: "${query}"`,
       },
     };
   }

package/src/tools/actions/output.ts

@@ -1,73 +1,39 @@
 import { configLoader } from "../../config";
-import {
-  type ExecuteResult,
-  LIVE_STATUSES,
-  type ResolveProcessResult,
-} from "../../constants";
+import { type ExecuteResult, LIVE_STATUSES } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { formatStatus, sanitizeLine } from "../../utils";
+import { resolveSelector } from "./utils";
 
 const MAX_BYTES = 50 * 1024; // 50KB
 
 interface OutputParams {
   id?: string;
-}
-
-function resolveProcessResult(
-  result: ResolveProcessResult,
-  action: "output" | "logs",
-  id: string,
-): ExecuteResult | null {
-  if (result.ok) return null;
-
-  if (result.reason === "ambiguous") {
-    const choices = (result.matches ?? [])
-      .map((match) => `${match.id} ("${sanitizeLine(match.name)}")`)
-      .join(", ");
-    const message =
-      `Process name is ambiguous: ${id}. ` +
-      `Use an exact process ID instead. Matches: ${choices}`;
-    return {
-      content: [{ type: "text", text: message }],
-      details: {
-        action,
-        success: false,
-        message,
-      },
-    };
-  }
-
-  const message = `Process not found: ${id}`;
-  return {
-    content: [{ type: "text", text: message }],
-    details: {
-      action,
-      success: false,
-      message,
-    },
-  };
+  name?: string;
 }
 
 export function executeOutput(
   params: OutputParams,
   manager: ProcessManager,
 ): ExecuteResult {
-  if (!params.id) {
+  const error = resolveSelector(params, manager);
+  if (error) {
+    return { ...error, details: { ...error.details, action: "output" } };
+  }
+
+  const query = params.id || params.name || "";
+  const resolved = manager.resolve(query);
+  if (!resolved.ok) {
+    // Should not reach here, but guard anyway
     return {
-      content: [{ type: "text", text: "Missing required parameter: id" }],
+      content: [{ type: "text", text: `Process not found: "${query}"` }],
       details: {
         action: "output",
         success: false,
-        message: "Missing required parameter: id",
+        message: `Process not found: "${query}"`,
       },
     };
   }
 
-  const resolved = manager.resolve(params.id);
-  if (!resolved.ok) {
-    return resolveProcessResult(resolved, "output", params.id) as ExecuteResult;
-  }
-
   const proc = resolved.info;
   const { defaultTailLines } = configLoader.getConfig().output;
   const output = manager.getOutput(proc.id, defaultTailLines);

package/src/tools/actions/restart.ts

@@ -3,6 +3,7 @@ import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { formatTimestamp, sanitizeLine } from "../../utils";
 import { executeKill } from "./kill";
+import { buildNextCommands } from "./utils";
 
 interface RestartParams {
   name?: string;
@@ -100,7 +101,12 @@ export async function executeRestart(
   }
 
   const startedAt = formatTimestamp(proc.startTime);
-  const message = `Restarted "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})\nStarted at: ${startedAt}\nLogs: ${proc.stdoutFile}`;
+  const message = [
+    `Restarted "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})`,
+    `Started at: ${startedAt}`,
+    `Logs: ${proc.stdoutFile}`,
+    buildNextCommands(proc.name),
+  ].join("\n");
   return {
     content: [{ type: "text", text: message }],
     details: {

package/src/tools/actions/start.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { formatTimestamp, sanitizeLine } from "../../utils";
+import { buildNextCommands } from "./utils";
 
 interface StartParams {
   name?: string;
@@ -59,7 +60,12 @@ export function executeStart(
     }
 
     const startedAt = formatTimestamp(proc.startTime);
-    const message = `Started "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})\nStarted at: ${startedAt}\nLogs: ${proc.stdoutFile}`;
+    const message = [
+      `Started "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})`,
+      `Started at: ${startedAt}`,
+      `Logs: ${proc.stdoutFile}`,
+      buildNextCommands(proc.name),
+    ].join("\n");
     return {
       content: [{ type: "text", text: message }],
       details: {

package/src/tools/actions/utils.ts

@@ -0,0 +1,104 @@
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { sanitizeLine } from "../../utils";
+
+interface SelectorParams {
+  id?: string;
+  name?: string;
+}
+
+export interface ResolvedProcess {
+  id: string;
+  name: string;
+}
+
+export function resolveSelector(
+  params: SelectorParams,
+  manager: ProcessManager,
+): ExecuteResult | null {
+  // Missing selector
+  if (!params.id && !params.name) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: 'Missing process selector. Use either id="proc_1" or name="backend-dev".',
+        },
+      ],
+      details: {
+        action: "output",
+        success: false,
+        message: "Missing process selector. Use either id or name.",
+      },
+    };
+  }
+
+  // Both specified
+  if (params.id && params.name) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Use either id or name, not both.",
+        },
+      ],
+      details: {
+        action: "output",
+        success: false,
+        message: "Use either id or name, not both.",
+      },
+    };
+  }
+
+  // Resolve by id or name
+  const query = params.id || params.name || "";
+  const resolved = manager.resolve(query);
+
+  if (resolved.ok) {
+    return null; // resolved successfully
+  }
+
+  if (resolved.reason === "ambiguous") {
+    const choices = (resolved.matches ?? [])
+      .map((match) => `${match.id} ("${sanitizeLine(match.name)}")`)
+      .join(", ");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Process name is ambiguous: "${query}". Use an exact process ID instead. Matches: ${choices}`,
+        },
+      ],
+      details: {
+        action: "output",
+        success: false,
+        message: `Process name is ambiguous: "${query}". Matches: ${choices}`,
+      },
+    };
+  }
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Process not found: "${query}"`,
+      },
+    ],
+    details: {
+      action: "output",
+      success: false,
+      message: `Process not found: "${query}"`,
+    },
+  };
+}
+
+export function buildNextCommands(name: string): string {
+  return [
+    "",
+    "Next commands:",
+    `  process output name="${name}"`,
+    `  process logs name="${name}"`,
+    `  process restart "<command>" name="${name}"`,
+    `  process kill name="${name}"`,
+  ].join("\n");
+}

package/src/tools/index.ts

@@ -26,7 +26,7 @@ const ProcessesParams = Type.Object({
   name: Type.Optional(
     Type.String({
       description:
-        "Friendly name for the process (required for start/restart, e.g. 'backend-dev', 'test-runner')",
+        "Friendly name for the process (required for start/restart; accepted for output/logs/kill as alternative to id)",
     }),
   ),
   cwd: Type.Optional(
@@ -38,7 +38,7 @@ const ProcessesParams = Type.Object({
   id: Type.Optional(
     Type.String({
       description:
-        "Exact process ID or exact friendly name to match (required for output/kill/logs).",
+        "Exact process ID (e.g. 'proc_1') or process name (for output/logs/kill as alternative to name)",
     }),
   ),
   force: Type.Optional(
@@ -57,10 +57,13 @@ export function setupProcessesTools(pi: ExtensionAPI, manager: ProcessManager) {
 
 Actions: start, list, output, logs, kill, clear, restart.
 - start/restart require 'name' and 'command' — restart kills existing process first
-- output/logs/kill require 'id' (exact process ID or exact friendly name)
+- output/logs/kill accept either 'id' (exact process ID) or 'name' (process name)
 - kill supports optional 'force=true' for SIGKILL
 - restart is preferred over start+kill: it safely awaits kill before starting new process
 
+Processes have both an exact process id (e.g. proc_1) and a stable name (e.g. astro-dev).
+For output/logs/kill, prefer name="..." when referring to a named dev server.
+
 Processes continue in the background. Use process output or process logs for a one-off snapshot when you need to inspect status. Do not poll repeatedly just to wait.
 Tool-triggered kills never notify.`,
     promptSnippet:
@@ -71,6 +74,7 @@ Tool-triggered kills never notify.`,
       "Use process output or process logs only for a one-off inspection, explicit user request, or debugging.",
       "Use process restart to replace an existing process — it safely awaits kill before starting the new one.",
       "Do not poll process output/list repeatedly just to wait for a process to finish.",
+      'For output/logs/kill, prefer name="..." when referring to a named dev server.',
     ],
 
     parameters: ProcessesParams,

package/src/utils/ansi.ts

@@ -41,7 +41,7 @@ export function stripAnsi(str: string): string {
   }
 
   // Strip terminal control chars like carriage return/backspace that can
-  // corrupt TUI layout when rendered back into pi.
+  // corrupt output formatting.
   return Array.from(clean)
     .filter((char) => {
       const code = char.codePointAt(0) ?? 0;
@@ -55,12 +55,11 @@ export function stripAnsi(str: string): string {
 }
 
 /**
- * Sanitize process output for single-line TUI rendering.
+ * Sanitize process output for single-line display.
  *
- * This is stricter than stripAnsi(): after terminal escapes are removed, any
- * remaining control bytes (carriage returns, backspaces, BEL, embedded
- * newlines, etc.) are dropped so process output cannot move the cursor or
- * alter Pi's surrounding TUI.
+ * After terminal escapes are removed, any remaining control bytes
+ * (carriage returns, backspaces, BEL, embedded newlines, etc.) are dropped
+ * so process output is safe for agent display.
  */
 export function sanitizeLine(str: string): string {
   return stripAnsi(str).replace(/\t/g, "  ");