@herbertgao/pi-bark 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Herbert Gao
+
+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/README.md

@@ -0,0 +1,44 @@
+# @herbertgao/pi-bark
+
+Bark notifications for user-facing Pi sessions. It sends a notification when Pi fully settles and when [`@juicesharp/rpiv-ask-user-question`](https://github.com/juicesharp/rpiv-mono) opens a questionnaire. Requests follow Bark's official [POST form API](https://github.com/Finb/Bark/blob/master/docs/en-us/tutorial.md#request-methods).
+
+## Install
+
+```bash
+pi install npm:@herbertgao/pi-bark
+```
+
+The extension is also included in `@herbertgao/pi-extensions`.
+
+## Configure
+
+Create `$PI_CODING_AGENT_DIR/bark.json` (normally `~/.pi/agent/bark.json`):
+
+```json
+{
+  "endpoint": "https://api.day.app/your-device-key",
+  "machine": "MacBook Pro M1 Max",
+  "locale": "zh-CN",
+  "events": {
+    "agentSettled": true,
+    "askUserQuestion": true
+  },
+  "params": {
+    "group": "pi",
+    "icon": "https://raw.githubusercontent.com/HerbertGao/pi-extensions/master/packages/pi-bark/assets/pi-icon.png"
+  },
+  "timeoutMs": 4000
+}
+```
+
+`endpoint` is required. `locale` accepts `auto` (default), `zh-CN`, `zh-TW`, or `en`; unsupported languages fall back to English. `params` accepts additional Bark POST parameters such as `group`, `sound`, `icon`, and `level`; dynamic `title` and `body` values always take precedence. Set `"enabled": false` to disable all notifications without removing the package.
+
+The notification body uses `💻` for the configured machine name and `📁` for Pi's full working directory. Questionnaire text is intentionally not sent because it may contain sensitive context. Only sessions with a user-facing UI notify, so nested `pi-subagents` sessions do not create duplicate pushes.
+
+The bundled [`assets/pi-icon.png`](assets/pi-icon.png) is a 512×512 rasterization of Pi's official [square badge](https://pi.dev/favicon.svg) from the [Pi Press Kit](https://pi.dev/press-kit), suitable for Bark's iOS 15+ `icon` parameter.
+
+Keep `bark.json` private because the endpoint normally contains the Bark device key. Restart Pi or run `/reload` after changing it.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@herbertgao/pi-bark",
+  "version": "0.1.0",
+  "description": "Send Bark notifications when Pi finishes or needs user input.",
+  "keywords": [
+    "bark",
+    "notifications",
+    "pi-extension",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/HerbertGao/pi-extensions/tree/master/packages/pi-bark#readme",
+  "bugs": {
+    "url": "https://github.com/HerbertGao/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Herbert Gao",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HerbertGao/pi-extensions.git",
+    "directory": "packages/pi-bark"
+  },
+  "files": [
+    "assets",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "x-origin": "original"
+}

package/src/index.ts

@@ -0,0 +1,178 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import { readFileSync } from "node:fs"
+import { homedir, hostname } from "node:os"
+import { join } from "node:path"
+
+const ASK_USER_PROMPT_EVENT = "rpiv:ask-user:prompt"
+const DEFAULT_TIMEOUT_MS = 4_000
+
+export type BarkLocale = "en" | "zh-CN" | "zh-TW"
+type NotificationEvent = "agentSettled" | "askUserQuestion"
+
+const COPY: Record<BarkLocale, Record<NotificationEvent, string>> = {
+  en: {
+    agentSettled: "✅ Pi finished",
+    askUserQuestion: "🟡 Pi needs your input",
+  },
+  "zh-CN": {
+    agentSettled: "✅ Pi 跑完了",
+    askUserQuestion: "🟡 Pi 等你回答",
+  },
+  "zh-TW": {
+    agentSettled: "✅ Pi 已完成",
+    askUserQuestion: "🟡 Pi 等你回覆",
+  },
+}
+
+export interface BarkConfig {
+  endpoint: string
+  machine: string
+  locale: BarkLocale
+  events: {
+    agentSettled: boolean
+    askUserQuestion: boolean
+  }
+  params: Record<string, string | number | boolean>
+  timeoutMs: number
+}
+
+export function getConfigPath(): string {
+  return join(
+    process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"),
+    "bark.json",
+  )
+}
+
+export function resolveLocale(input: unknown): BarkLocale {
+  const requested =
+    typeof input === "string" && input.toLowerCase() !== "auto"
+      ? input
+      : Intl.DateTimeFormat().resolvedOptions().locale
+  const locale = requested.toLowerCase()
+  if (locale.includes("hant") || /^zh-(tw|hk|mo)/.test(locale)) return "zh-TW"
+  if (locale.startsWith("zh")) return "zh-CN"
+  return "en"
+}
+
+export function notificationTitle(
+  locale: BarkLocale,
+  event: NotificationEvent,
+): string {
+  return COPY[locale][event]
+}
+
+export function normalizeConfig(input: unknown): BarkConfig | undefined {
+  if (!input || typeof input !== "object") return undefined
+  const source = input as Record<string, unknown>
+  if (source.enabled === false || typeof source.endpoint !== "string")
+    return undefined
+
+  try {
+    const protocol = new URL(source.endpoint).protocol
+    if (protocol !== "http:" && protocol !== "https:") return undefined
+  } catch {
+    return undefined
+  }
+
+  const eventSource =
+    source.events && typeof source.events === "object"
+      ? (source.events as Record<string, unknown>)
+      : {}
+  const params =
+    source.params && typeof source.params === "object"
+      ? Object.fromEntries(
+          Object.entries(source.params).filter((entry) =>
+            ["string", "number", "boolean"].includes(typeof entry[1]),
+          ),
+        )
+      : {}
+  const timeoutMs =
+    typeof source.timeoutMs === "number" &&
+    Number.isFinite(source.timeoutMs) &&
+    source.timeoutMs > 0
+      ? source.timeoutMs
+      : DEFAULT_TIMEOUT_MS
+
+  return {
+    endpoint: source.endpoint,
+    machine:
+      typeof source.machine === "string" && source.machine.trim()
+        ? source.machine.trim()
+        : hostname(),
+    locale: resolveLocale(source.locale),
+    events: {
+      agentSettled: eventSource.agentSettled !== false,
+      askUserQuestion: eventSource.askUserQuestion !== false,
+    },
+    params,
+    timeoutMs,
+  }
+}
+
+export function loadConfig(path = getConfigPath()): BarkConfig | undefined {
+  try {
+    return normalizeConfig(JSON.parse(readFileSync(path, "utf8")))
+  } catch {
+    return undefined
+  }
+}
+
+export function formatBody(config: BarkConfig, cwd: string): string {
+  return `💻 ${config.machine}\n📁 ${cwd}`
+}
+
+export async function sendBark(
+  config: BarkConfig,
+  title: string,
+  body: string,
+  fetcher: typeof fetch = fetch,
+): Promise<void> {
+  const form = new URLSearchParams()
+  for (const [key, value] of Object.entries(config.params))
+    form.set(key, String(value))
+  form.set("title", title)
+  form.set("body", body)
+
+  const response = await fetcher(config.endpoint, {
+    method: "POST",
+    body: form,
+    signal: AbortSignal.timeout(config.timeoutMs),
+  })
+  if (!response.ok) throw new Error(`Bark returned HTTP ${response.status}`)
+}
+
+export default function piBark(pi: ExtensionAPI): void {
+  let config: BarkConfig | undefined
+  let cwd = process.cwd()
+  let userFacingSession = false
+
+  const notify = async (title: string): Promise<void> => {
+    if (!config || !userFacingSession) return
+    try {
+      await sendBark(config, title, formatBody(config, cwd))
+    } catch {
+      // Notifications are best-effort and must never interrupt Pi.
+    }
+  }
+
+  const unsubscribeAskUser = pi.events.on(ASK_USER_PROMPT_EVENT, () => {
+    if (config?.events.askUserQuestion)
+      void notify(notificationTitle(config.locale, "askUserQuestion"))
+  })
+
+  pi.on("session_start", (_event, ctx) => {
+    config = loadConfig()
+    cwd = ctx.cwd
+    userFacingSession = ctx.hasUI
+  })
+
+  pi.on("agent_settled", (_event, ctx) => {
+    cwd = ctx.cwd
+    if (config?.events.agentSettled)
+      void notify(notificationTitle(config.locale, "agentSettled"))
+  })
+
+  pi.on("session_shutdown", () => {
+    unsubscribeAskUser()
+  })
+}