@aliou/pi-processes 0.11.1 → 0.11.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-processes",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "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
 {