@kvali/cli 0.6.1 → 0.6.3

package/README.md

@@ -27,10 +27,14 @@ kvali watch            # hooks and phone notifications only, e.g. in the backgro
 
 ## More
 
-- `kvali phone test` / `kvali phone off`; options `--private` (no project or step names in notifications), `--no-steps` (alerts only, no progress notifications), `--server <url>` for your own ntfy server.
+- `kvali phone test` / `kvali phone off`; options `--events needs-you,done,steps,actions,error,stuck` (what reaches the phone), `--done-after <seconds>` (the shortest task worth a notification; 0: every task), `--private` (no project or step names in notifications), `--server <url>` for your own ntfy server.
 - `kvali protocol [dir]` adds the progress protocol to a repository's `AGENTS.md` for agents Kvali has no adapter for (Cursor, Copilot, …).
 - `kvali --help` lists everything.
 
 Kvali also comes as an editor extension (VS Code, Antigravity, Cursor, Windsurf): search for "Kvali" in the Extensions view. Source and docs: https://github.com/webGrandpa/kvali
 
+Everything stays on your computer, with no telemetry; only phone notifications, when you set them up, go to the ntfy server you choose. [Privacy](https://github.com/webGrandpa/kvali/blob/main/PRIVACY.md) · [Security policy](https://github.com/webGrandpa/kvali/blob/main/SECURITY.md) · [Third-party notices](https://github.com/webGrandpa/kvali/blob/main/THIRD_PARTY_NOTICES.md)
+
 MIT © Giorgi Khiladze
+
+Kvali is an independent open-source project, not affiliated with or endorsed by Anthropic, OpenAI, Google, Microsoft or the makers of the other tools it works with. Claude Code, Codex, Gemini CLI, Antigravity, VS Code, Cursor, Windsurf and the other product names here are trademarks of their owners, used only to say what Kvali works with.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,64 @@
+# Third-party notices
+
+Kvali's own code is released under the [MIT License](LICENSE). The editor extension and the `kvali` command (npm package `@kvali/cli`) also bundle the open-source code listed below. Each keeps its own license, reproduced here as its terms require.
+
+| Package | Version | License | Where it is used |
+| --- | --- | --- | --- |
+| [Preact](https://github.com/preactjs/preact) | 10.29.8 | MIT | The editor extension's Agents view |
+| [qrcode-generator](https://github.com/kazuhikoarase/qrcode-generator) | 2.0.4 | MIT | The QR code for phone setup, in the extension and the CLI |
+
+The release build checks this list: it stops when the bundles contain a package, or a version, that is missing here.
+
+## preact 10.29.8
+
+The MIT License (MIT)
+
+Copyright (c) 2015-present Jason Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## qrcode-generator 2.0.4
+
+QR Code Generator for JavaScript
+
+Copyright (c) 2009 Kazuhiko Arase
+
+URL: http://www.d-project.com/
+
+Licensed under the MIT license:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The word "QR Code" is a registered trademark of DENSO WAVE INCORPORATED.

package/dist/claude-plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Giorgi Khiladze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/claude-plugin/README.md

@@ -13,7 +13,7 @@ It works wherever Claude Code runs: the terminal, the desktop app, the VS Code e
 
 ## On your phone
 
-With phone notifications set up (`kvali phone` or **Kvali: Send Notifications to My Phone** in the editor), the plugin sends this session's pushes through ntfy by itself, no editor needed: the turn's progress through its plan as one silent notification that each finished step updates (at most once a minute) and the turn's end replaces, and alerts when a question has waited a minute for your answer (one answered at the computer sends nothing), a turn of two minutes or more (or one whose progress you followed) finished, or stopped mid-plan and waited a minute, an error, or no data from the API. It reads the shared setup in `~/.kvali/config.json` once a minute.
+With phone notifications set up (`kvali phone` or **Kvali: Send Notifications to My Phone** in the editor), the plugin sends this session's pushes through ntfy by itself, no editor needed: the turn's progress through its plan as one silent notification that each finished step updates (at most once a minute) and the turn's end replaces, and alerts when a question has waited a minute for your answer (one answered at the computer sends nothing), a turn of two minutes or more (or one whose progress you followed) finished, or stopped mid-plan and waited a minute, an error, or no data from the API. It follows the choices made in Kvali's phone card or with `kvali phone --events` (each finished step, every action live, every task or only longer ones) and reads the shared setup in `~/.kvali/config.json` once a minute.
 
 ## With the Kvali editor extension
 
@@ -35,3 +35,9 @@ claude plugin test packages/claude-plugin
 ```
 
 `hooks/model.ts` holds the logic (plan, step timing, the "is it working?" line), `hooks/register.tsx` connects it to Claude Code's events and draws the pane, `types/index.d.ts` declares the state it keeps.
+
+## Privacy
+
+The plugin keeps its state on your computer and has no telemetry. It sends something only when you set up phone notifications: short status lines to the ntfy server you chose, never code or prompts. [Privacy](https://github.com/webGrandpa/kvali/blob/main/PRIVACY.md) · [Security policy](https://github.com/webGrandpa/kvali/blob/main/SECURITY.md) · MIT License
+
+Kvali is an independent open-source project, not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic, used only to say what this plugin works with.

package/dist/claude-plugin/hooks/model.ts

@@ -351,9 +351,11 @@ export const projectSlug = (dir: string): string => dir.replace(/[^a-zA-Z0-9]/g,
 
 // ---------- phone notifications (shared setup in ~/.kvali/config.json) ----------
 
-export type PhoneEvent = 'needs-you' | 'done' | 'error' | 'stuck' | 'steps'
-export type PhoneCfg = { server: string; topic: string; token?: string; events: PhoneEvent[]; details: boolean }
-const PHONE_EVENTS: readonly PhoneEvent[] = ['needs-you', 'done', 'error', 'stuck', 'steps']
+export type PhoneEvent = 'needs-you' | 'done' | 'error' | 'stuck' | 'steps' | 'actions'
+/** `doneAfterSec`: a turn's end is pushed when it took at least this long (0: every turn), or when the phone followed it. */
+export type PhoneCfg = { server: string; topic: string; token?: string; events: PhoneEvent[]; details: boolean; doneAfterSec: number }
+const PHONE_EVENTS: readonly PhoneEvent[] = ['needs-you', 'done', 'steps', 'actions', 'error', 'stuck']
+const DEFAULT_EVENTS: readonly PhoneEvent[] = ['needs-you', 'done', 'error', 'stuck', 'steps']
 
 /** Kvali 0.5 saved this list as its default, before progress existed: it reads as today's default. */
 const DEFAULT_EVENTS_V1: readonly PhoneEvent[] = ['needs-you', 'done', 'error', 'stuck']
@@ -368,10 +370,26 @@ export function parsePhoneConfig(text: string): PhoneCfg | undefined {
   }
   if (typeof r.topic !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(r.topic)) return undefined
   const server = typeof r.server === 'string' && /^https?:\/\/[^\s/]/.test(r.server) ? r.server.replace(/\/+$/, '') : 'https://ntfy.sh'
-  let events = Array.isArray(r.events) ? r.events.filter((e): e is PhoneEvent => PHONE_EVENTS.includes(e as PhoneEvent)) : [...PHONE_EVENTS]
+  let events = Array.isArray(r.events) ? r.events.filter((e): e is PhoneEvent => PHONE_EVENTS.includes(e as PhoneEvent)) : [...DEFAULT_EVENTS]
   const v1Default = events.length === DEFAULT_EVENTS_V1.length && DEFAULT_EVENTS_V1.every(e => events.includes(e))
-  if (r.v === undefined && v1Default) events = [...PHONE_EVENTS]
-  return { server, topic: r.topic, token: typeof r.token === 'string' && r.token ? r.token : undefined, events, details: r.details !== false }
+  if (r.v === undefined && v1Default) events = [...DEFAULT_EVENTS]
+  const doneAfterSec = typeof r.doneAfter === 'number' && Number.isFinite(r.doneAfter) && r.doneAfter >= 0 ? Math.min(Math.round(r.doneAfter), 86_400) : 120
+  return { server, topic: r.topic, token: typeof r.token === 'string' && r.token ? r.token : undefined, events, details: r.details !== false, doneAfterSec }
+}
+
+/** Silent updates pause while fewer messages than this are left for the day, so alerts still get through. */
+export const QUIET_RESERVE = 50
+
+/** Messages left for today from ntfy's `GET /v1/account`, when the server limits them (ntfy.sh: 250 a day per address). */
+export function messagesLeftOf(text: string): number | undefined {
+  try {
+    const a = JSON.parse(text) as { limits?: { messages?: number }; stats?: { messages_remaining?: number } }
+    const limit = a?.limits?.messages
+    const left = a?.stats?.messages_remaining
+    return typeof limit === 'number' && limit > 0 && typeof left === 'number' ? left : undefined
+  } catch {
+    return undefined
+  }
 }
 
 /** `sequence`: the notification it replaces (ntfy's sequence ID), so a turn's progress and its end are one notification. */
@@ -381,7 +399,7 @@ export type PushKind = 'needs-you' | 'finished' | 'paused' | 'error' | 'stalled'
 /** The words of a push, the same as the extension's. Without details no project or step names leave the computer. */
 export function phonePush(
   kind: PushKind,
-  info: { project: string; plan: KvPlan; label?: string; workedMs?: number; tokens?: number; quietMs?: number },
+  info: { project: string; plan: KvPlan; label?: string; workedMs?: number; tokens?: number; quietMs?: number; doing?: string },
   details: boolean,
 ): PhonePush {
   const where = details && info.project ? ` · ${info.project}` : ''
@@ -411,9 +429,16 @@ export function phonePush(
       }
     case 'step':
     {
+      // The turn's live notification: the plan's progress and, when chosen, the action running now.
       const next = step ? undefined : info.plan.tasks.find(t => t.status === 'pending')?.title
       const line = details ? (step ? `Now: ${truncate(step, 120)}` : next ? `Next: ${truncate(next, 120)}` : undefined) : undefined
-      return { title: `Claude Code${where} · ${p.done}/${p.total}`, message: lines(`${phoneBar(p.done, p.total)} ${p.percent}%`, line), priority: 2, tags: ['arrow_forward'] }
+      const doing = details && info.doing ? `Doing: ${truncate(info.doing, 120)}` : undefined
+      return {
+        title: p.total ? `Claude Code${where} · ${p.done}/${p.total}` : `Claude Code${where} · working`,
+        message: lines(p.total ? `${phoneBar(p.done, p.total)} ${p.percent}%` : undefined, line, doing) || 'Working',
+        priority: 2,
+        tags: ['arrow_forward'],
+      }
     }
   }
 }

package/dist/claude-plugin/hooks/register.tsx

@@ -36,6 +36,8 @@ import {
   totalTokens,
   turnSequence,
   typicalMs,
+  messagesLeftOf,
+  QUIET_RESERVE,
   type PhoneCfg,
   type PushKind,
 } from './model'
@@ -114,6 +116,12 @@ type Runtime = {
   progressSent: boolean
   /** A turn that stopped in the middle of its plan: pushed once it has waited like a question. */
   pendingPause: { at: number; workedMs: number; sequence?: string } | undefined
+  /** The last live update (a step or an action) and the action it showed. */
+  lastLivePushAt: number
+  sentAction: string | undefined
+  /** Messages the ntfy server still allows today (checked once a minute), to keep room for alerts. */
+  budgetAt: number
+  budgetLeft: number | undefined
   /** Ask Claude for a plan while there is none (`autoPlan` in ~/.kvali/config.json). */
   autoPlan: boolean
 }
@@ -151,6 +159,10 @@ const fresh = (): Runtime => ({
   progressSeenAt: 0,
   progressSent: false,
   pendingPause: undefined,
+  lastLivePushAt: 0,
+  sentAction: undefined,
+  budgetAt: -Infinity,
+  budgetLeft: undefined,
   autoPlan: true,
 })
 
@@ -209,7 +221,8 @@ async function doRefresh($: Engine, force: boolean): Promise<void> {
     quiet(push($, 'paused', { workedMs, sequence }))
   }
   const current = await read($, plan)
-  if (progressDue(current, now)) quiet(push($, 'step', { sequence: turnSeq(now) }))
+  const news = liveDue(current, now)
+  if (news) quiet(push($, 'step', { sequence: turnSeq(now), doing: news.doing }))
   const key = [l.phase, l.since, l.label ?? '', l.detail ?? ''].join('|')
   if (key !== rt.lastLiveKey || force) {
     rt.lastLiveKey = key
@@ -230,20 +243,53 @@ async function doRefresh($: Engine, force: boolean): Promise<void> {
  * count waits a moment first: Claude marks a task done and the next one in progress in two
  * calls, and the update should name the next one.
  */
-function progressDue(p: KvPlan, now: number): boolean {
+function liveDue(p: KvPlan, now: number): { doing?: string } | undefined {
   const pr = progress(p.tasks)
   if (pr.done < rt.progressSentDone) rt.progressSentDone = pr.done // a new plan
   if (pr.done !== rt.progressSeenDone) {
     rt.progressSeenDone = pr.done
     rt.progressSeenAt = now
   }
-  if (!rt.turnActive || !rt.phone?.events.includes('steps')) return false
-  if (pr.total === 0 || pr.done <= rt.progressSentDone || pr.done >= pr.total) return false
-  if (now - rt.lastStepPushAt < 60_000 || now - rt.progressSeenAt < 1_500) return false
-  rt.lastStepPushAt = now
-  rt.progressSentDone = pr.done
+  const events = rt.phone?.events ?? []
+  if (!rt.turnActive) return undefined
+  const stepNews =
+    events.includes('steps') &&
+    pr.total > 0 &&
+    pr.done > rt.progressSentDone &&
+    pr.done < pr.total &&
+    now - rt.lastStepPushAt >= 60_000 &&
+    now - rt.progressSeenAt >= 1_500
+  // With actions chosen: what runs now, at most twice a minute.
+  const action = [...rt.running.values()].filter(r => !r.asks).pop()
+  const actionKey = action ? `${action.label}|${action.startedAt}` : undefined
+  const actionNews = events.includes('actions') && actionKey !== undefined && actionKey !== rt.sentAction && now - rt.lastLivePushAt >= 30_000
+  if (!stepNews && !actionNews) return undefined
+  rt.lastLivePushAt = now
+  if (stepNews) {
+    rt.lastStepPushAt = now
+    rt.progressSentDone = pr.done
+  }
+  if (actionKey !== undefined) rt.sentAction = actionKey
   rt.progressSent = true
-  return true
+  return { doing: events.includes('actions') ? action?.label : undefined }
+}
+
+/** Silent updates are worth a message only while the day's allowance keeps room for alerts. */
+async function quietAllowed($: Engine, cfg: PhoneCfg): Promise<boolean> {
+  const now = await $.clock.now()
+  if (now - rt.budgetAt >= 60_000) {
+    rt.budgetAt = now
+    rt.budgetLeft = undefined
+    const headers: Record<string, string> = { Accept: 'application/json' }
+    if (cfg.token) headers.Authorization = `Bearer ${cfg.token}`
+    try {
+      const res = await $.http.fetch(`${cfg.server}/v1/account`, { headers })
+      if (res.ok) rt.budgetLeft = messagesLeftOf(res.text)
+    } catch {
+      // unknown: no limit to keep to
+    }
+  }
+  return rt.budgetLeft === undefined || rt.budgetLeft > QUIET_RESERVE
 }
 
 function turnSeq(now: number): string {
@@ -359,9 +405,12 @@ const PUSH_EVENT: Record<PushKind, 'needs-you' | 'done' | 'error' | 'stuck' | 's
 }
 
 /** Sends one push to the phone; a failure only costs that push. */
-async function push($: Engine, kind: PushKind, extra: { label?: string; workedMs?: number; quietMs?: number; sequence?: string } = {}): Promise<void> {
+async function push($: Engine, kind: PushKind, extra: { label?: string; workedMs?: number; quietMs?: number; sequence?: string; doing?: string } = {}): Promise<void> {
   const cfg = rt.phone
-  if (!cfg || !cfg.events.includes(PUSH_EVENT[kind])) return
+  if (!cfg) return
+  const wanted = kind === 'step' ? cfg.events.includes('steps') || cfg.events.includes('actions') : cfg.events.includes(PUSH_EVENT[kind])
+  if (!wanted) return
+  if (kind === 'step' && !(await quietAllowed($, cfg))) return
   const p = await read($, plan)
   const u = await read($, usage)
   const { sequence, ...info } = extra
@@ -369,7 +418,8 @@ async function push($: Engine, kind: PushKind, extra: { label?: string; workedMs
   const headers: Record<string, string> = { 'Content-Type': 'application/json' }
   if (cfg.token) headers.Authorization = `Bearer ${cfg.token}`
   try {
-    await $.http.fetch(cfg.server, { method: 'POST', headers, body })
+    const res = await $.http.fetch(cfg.server, { method: 'POST', headers, body })
+    if (res.ok && rt.budgetLeft !== undefined) rt.budgetLeft -= 1
   } catch {
     // offline or refused by policy: the pane still shows it
   }
@@ -558,7 +608,7 @@ export const register: Register = on => {
     if (phase === 'error') quiet(push($, 'error', { label: rt.ended.label, sequence }))
     // A turn the phone followed always gets its end; other turns only when they were long.
     // A stop in the middle of the plan asks the person something, so it waits like a question.
-    if (phase === 'done' && (e.durationMs >= LONG_TURN_MS || followed)) {
+    if (phase === 'done' && (e.durationMs >= (rt.phone?.doneAfterSec ?? 120) * 1000 || followed)) {
       const pr = progress((await read($, plan)).tasks)
       if (pr.total > 0 && pr.done < pr.total) rt.pendingPause = { at: now, workedMs: e.durationMs, sequence }
       else quiet(push($, 'finished', { workedMs: e.durationMs, sequence }))

package/dist/kvali.mjs

@@ -905,6 +905,7 @@ var AntigravityAdapter = class {
       agentLabel: this.label,
       id: st.id,
       title: st.task?.title || st.firstInput || current?.title || "Antigravity conversation",
+      titleFromPrompt: !st.task?.title && !!st.firstInput ? true : void 0,
       projectPath: this.projectOf(st, ctx.home),
       model: st.model,
       turn: st.turnStartedAt !== void 0 ? { steps: st.turnSteps, startedAt: st.turnStartedAt } : void 0,
@@ -1476,7 +1477,8 @@ var ClaudeCodeAdapter = class {
     }
     const activeSubagents = [...st.subagents.values()].filter((s) => now - s.updatedAt < 6e4).length;
     const window = /\[1m\]/i.test(st.model ?? "") || st.maxContext > 2e5 ? 1e6 : 2e5;
-    const title = st.customTitle || st.aiTitle || st.summary || st.firstPrompt || "Untitled session";
+    const ownTitle = st.customTitle || st.aiTitle || st.summary;
+    const title = ownTitle || st.firstPrompt || "Untitled session";
     let activity = status === "working" ? st.activity : void 0;
     if (status === "working" && st.phase === "tool" && st.open.size > 0) activity = [...st.open.values()].pop();
     return {
@@ -1485,6 +1487,7 @@ var ClaudeCodeAdapter = class {
       agentLabel: this.label,
       id: st.sessionId,
       title: truncate(title, 100),
+      titleFromPrompt: !ownTitle && !!st.firstPrompt ? true : void 0,
       projectPath: st.launchCwd ? findGitRoot(st.launchCwd) ?? st.launchCwd : void 0,
       cwd: st.launchCwd,
       model: st.model,
@@ -1824,6 +1827,7 @@ var CodexAdapter = class extends JsonlSessionAdapter {
       agentLabel: this.label,
       id: st.id,
       title: st.title ?? "Untitled session",
+      titleFromPrompt: st.title !== void 0 ? true : void 0,
       projectPath: st.cwd ? findGitRoot(st.cwd) ?? st.cwd : void 0,
       cwd: st.cwd,
       model: st.model,
@@ -2106,6 +2110,7 @@ var GeminiCliAdapter = class {
       agentLabel: this.label,
       id: st.sessionId ?? path5.basename(st.file),
       title: st.summary ? truncate(st.summary, 100) : title ?? "Untitled session",
+      titleFromPrompt: !st.summary && title !== void 0 ? true : void 0,
       projectPath: st.projectPath,
       model,
       status: phase === "idle" && tasksProg.total > 0 && tasksProg.done === tasksProg.total ? "done" : phase,
@@ -2444,7 +2449,22 @@ var HookHub = class {
       this.setHub(true);
     });
   }
+  /**
+   * A web page can make a browser call this port by pointing its own host name at
+   * 127.0.0.1 (DNS rebinding); such requests name that host, so only local names pass.
+   * Hooks call `http://127.0.0.1:<port>`.
+   */
+  localHost(req) {
+    const host = req.headers.host?.toLowerCase();
+    if (!host) return true;
+    const port = this.server?.address()?.port ?? this.port;
+    return host === `127.0.0.1:${port}` || host === `localhost:${port}` || host === `[::1]:${port}`;
+  }
   async handle(req, res) {
+    if (!this.localHost(req)) {
+      res.writeHead(403).end();
+      return;
+    }
     const url = req.url ?? "/";
     if (req.method === "GET" && url === "/v1/health") {
       res.writeHead(200, { "Content-Type": "application/json" });
@@ -3018,11 +3038,12 @@ async function removeSetup(home, env = {}, opts = {}) {
 import { randomBytes } from "node:crypto";
 import { promises as fsp8 } from "node:fs";
 import path14 from "node:path";
-var PHONE_EVENTS = ["needs-you", "done", "error", "stuck", "steps"];
+var PHONE_EVENTS = ["needs-you", "done", "steps", "actions", "error", "stuck"];
 var DEFAULT_PHONE_EVENTS = ["needs-you", "done", "error", "stuck", "steps"];
 var DEFAULT_EVENTS_V1 = ["needs-you", "done", "error", "stuck"];
 var PHONE_CONFIG_VERSION = 2;
 var DEFAULT_NTFY_SERVER = "https://ntfy.sh";
+var DEFAULT_DONE_AFTER_SEC = 120;
 var kvaliConfigFile = (home) => path14.join(home, ".kvali", "config.json");
 var TOPIC_RE = /^[A-Za-z0-9_-]{1,64}$/;
 function normalizePhoneConfig(raw) {
@@ -3033,7 +3054,8 @@ function normalizePhoneConfig(raw) {
   let events = Array.isArray(r.events) ? r.events.filter((e) => PHONE_EVENTS.includes(e)) : [...DEFAULT_PHONE_EVENTS];
   const v1Default = events.length === DEFAULT_EVENTS_V1.length && DEFAULT_EVENTS_V1.every((e) => events.includes(e));
   if (r.v === void 0 && v1Default) events = [...DEFAULT_PHONE_EVENTS];
-  return { server, topic: r.topic, token: typeof r.token === "string" && r.token ? r.token : void 0, events, details: r.details !== false };
+  const doneAfterSec = typeof r.doneAfter === "number" && Number.isFinite(r.doneAfter) && r.doneAfter >= 0 ? Math.min(Math.round(r.doneAfter), 86400) : DEFAULT_DONE_AFTER_SEC;
+  return { server, topic: r.topic, token: typeof r.token === "string" && r.token ? r.token : void 0, events, details: r.details !== false, doneAfterSec };
 }
 async function readPhoneConfig(home) {
   try {
@@ -3051,7 +3073,16 @@ async function writePhoneConfig(home, cfg) {
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) all = parsed;
   } catch {
   }
-  if (cfg) all.phone = { v: PHONE_CONFIG_VERSION, server: cfg.server, topic: cfg.topic, ...cfg.token ? { token: cfg.token } : {}, events: cfg.events, details: cfg.details };
+  if (cfg)
+    all.phone = {
+      v: PHONE_CONFIG_VERSION,
+      server: cfg.server,
+      topic: cfg.topic,
+      ...cfg.token ? { token: cfg.token } : {},
+      events: cfg.events,
+      details: cfg.details,
+      doneAfter: cfg.doneAfterSec ?? DEFAULT_DONE_AFTER_SEC
+    };
   else delete all.phone;
   await fsp8.mkdir(path14.dirname(file), { recursive: true });
   await fsp8.writeFile(file, `${JSON.stringify(all, null, 2)}
@@ -3130,7 +3161,7 @@ function formatPush(kind, s, details, extra = {}) {
   const stepName = step ? step.activeTitle ?? step.title : void 0;
   const nextName = step ? void 0 : s.tasks.find((t) => t.status === "pending")?.title;
   const planLine = p2.total ? `${p2.done}/${p2.total} tasks${details && stepName ? ` \xB7 ${clip(stepName, 80)}` : ""}` : void 0;
-  const title = details ? clip(s.title, 120) : void 0;
+  const title = details && !s.titleFromPrompt ? clip(s.title, 120) : void 0;
   const lines = (...xs) => xs.filter(Boolean).join("\n");
   switch (kind) {
     case "needs-you":
@@ -3189,14 +3220,17 @@ function formatPush(kind, s, details, extra = {}) {
         priority: 3,
         tags: ["hourglass"]
       };
-    case "step":
+    case "step": {
+      const doing = extra.action && s.activity && !s.activity.endedAt ? s.activity.label : void 0;
+      const stepLine = details ? stepName ? `Now: ${clip(stepName, 120)}` : nextName ? `Next: ${clip(nextName, 120)}` : void 0 : void 0;
       return {
-        event: "steps",
-        title: `${agent}${where} \xB7 ${p2.done}/${p2.total}`,
-        message: lines(`${phoneBar(p2.done, p2.total)} ${p2.percent}%`, details ? stepName ? `Now: ${clip(stepName, 120)}` : nextName ? `Next: ${clip(nextName, 120)}` : void 0 : void 0),
+        event: extra.action ? "actions" : "steps",
+        title: p2.total ? `${agent}${where} \xB7 ${p2.done}/${p2.total}` : `${agent}${where} \xB7 working`,
+        message: lines(p2.total ? `${phoneBar(p2.done, p2.total)} ${p2.percent}%` : void 0, stepLine, details && doing ? `Doing: ${clip(doing, 120)}` : void 0) || "Working",
         priority: 2,
         tags: ["arrow_forward"]
       };
+    }
   }
 }
 var PushPlanner = class {
@@ -3210,6 +3244,7 @@ var PushPlanner = class {
   troubleMs;
   stepEveryMs;
   progressSettleMs;
+  actionEveryMs;
   constructor(opts = {}) {
     this.now = opts.now ?? Date.now;
     this.startedAt = this.now();
@@ -3220,11 +3255,13 @@ var PushPlanner = class {
     this.troubleMs = opts.troubleMs ?? 2 * 6e4;
     this.stepEveryMs = opts.stepEveryMs ?? 6e4;
     this.progressSettleMs = opts.progressSettleMs ?? 2e3;
+    this.actionEveryMs = opts.actionEveryMs ?? 3e4;
   }
   observe(snapshot, cfg) {
     const now = this.now();
     const out = [];
     const want = (e) => cfg.events.includes(e);
+    const minWork = cfg.doneAfterSec !== void 0 ? cfg.doneAfterSec * 1e3 : this.minWorkMs;
     const seen = /* @__PURE__ */ new Set();
     for (const s of snapshot.sessions) {
       seen.add(s.key);
@@ -3263,7 +3300,7 @@ var PushPlanner = class {
       if (t.stoppedAt !== void 0 && (s.status === "done" || s.status === "idle") && now - t.stoppedAt >= this.settleMs) {
         const worked = t.workStart !== void 0 ? t.stoppedAt - t.workStart : 0;
         const interrupted = s.statusDetail === "Interrupted";
-        const worth = (worked >= this.minWorkMs || t.progressSent) && !interrupted && mine && want("done");
+        const worth = (worked >= minWork || t.progressSent) && !interrupted && mine && want("done");
         const unfinished = prog.total > 0 && prog.done < prog.total;
         if (!(worth && unfinished && now - t.stoppedAt < this.needsYouAfterMs)) {
           if (worth) out.push({ ...formatPush(unfinished ? "paused" : "finished", s, cfg.details, { workedMs: worked }), sequence: t.episode });
@@ -3286,8 +3323,8 @@ var PushPlanner = class {
           t.troublePushed = true;
           out.push(formatPush("trouble", s, cfg.details));
         } else if (mine && !s.pulse && t.troubleSince === void 0) {
-          const a = s.activity;
-          const running = !!a && !a.endedAt && a.kind !== "thinking" && a.kind !== "message";
+          const a2 = s.activity;
+          const running = !!a2 && !a2.endedAt && a2.kind !== "thinking" && a2.kind !== "message";
           const quietFor = now - Math.max(s.updatedAt, this.startedAt);
           if (!running && quietFor >= this.quietMs && t.quietPushedFor !== s.updatedAt) {
             t.quietPushedFor = s.updatedAt;
@@ -3300,12 +3337,19 @@ var PushPlanner = class {
         t.seenDone = prog.done;
         t.seenDoneAt = now;
       }
-      const stepDue = (t.lastStepPush === void 0 || now - t.lastStepPush >= this.stepEveryMs) && now - t.seenDoneAt >= this.progressSettleMs;
-      if (want("steps") && mine && active && prog.total > 0 && prog.done > t.sentDone && prog.done < prog.total && stepDue) {
-        t.lastStepPush = now;
-        t.sentDone = prog.done;
+      const stepNews = want("steps") && prog.total > 0 && prog.done > t.sentDone && prog.done < prog.total && now - t.seenDoneAt >= this.progressSettleMs && (t.lastStepPush === void 0 || now - t.lastStepPush >= this.stepEveryMs);
+      const a = s.activity;
+      const actionKey = a && !a.endedAt && a.kind !== "thinking" && a.kind !== "message" ? `${a.label}|${a.startedAt}` : void 0;
+      const actionNews = want("actions") && actionKey !== void 0 && actionKey !== t.sentAction && (t.lastLivePush === void 0 || now - t.lastLivePush >= this.actionEveryMs);
+      if (mine && active && (stepNews || actionNews)) {
+        t.lastLivePush = now;
+        if (stepNews) {
+          t.lastStepPush = now;
+          t.sentDone = prog.done;
+        }
+        if (actionKey !== void 0) t.sentAction = actionKey;
         t.progressSent = true;
-        out.push({ ...formatPush("step", s, cfg.details), sequence: t.episode });
+        out.push({ ...formatPush("step", s, cfg.details, { action: want("actions") }), sequence: t.episode });
       }
       t.status = s.status;
     }
@@ -3325,6 +3369,17 @@ function end(t, done) {
   t.progressSent = false;
   t.sentDone = done;
 }
+var QUIET_RESERVE = 50;
+async function messagesLeft(cfg, fetchImpl = fetch) {
+  const headers = { Accept: "application/json" };
+  if (cfg.token) headers.Authorization = `Bearer ${cfg.token}`;
+  const res = await fetchImpl(`${cfg.server}/v1/account`, { headers, signal: AbortSignal.timeout(1e4) });
+  if (!res.ok) return void 0;
+  const a = await res.json().catch(() => void 0);
+  const limit = a?.limits?.messages;
+  const left = a?.stats?.messages_remaining;
+  return typeof limit === "number" && limit > 0 && typeof left === "number" ? left : void 0;
+}
 var PhoneNotifier = class {
   cfg;
   mtime = -1;
@@ -3332,6 +3387,9 @@ var PhoneNotifier = class {
   timer;
   running;
   again = false;
+  left;
+  leftAt = -Infinity;
+  quietPaused = false;
   planner;
   opts;
   constructor(opts) {
@@ -3392,10 +3450,29 @@ var PhoneNotifier = class {
     if (!pushes.length || !this.opts.canSend()) return;
     const send = this.opts.send ?? sendPush;
     for (const p2 of pushes) {
+      if (p2.priority <= 2 && !await this.quietAllowed(cfg)) continue;
       const r = await send(cfg, p2);
+      if (r.ok && this.left !== void 0) this.left -= 1;
       this.opts.report?.(r.ok ? p2.title : `${p2.title}: ${r.error}`, r.ok);
     }
   }
+  /** Silent updates are worth a message only while the day's allowance keeps room for alerts. */
+  async quietAllowed(cfg) {
+    const now = Date.now();
+    if (now - this.leftAt >= 6e4) {
+      this.leftAt = now;
+      this.left = await (this.opts.budget ?? messagesLeft)(cfg).catch(() => void 0);
+    }
+    const ok = this.left === void 0 || this.left > QUIET_RESERVE;
+    if (ok === this.quietPaused) {
+      this.quietPaused = !ok;
+      this.opts.report?.(
+        ok ? "progress updates resumed" : `progress updates paused: ${this.left} notifications left today on ${new URL(cfg.server).host}, kept for alerts`,
+        ok
+      );
+    }
+    return ok;
+  }
 };
 
 // ../../node_modules/.pnpm/qrcode-generator@2.0.4/node_modules/qrcode-generator/dist/qrcode.mjs
@@ -5066,7 +5143,7 @@ function qrTerminal(text, color = true) {
 }
 
 // src/index.ts
-var VERSION = "0.6.1";
+var VERSION = "0.6.3";
 function parse(argv) {
   const opts = {
     json: false,
@@ -5078,7 +5155,9 @@ function parse(argv) {
     port: DEFAULT_HOOK_PORT,
     color: process2.stdout.isTTY && !process2.env.NO_COLOR,
     private: false,
-    steps: void 0
+    steps: void 0,
+    events: void 0,
+    doneAfter: void 0
   };
   const cmd = [];
   for (let i = 0; i < argv.length; i += 1) {
@@ -5136,6 +5215,19 @@ function parse(argv) {
       case "--no-steps":
         opts.steps = false;
         break;
+      case "--events": {
+        const list = next().split(",").map((e) => e.trim()).filter(Boolean);
+        const bad = list.filter((e) => !PHONE_EVENTS.includes(e));
+        if (bad.length) fail(`unknown event ${bad.join(", ")}: choose from ${PHONE_EVENTS.join(", ")}`);
+        opts.events = PHONE_EVENTS.filter((e) => list.includes(e));
+        break;
+      }
+      case "--done-after": {
+        const sec = Number(next());
+        if (!Number.isFinite(sec) || sec < 0) fail("--done-after needs a number of seconds (0: every task)");
+        opts.doneAfter = Math.round(sec);
+        break;
+      }
       case "--version":
       case "-v":
         console.log(VERSION);
@@ -5178,7 +5270,8 @@ Options
   --port <n>                  hook hub port (default ${DEFAULT_HOOK_PORT})
   --no-hub                    do not listen for hook events (and send no phone notifications)
   --no-color
-  kvali phone options: --server <url> (self-hosted ntfy)  --token <token>  --private (no project or step names)  --no-steps (no progress notifications)`;
+  kvali phone options: --server <url> (self-hosted ntfy)  --token <token>  --private (no project or step names)
+                              --events needs-you,done,steps,actions,error,stuck (what to hear about)  --done-after <seconds> (shortest task worth a notification; 0: every task)  --no-steps`;
 function fail(msg) {
   console.error(`kvali: ${msg}`);
   process2.exit(2);
@@ -5352,6 +5445,18 @@ function startPhone(engine, hub, home, report) {
   notifier.start();
   return notifier;
 }
+function phoneEventsText(cfg) {
+  const done = cfg.doneAfterSec ?? DEFAULT_DONE_AFTER_SEC;
+  const words = {
+    "needs-you": "a question that waited a minute",
+    done: done ? `tasks done after ${fmtDuration(done * 1e3)} or longer` : "every task done",
+    steps: "each finished step (silent)",
+    actions: "every action, live (silent)",
+    error: "errors",
+    stuck: "an agent gone silent"
+  };
+  return cfg.events.length ? PHONE_EVENTS.filter((e) => cfg.events.includes(e)).map((e) => words[e]).join(", ") : "nothing (no event chosen)";
+}
 async function phone(sub, opts) {
   const c = paint(opts.color);
   if (sub === "off") {
@@ -5373,8 +5478,10 @@ async function phone(sub, opts) {
   if (opts.server) cfg.server = opts.server.replace(/\/+$/, "");
   if (opts.token) cfg.token = opts.token;
   if (opts.private) cfg.details = false;
+  if (opts.events) cfg.events = opts.events;
   if (opts.steps === true && !cfg.events.includes("steps")) cfg.events.push("steps");
   if (opts.steps === false) cfg.events = cfg.events.filter((e) => e !== "steps");
+  if (opts.doneAfter !== void 0) cfg.doneAfterSec = opts.doneAfter;
   await writePhoneConfig(opts.home, cfg);
   const self = cfg.server !== "https://ntfy.sh";
   console.log(
@@ -5395,8 +5502,8 @@ async function phone(sub, opts) {
   console.log(
     [
       "",
-      "  You get an alert when an agent finishes, fails, goes quiet or has waited a minute for your answer.",
-      cfg.events.includes("steps") ? "  Each task also gets one silent notification that its finished steps update (--no-steps turns it off)." : "  Progress notifications are off (kvali phone --steps turns them on).",
+      `  You will hear about: ${phoneEventsText(cfg)}.`,
+      "  Choose with --events needs-you,done,steps,actions,error,stuck and --done-after <seconds>.",
       "  They are sent while Kvali runs: the editor extension, `kvali`, or `kvali watch` in the background.",
       "  Kvali's Claude Code plugin sends them for its own sessions by itself.",
       `  ${c.gray("Test: kvali phone test \xB7 Stop: kvali phone off")}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kvali/cli",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Live progress, tokens and phone alerts for AI coding agents (Claude Code, Codex, Gemini CLI, Antigravity), in your terminal.",
   "license": "MIT",
   "author": "Giorgi Khiladze (https://github.com/webGrandpa)",
@@ -17,7 +17,8 @@
     "kvali": "dist/kvali.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "engines": {
     "node": ">=20"