@aliou/pi-processes 0.10.2 → 0.10.3

package/extensions/processes/handlers/notifications.ts

@@ -60,10 +60,11 @@ export function registerNotificationDelivery(
       summary: `Suppressed ${count} log-match notifications because output was too fast.`,
       attention: "context",
     };
-    sendProcessNotificationMessage(pi, details, {
-      triggerTurn: false,
-      deliverAs: "steer",
-    });
+    sendProcessNotificationMessage(
+      pi,
+      details,
+      attentionToSendOptions(details.attention),
+    );
   };
 
   const flushSuppressedSummary = () => {

package/extensions/processes/notifications/service.ts

@@ -25,7 +25,10 @@ const DEFAULT_ATTENTION: Record<
   "onSuccess" | "onFailure" | "onKilled",
   Attention
 > = {
-  onSuccess: "context",
+  // Keep in sync with DEFAULT_NOTIFY_CONFIG in tools/notify.ts. Success
+  // defaults to a turn because "context" is only seen by an agent that is
+  // still streaming when the process ends.
+  onSuccess: "turn",
   onFailure: "turn",
   // External kills surface as context by default (see DEFAULT_NOTIFY_CONFIG
   // in tools/notify.ts for rationale). Intentional stops are classified

package/extensions/processes/tools/index.ts

@@ -54,7 +54,8 @@ export function registerProcessTool(
         "Manage long-running background processes: start, list, stop, write to stdin, update watches, clear finished entries, and inspect recent output. After starting a process, do not wait - notifications bring you back on exit and on log matches.",
       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. The process notifies you on exit (success, failure, killed) and on notify.logMatches matches, which brings you back.",
+        "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: 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

@@ -14,7 +14,13 @@ 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",
+  // 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".
+  onSuccess: "turn",
   onFailure: "turn",
   // External kills (outside this manager) surface as context by default so
   // the agent and user learn that a managed process disappeared. Intentional
@@ -36,11 +42,14 @@ export function normalizeNotifyConfig(input: unknown): NotifyConfig {
 
   return {
     onSuccess:
-      normalizeAttention(input.onSuccess, "notify.onSuccess") ?? "context",
+      normalizeAttention(input.onSuccess, "notify.onSuccess") ??
+      DEFAULT_NOTIFY_CONFIG.onSuccess,
     onFailure:
-      normalizeAttention(input.onFailure, "notify.onFailure") ?? "turn",
+      normalizeAttention(input.onFailure, "notify.onFailure") ??
+      DEFAULT_NOTIFY_CONFIG.onFailure,
     onKilled:
-      normalizeAttention(input.onKilled, "notify.onKilled") ?? "context",
+      normalizeAttention(input.onKilled, "notify.onKilled") ??
+      DEFAULT_NOTIFY_CONFIG.onKilled,
     logMatches: normalizeLogMatches(logMatches),
   };
 }

package/extensions/processes/tools/schema.ts

@@ -110,28 +110,25 @@ const WatchUpdateItemParams = Type.Object({
   ),
   on: Type.Optional(
     StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
-      description: "Agent attention for this log match. Defaults to turn.",
+      description: "Attention for this match. Defaults to turn.",
     }),
   ),
 });
 
-const NotifyParams = Type.Object({
+const NotifyProperties = {
   onSuccess: Type.Optional(
     StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
-      description:
-        "Agent attention when the process exits successfully. Defaults to context.",
+      description: "Attention on clean exit. Defaults to turn.",
     }),
   ),
   onFailure: Type.Optional(
     StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
-      description:
-        "Agent attention when the process fails or crashes. Defaults to turn.",
+      description: "Attention on failure or crash. Defaults to turn.",
     }),
   ),
   onKilled: Type.Optional(
     StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
-      description:
-        "Agent attention when the process is killed. Defaults to context.",
+      description: "Attention on external kill. Defaults to context.",
     }),
   ),
   logMatches: Type.Optional(
@@ -141,6 +138,11 @@ const NotifyParams = Type.Object({
         "Log match notifications. Supports at most 20 matchers, with each pattern limited to 500 characters.",
     }),
   ),
+};
+
+const NotifyParams = Type.Object(NotifyProperties, {
+  description:
+    "Notify settings. Attention: turn wakes an idle agent, context only reaches an agent still working, ignore never notifies.",
 });
 
 export const ProcessesParams = Type.Object({

package/package.json

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

package/skills/pi-processes/SKILL.md

@@ -15,9 +15,11 @@ A started process runs in the background and the manager brings you back when so
 2. End your turn or move on to other work. Do not call `process output` in a loop waiting for "ready".
 3. The process notifies you when:
    - a `logMatches` pattern hits (readiness, error, progress),
-   - the process exits successfully (`onSuccess`, default `context`),
+   - the process exits successfully (`onSuccess`, default `turn`),
    - the process fails or crashes (`onFailure`, default `turn`),
-   - the process is killed, by you or externally (`onKilled`, default `context`).
+   - the process is killed externally (`onKilled`, default `context`, which does not wake an idle agent).
+
+   Stopping a process yourself never notifies.
 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.
 
@@ -50,6 +52,8 @@ 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.
+
 Optional `cwd` sets the working directory for the spawned command. Omit it to inherit the agent's current working directory.
 
 Empty `logMatches` patterns (literal or regex) are rejected at start and update time. Use `mode: "regex"` only when literal matching is not enough, scope by `stream` to cut noise, and use `repeat: true` when a matcher should fire more than once.
@@ -214,9 +218,9 @@ Good:
 
 Exit attention:
 
-- `notify.onSuccess` — when the process exits successfully. Defaults to `context`.
-- `notify.onFailure` — when the process fails or crashes. Defaults to `turn`.
-- `notify.onKilled` — when the process is killed, by you or externally. Defaults to `context`.
+- `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.
 
 Log match watches (`notify.logMatches`, up to 20, each pattern up to 500 chars):
 
@@ -226,7 +230,13 @@ Log match watches (`notify.logMatches`, up to 20, each pattern up to 500 chars):
 - `repeat` — `false` (default) fires once; `true` fires on every match.
 - `on` — `turn`, `context`, or `ignore`. Overrides the default attention for that watch. Defaults to `turn`.
 
-`turn` interrupts with an agent message. `context` adds the notice as context without interrupting. `ignore` records the match silently.
+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.
+
+Use `context` only when nothing needs to happen in response.
 
 ## Use cases