@zeph-to/cli 2.16.0 → 2.17.0

package/README.md

@@ -664,6 +664,28 @@ others cannot: a turn with no tool calls, a turn with exactly one (a
 lone edit included — the gate wants two), and a turn whose calls were
 all reads. `/zeph-loud` still pushes on all of them.
 
+The Pi extension also pushes when pi is **waiting on you**: any blocking
+extension dialog — a bash guard's Run/Abort, an ask-user tool, a
+`ctx.ui.confirm` — that is still open 10 seconds after it appeared sends a
+`high` push ("pi asks: <project>", body = the dialog title or the guarded
+bash command). `high` gets through `quiet`; only `/zeph-mute` stops it.
+Answering inside the 10 seconds sends nothing. It is the pi twin of the
+Claude Code plugin's AskUserQuestion push, driven by pi's
+`ui_prompt_start` / `ui_prompt_end` events. Only dialogs that open while a
+turn is running count: a settings picker you open yourself between turns
+(`/caveman config`) never pushes.
+
+Two more end-of-turn cases differ from Claude Code:
+
+- **Push Signal markers** — pi's rules teach the same `<!-- zeph: skip|push|high -->`
+  markers, and the extension reads them from the final assistant message
+  (then strips them, since pi's terminal would otherwise print the comment).
+  `high` is how pi gets a "the turn ended with a question for you" push
+  through `quiet`.
+- **Errors and aborts** — a turn that ended on a provider error sends a
+  `high` "pi stopped: <project>" push with the error text instead of
+  "Task done"; a turn you aborted with Esc sends nothing.
+
 #### Quiet while away
 
 `quiet` silences routine pushes because you are watching the pane. When
@@ -789,7 +811,7 @@ try {
 | Copilot CLI | Session end hook + rules |
 | Cline | Rules file (`~/.cline/rules/zeph.md`) |
 | Aider | Conventions file + `read:` directive in `~/.aider.conf.yml` |
-| Pi | Extension (settle hook + remote detection) + rules — no MCP (pi has none; rules map zeph tools to the CLI) |
+| Pi | Extension (settle hook + waiting-on-you push + remote detection) + rules — no MCP (pi has none; rules map zeph tools to the CLI) |
 | OpenCode | MCP server + idle-notify plugin + rules |
 
 For remote-control via `zeph listener` the per-agent setup is the same

package/dist/templates.d.ts

@@ -1,3 +1,5 @@
+/** Grace before the pi extension turns an unanswered prompt into a push. Exported for the tests. */
+export declare const PI_PROMPT_GRACE_MS = 10000;
 /** Cursor — written to ~/.cursor/rules/zeph.mdc (needs .mdc frontmatter). No prompt hook. */
 export declare const CURSOR_RULE: string;
 /** Windsurf — appended into ~/.codeium/windsurf/memories/global_rules.md. No prompt hook. */
@@ -12,7 +14,7 @@ export declare const COPILOT_RULE: string;
 export declare const CLINE_RULE: string;
 /** Aider — standalone conventions file via .aider.conf.yml `read:` (no Stop hook, no prompt hook). */
 export declare const AIDER_RULE: string;
-/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook (PI_EXTENSION). */
+/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook + waiting-on-you push (PI_EXTENSION). */
 export declare const PI_RULE: string;
 /** OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook (v1). */
 export declare const OPENCODE_RULE: string;

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AA6KA,6FAA6F;AAC7F,eAAO,MAAM,WAAW,QAKtB,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,aAAa,QAIxB,CAAC;AAEH,0FAA0F;AAC1F,eAAO,MAAM,WAAW,QAAyE,CAAC;AAElG,uFAAuF;AACvF,eAAO,MAAM,UAAU,QAAyE,CAAC;AAEjG,oGAAoG;AACpG,eAAO,MAAM,YAAY,QAIvB,CAAC;AAEH,gFAAgF;AAChF,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,sGAAsG;AACtG,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,6GAA6G;AAC7G,eAAO,MAAM,OAAO,QAIlB,CAAC;AAEH,2GAA2G;AAC3G,eAAO,MAAM,aAAa,QAIxB,CAAC;AAIH,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;CAuBxB,CAAC;AAYF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;CASvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,OAUhD,CAAC;AAEF,eAAO,MAAM,aAAa,QASf,CAAC;AAQZ,2FAA2F;AAC3F,eAAO,MAAM,YAAY,QAsDxB,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,eAAe,QAwG3B,CAAC;AASF,eAAO,MAAM,eAAe,oFAA+E,CAAC;AAC5G,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAQjD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,KAAG,MAWnE,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAOrD,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AA+FA,oGAAoG;AACpG,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAoHzC,6FAA6F;AAC7F,eAAO,MAAM,WAAW,QAKtB,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,aAAa,QAIxB,CAAC;AAEH,0FAA0F;AAC1F,eAAO,MAAM,WAAW,QAAyE,CAAC;AAElG,uFAAuF;AACvF,eAAO,MAAM,UAAU,QAAyE,CAAC;AAEjG,oGAAoG;AACpG,eAAO,MAAM,YAAY,QAIvB,CAAC;AAEH,gFAAgF;AAChF,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,sGAAsG;AACtG,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,mIAAmI;AACnI,eAAO,MAAM,OAAO,QAKlB,CAAC;AAEH,2GAA2G;AAC3G,eAAO,MAAM,aAAa,QAIxB,CAAC;AAIH,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;CAuBxB,CAAC;AAYF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;CASvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,OAUhD,CAAC;AAEF,eAAO,MAAM,aAAa,QASf,CAAC;AAQZ,2FAA2F;AAC3F,eAAO,MAAM,YAAY,QAgJxB,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,eAAe,QAwG3B,CAAC;AASF,eAAO,MAAM,eAAe,oFAA+E,CAAC;AAC5G,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAQjD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,KAAG,MAWnE,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAOrD,CAAC"}

package/dist/templates.js

@@ -26,7 +26,7 @@
 // Keeping this in one place means a rule change lands everywhere at once
 // and the agents can't drift apart.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.removeManagedBlock = exports.upsertManagedBlock = exports.ZEPH_MARK_END = exports.ZEPH_MARK_START = exports.OPENCODE_PLUGIN = exports.PI_EXTENSION = exports.COPILOT_HOOKS = exports.isZephHookGroup = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_HOOKS = exports.OPENCODE_RULE = exports.PI_RULE = exports.AIDER_RULE = exports.CLINE_RULE = exports.COPILOT_RULE = exports.CODEX_RULE = exports.GEMINI_RULE = exports.WINDSURF_RULE = exports.CURSOR_RULE = void 0;
+exports.removeManagedBlock = exports.upsertManagedBlock = exports.ZEPH_MARK_END = exports.ZEPH_MARK_START = exports.OPENCODE_PLUGIN = exports.PI_EXTENSION = exports.COPILOT_HOOKS = exports.isZephHookGroup = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_HOOKS = exports.OPENCODE_RULE = exports.PI_RULE = exports.AIDER_RULE = exports.CLINE_RULE = exports.COPILOT_RULE = exports.CODEX_RULE = exports.GEMINI_RULE = exports.WINDSURF_RULE = exports.CURSOR_RULE = exports.PI_PROMPT_GRACE_MS = void 0;
 const gate_js_1 = require("./gate.js");
 const zeph_core_generated_js_1 = require("./zeph-core.generated.js");
 // Graceful resolution: prefer the installed `zeph` CLI, but fall back to
@@ -73,6 +73,19 @@ const TURN_FACT_FLAGS = ` --${gate_js_1.TOOL_COUNT_FLAG} \${tools} --${gate_js_1
 // stderr is discarded; `|| true` keeps a broken install from ever blocking
 // a prompt.
 const remoteHookCmd = (agent) => `$(command -v zeph || echo "npx -y @zeph-to/cli") remote-hook ${agent} 2>/dev/null || true`;
+// One-off `high` push from the pi extension — a prompt left waiting (the twin
+// of the plugin's zeph-ask.sh) or a turn that died on an error. `high` gets
+// through the quiet dial, and plain `notify` (no --auto) means only a mute
+// stops it. Title and body arrive as env vars, never spliced into the string:
+// the body can carry the model's own bash command or a provider error.
+const highNotifyCmd = '$(command -v zeph || echo "npx -y @zeph-to/cli") notify'
+    + ' --title "$ZEPH_PUSH_TITLE" --body "$ZEPH_PUSH_BODY" --priority high 2>/dev/null || true';
+// The pi turn's Push Signal marker, as a JS template placeholder (single quotes:
+// `${marker}` must reach the artifact unexpanded). The artifact only ever
+// assigns it a word the marker regex captured, or "none".
+const PUSH_SIGNAL_FLAG = ' --marker ${marker}';
+/** Grace before the pi extension turns an unanswered prompt into a push. Exported for the tests. */
+exports.PI_PROMPT_GRACE_MS = 10_000;
 // ── Shared behavioral core ───────────────────────────────────────
 //
 // GENERATED from plugin/docs/CORE_RULES.md — see src/zeph-core.generated.ts
@@ -137,10 +150,31 @@ tool instead — same semantics:
   unreachable) is a Done-like outcome — treat it as NORMAL.
 - zeph_notify → \`zeph notify --title "…" --body "…" [--priority high]\`
 - AskUserQuestion → pi's own terminal prompt.`;
+// Push Signal preamble — pi only. The shared core has no Push Signal section:
+// Claude Code gets it from the plugin's SessionStart hook, per push dial. The
+// pi extension reads the same markers (PI_EXTENSION, message_end), so pi's
+// rules carry a dial-independent version here.
+const PI_PUSH_SIGNAL = `## Push Signal — steer the end-of-turn push
+
+When a turn ends, the zeph extension decides whether to push by tool volume
+and the user's push dial. Put ONE marker anywhere in your final response to
+override that for this turn. The extension removes it before the message is
+shown or kept:
+
+- \`<!-- zeph: high -->\` — push at high priority. The only marker that gets
+  through the quiet dial, so use it whenever the user must act: you ended the
+  turn with a question for them, or you are blocked on a decision only they
+  can make. Never on routine completions.
+- \`<!-- zeph: push -->\` — push a turn the heuristic would skip.
+- \`<!-- zeph: skip -->\` — no push for a turn not worth a ping.
+
+No marker → the heuristic: fewer than 2 tool calls, or only read-only ones,
+stays silent. Markers are lowercase and exact.`;
 /** Assemble a full rule document from optional frontmatter + preambles + core. */
 const buildRule = (opts) => {
     const fm = opts.frontmatter ? `${opts.frontmatter}\n\n` : '';
     const tools = opts.toolAccess ? `${opts.toolAccess}\n\n` : '';
+    const signal = opts.pushSignal ? `${opts.pushSignal}\n\n` : '';
     const entry = opts.remoteEntry ? `${opts.remoteEntry}\n\n` : '';
     return `${fm}# Zeph — Remote-Control Rules
 
@@ -150,7 +184,7 @@ the user.
 
 ${opts.notify}
 
-${tools}${entry}${opts.core}
+${tools}${signal}${entry}${opts.core}
 `;
 };
 // ── Per-agent rule documents ─────────────────────────────────────
@@ -193,10 +227,11 @@ exports.AIDER_RULE = buildRule({
     remoteEntry: REMOTE_ENTRY_NO_HOOK,
     core: zeph_core_generated_js_1.ZEPH_CORE_RULE_ONLY,
 });
-/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook (PI_EXTENSION). */
+/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook + waiting-on-you push (PI_EXTENSION). */
 exports.PI_RULE = buildRule({
     notify: HOOK_DRIVEN_NOTIFY,
     toolAccess: PI_TOOL_ACCESS,
+    pushSignal: PI_PUSH_SIGNAL,
     core: zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN,
 });
 /** OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook (v1). */
@@ -320,20 +355,108 @@ const sh = (cmd: string, cwd: string, stdin?: string): Promise<string> =>
 // an unknown tool errs toward pushing rather than toward silence.
 const READ_ONLY = new Set(["read", "grep", "find", "ls"]);
 
+// How long a blocking prompt may stay open before it becomes a push. An answer
+// inside the window means the user is at the terminal, and a guard extension
+// can raise several prompts a turn — pushing each one at once would be noise.
+const PROMPT_GRACE_MS = ${exports.PI_PROMPT_GRACE_MS};
+
+// Push Signal markers — the pattern the Claude Code Stop hook reads
+// (plugin/hooks/zeph-stop.sh MARKER_RE). pi's markdown renders an HTML comment
+// as plain text, so message_end also strips it from what the user sees.
+const MARKER_RE = /<!--[ \\t]*zeph:[ \\t]*(skip|push|high)[ \\t]*-->/g;
+
+const projectOf = (cwd: string): string => cwd.split("/").pop() || cwd;
+
+// Fire-and-forget: never block pi on the notify network call.
+const pushHigh = (cwd: string, title: string, body: string): void => {
+  const env = {
+    ...process.env,
+    ZEPH_PUSH_TITLE: title,
+    ZEPH_PUSH_BODY: body.length > 200 ? body.slice(0, 199) + "…" : body,
+  };
+  const child = spawn("sh", ["-c", ${JSON.stringify(highNotifyCmd)}], { cwd, env, stdio: "ignore", detached: true });
+  child.on("error", () => {});
+  child.unref();
+};
+
 export default function (pi: ExtensionAPI) {
   // Turn facts for the push gate. One agent per process, so plain counters
   // suffice — no session keying.
   let tools = 0;
   let nonReadonly = 0;
+  // The tool call in flight. tool_execution_start fires before pi runs the
+  // tool_call handlers, so a guard's prompt always finds its own call here.
+  let running: { toolName: string; args: any } | undefined;
+  let promptTimer: ReturnType<typeof setTimeout> | undefined;
+  // A prompt only counts inside a turn. Outside one it is a dialog the user
+  // opened at the terminal themselves (/caveman config, a settings picker).
+  let agentRunning = false;
+  // This turn's Push Signal, and why its last assistant message stopped.
+  let marker = "none";
+  let stop: { reason: string; error?: string } | undefined;
 
+  pi.on("agent_start", () => {
+    agentRunning = true;
+  });
+  pi.on("message_end", (event) => {
+    const message = event.message;
+    if (message.role !== "assistant") return;
+    stop = { reason: message.stopReason, error: message.errorMessage };
+    let found = false;
+    const content = message.content.map((part) => {
+      if (part.type !== "text") return part;
+      const text = part.text.replace(MARKER_RE, (_match: string, word: string) => {
+        marker = word;
+        found = true;
+        return "";
+      });
+      return text === part.text ? part : { ...part, text: text.trimEnd() };
+    });
+    if (found) return { message: { ...message, content } };
+  });
+  pi.on("tool_execution_start", (event) => {
+    running = event;
+  });
   pi.on("tool_execution_end", (event) => {
+    running = undefined;
     tools += 1;
     if (!READ_ONLY.has(event.toolName)) nonReadonly += 1;
   });
+  // Waiting-on-you: pi fires ui_prompt_start for every blocking extension
+  // dialog (select/confirm/input/editor/custom — bash guards, ask-user tools).
+  // A custom dialog carries no title, so name the call that raised it instead.
+  pi.on("ui_prompt_start", (event, ctx) => {
+    clearTimeout(promptTimer);
+    if (!agentRunning) return;
+    const command = running?.toolName === "bash" ? running.args?.command : undefined;
+    const body = event.title
+      ?? (typeof command === "string" ? "$ " + command : undefined)
+      ?? (running ? running.toolName + " is waiting for your answer" : "Waiting for your input");
+    promptTimer = setTimeout(() => {
+      promptTimer = undefined;
+      pushHigh(ctx.cwd, "pi asks: " + projectOf(ctx.cwd), body);
+    }, PROMPT_GRACE_MS);
+    promptTimer.unref?.();
+  });
+  pi.on("ui_prompt_end", () => {
+    clearTimeout(promptTimer);
+    promptTimer = undefined;
+  });
   // Stop-equivalent: agent_settled fires once per user turn, after retries/compaction.
   // Fire-and-forget: never block pi's turn-end on the notify network call.
   pi.on("agent_settled", (_event, ctx) => {
-    const child = spawn("sh", ["-c", ${notifyCmdLiteral(TURN_FACT_FLAGS)}], { cwd: ctx.cwd, stdio: "ignore", detached: true });
+    agentRunning = false;
+    clearTimeout(promptTimer);
+    promptTimer = undefined;
+    // Esc (at the terminal, or a key sent from the phone): whoever stopped the
+    // turn is already looking at it.
+    if (stop?.reason === "aborted") return;
+    // A turn that died on a provider error is a blocker, not a completion.
+    if (stop?.reason === "error") {
+      pushHigh(ctx.cwd, "pi stopped: " + projectOf(ctx.cwd), stop.error || "The model request failed");
+      return;
+    }
+    const child = spawn("sh", ["-c", ${notifyCmdLiteral(TURN_FACT_FLAGS + PUSH_SIGNAL_FLAG)}], { cwd: ctx.cwd, stdio: "ignore", detached: true });
     child.on("error", () => {});
     child.unref();
   });
@@ -343,6 +466,8 @@ export default function (pi: ExtensionAPI) {
   pi.on("before_agent_start", async (event, ctx) => {
     tools = 0;
     nonReadonly = 0;
+    marker = "none";
+    stop = undefined;
     const out = await sh(${JSON.stringify(remoteHookCmd('pi'))}, ctx.cwd,
       JSON.stringify({ prompt: event.prompt, cwd: ctx.cwd }));
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/cli",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Zeph CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",