bark-agent-hook 0.1.1__py3-none-any.whl

bark_agent_hook/__init__.py

@@ -0,0 +1 @@
+"""bark_agent_hook package."""

bark_agent_hook/__main__.py

@@ -0,0 +1,3 @@
+from bark_agent_hook.cli import cmd
+
+cmd()

bark_agent_hook/app.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import importlib.metadata
+from typing import Any
+
+import typer
+
+helptext = """
+Send Bark notifications from agent lifecycle hooks.
+
+Install plugins:
+  bark-agent-hook install
+  bark-agent-hook install --agent codex
+  bark-agent-hook install --agent claude --agent openclaw
+
+Uninstall plugins:
+  bark-agent-hook uninstall
+  bark-agent-hook uninstall --agent codex
+
+Hook commands used by the plugins:
+  bark-agent-hook hook --runtime codex --event completion
+  bark-agent-hook hook --runtime claude --event approval_needed --summary-mode extract
+  bark-agent-hook hook --runtime openclaw --event completion --summary-mode extract
+
+Direct plugin install commands:
+  codex plugin marketplace add qsoyq/bark-agent-hook
+  codex plugin add bark-agent-hook-codex@bark-agent-hook
+  claude plugin marketplace add qsoyq/bark-agent-hook
+  claude plugin install bark-agent-hook@bark-agent-hook --scope user
+  openclaw plugins install --link ./plugins/bark-agent-hook-openclaw
+  openclaw plugins enable bark-agent-hook-openclaw
+
+Configuration:
+  BARK_DEVICE_KEY is required. Missing or empty means skip and exit 0.
+  BARK_GROUP is optional and overrides the computed Bark group.
+  BARK_SERVER defaults to https://api.day.app.
+  AGENT_BARK_NOTIFY_HOOK_URL optionally sets a Bark click URL template.
+  AGENT_BARK_NOTIFY_TITLE_TEMPLATE optionally sets a notification title template.
+  AGENT_BARK_NOTIFY_GROUP_MODE selects the computed group when BARK_GROUP is unset: agent, project, or project-branch.
+  AGENT_BARK_NOTIFY_AUDIT_LOG=1 enables local JSONL audit logging.
+  AGENT_BARK_NOTIFY_AUDIT_LOG_FILE overrides the audit log path.
+
+Template variables:
+  AGENT_BARK_NOTIFY_TITLE_TEMPLATE supports:
+    {agent}, {event}, {project}, {branch}, {session}, {runtime}, {cwd_basename},
+    {LODY_ELECTRON_BOOTSTRAP}, {LODY_ELECTRON_SESSION_USER_ID}, {LODY_SESSION_ID},
+    {LODY_WORKSPACE_SESSION_ID}.
+    Example: AGENT_BARK_NOTIFY_TITLE_TEMPLATE='[{agent}][{event}][{LODY_SESSION_ID}]'
+  AGENT_BARK_NOTIFY_HOOK_URL supports:
+    {runtime}, {agent}, {event}, {project}, {branch}, {session}, {session_id},
+    {session_key}, {conversation_id}, {message_id}, {run_id}, {agent_id},
+    {workspace_dir}, {cwd_basename}, {LODY_ELECTRON_BOOTSTRAP},
+    {LODY_ELECTRON_SESSION_USER_ID}, {LODY_SESSION_ID}, {LODY_WORKSPACE_SESSION_ID}.
+    Example: AGENT_BARK_NOTIFY_HOOK_URL='https://lody.ai/users/{LODY_ELECTRON_SESSION_USER_ID}/sessions/{LODY_SESSION_ID}'
+  Hook URL variable values are percent-encoded; title variables are not URL-encoded.
+  Lody passthrough variables are read from LodySettings and limited to the four LODY_* keys above.
+
+Audit log field sources:
+  Generated by the hook command:
+    1. time: UTC timestamp when the audit record is created.
+    2. status: final hook handling result, such as sent, skipped_duplicate, or skipped_missing_device_key.
+  CLI options:
+    1. runtime: agent runtime selected by --runtime or auto detection.
+    2. event: notification event selected by --event or inferred from the payload.
+    3. summary_mode: notification body mode selected by --summary-mode.
+  Hook payload-derived values:
+    1. hook_event_name: hook event name read from hook_event_name, event, event_name, or type.
+    2. project: project name derived from payload metadata or the current working directory.
+    3. session_id_hash: hashed session identifier; raw session IDs are not logged.
+  Built notification-derived values:
+    1. dedupe_key_hash: hashed notification dedupe key.
+    2. title: final notification title.
+    3. body_len: length of the final notification body; notification bodies are not logged.
+  Lody environment passthrough:
+    1. lody: non-empty whitelisted Lody environment values managed by LodySettings.
+       Keys: LODY_ELECTRON_BOOTSTRAP, LODY_ELECTRON_SESSION_USER_ID,
+       LODY_SESSION_ID, and LODY_WORKSPACE_SESSION_ID.
+"""
+
+
+def version_callback(ctx: typer.Context, value: bool) -> None:
+    if not value:
+        return
+    name = ctx.find_root().info_name or "bark-agent-hook"
+    version = importlib.metadata.version("bark-agent-hook")
+    typer.echo(f"{name} cli version: {version}")
+    raise typer.Exit(0)
+
+
+def default_invoke_without_command(
+    _: bool = typer.Option(False, "--version", "-v", "-V", callback=version_callback),
+) -> None:
+    return None
+
+
+def make_typer(help: str, **kwargs: Any) -> typer.Typer:
+    app = typer.Typer(help=help, **kwargs)
+    app.callback(invoke_without_command=True)(default_invoke_without_command)
+    return app
+
+
+cmd = make_typer(helptext)

bark_agent_hook/audit.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from bark_agent_hook.constants import (
+    AUDIT_LOG_ENV,
+    AUDIT_LOG_FILE_ENV,
+    BEARER_RE,
+    DEFAULT_AUDIT_LOG_PATH,
+    SENSITIVE_ASSIGNMENT_RE,
+)
+from bark_agent_hook.models import Notification, SummaryMode
+from bark_agent_hook.runtime import project_name
+from bark_agent_hook.settings import LodySettings
+from bark_agent_hook.summary import _redact_url, _truncate_summary
+from bark_agent_hook.utils import _env_value, _hash_value, _hook_event_name
+
+
+def _session_id(payload: dict[str, Any]) -> str | None:
+    value = payload.get("session_id") or payload.get("sessionId") or payload.get("sessionKey") or payload.get("conversation_id") or payload.get("transcript_path")
+    return str(value) if value is not None else None
+
+
+def _audit_enabled(env: dict[str, str]) -> bool:
+    return _env_value(env, AUDIT_LOG_ENV).lower() in {"1", "true", "yes", "on"}
+
+
+def _audit_log_path(env: dict[str, str]) -> Path:
+    configured = _env_value(env, AUDIT_LOG_FILE_ENV)
+    if configured:
+        return Path(configured).expanduser()
+    return DEFAULT_AUDIT_LOG_PATH.expanduser()
+
+
+def _safe_error_message(error: BaseException) -> str:
+    message = " ".join(str(error).split())
+    message = BEARER_RE.sub("Bearer [REDACTED]", message)
+    message = SENSITIVE_ASSIGNMENT_RE.sub(lambda m: f"{m.group(1)}=[REDACTED]", message)
+    message = _redact_url(message)
+    return _truncate_summary(message, 200)
+
+
+def _write_audit_record(env: dict[str, str], record: dict[str, Any]) -> None:
+    if not _audit_enabled(env):
+        return
+    try:
+        path = _audit_log_path(env)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False, sort_keys=True))
+            f.write("\n")
+    except OSError:
+        return
+
+
+def _new_audit_record(
+    *,
+    runtime: str,
+    event: str | None,
+    payload: dict[str, Any],
+    summary_mode: SummaryMode,
+    lody_settings: LodySettings,
+    cwd: Path | None = None,
+) -> dict[str, Any]:
+    record: dict[str, Any] = {
+        "time": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "runtime": runtime,
+        "event": event,
+        "hook_event_name": _hook_event_name(payload),
+        "status": None,
+        "project": project_name(payload, cwd),
+        "session_id_hash": _hash_value(_session_id(payload)),
+        "dedupe_key_hash": None,
+        "summary_mode": summary_mode,
+        "title": None,
+        "body_len": None,
+    }
+    lody_values = lody_settings.audit_values()
+    if lody_values:
+        record["lody"] = lody_values
+    return record
+
+
+def _finish_audit_record(
+    env: dict[str, str],
+    record: dict[str, Any],
+    *,
+    status: str,
+    notification: Notification | None = None,
+    error: BaseException | None = None,
+) -> None:
+    record["status"] = status
+    if notification is not None:
+        record["dedupe_key_hash"] = _hash_value(notification.dedupe_key)
+        record["title"] = notification.title
+        record["body_len"] = len(notification.body)
+    if error is not None:
+        record["error_class"] = error.__class__.__name__
+        record["error_message"] = _safe_error_message(error)
+    _write_audit_record(env, record)

bark_agent_hook/cli.py

@@ -0,0 +1,3 @@
+from bark_agent_hook.hook import cmd
+
+__all__ = ["cmd"]

bark_agent_hook/commands.py

@@ -0,0 +1,138 @@
+import json
+import os
+
+import httpx
+import typer
+from rich.console import Console
+
+from bark_agent_hook.app import cmd
+from bark_agent_hook.audit import _finish_audit_record, _new_audit_record
+from bark_agent_hook.constants import DEFAULT_SUMMARY_MAX_CHARS
+from bark_agent_hook.installer import _install_for_available_agents, _uninstall_for_available_agents
+from bark_agent_hook.models import AgentOption, Event, GroupModeOption, Runtime, SummaryMode
+from bark_agent_hook.notification import (
+    already_sent,
+    build_notification,
+    resolve_group_mode,
+    send_bark,
+    skip_notification_reason,
+)
+from bark_agent_hook.output import (
+    _found_cli_count,
+    _print_install_results,
+    _print_uninstall_results,
+    _succeeded,
+)
+from bark_agent_hook.runtime import _read_stdin, detect_event, detect_runtime, parse_hook_payload
+from bark_agent_hook.settings import LodySettings
+from bark_agent_hook.summary import extract_summary
+
+
+@cmd.command()
+def install(
+    agents: list[AgentOption] | None = typer.Option(None, "--agent", help="Agent plugin to install. Repeat for multiple agents. Defaults to all supported agents."),
+) -> None:
+    """Install bark-agent-hook plugins for locally available agents.
+
+    This command checks for codex, claude, and openclaw CLIs in PATH unless
+    one or more --agent options are passed. Missing CLIs are skipped.
+
+    Installed plugins:
+      Codex:        bark-agent-hook-codex@bark-agent-hook
+      Claude Code:  bark-agent-hook@bark-agent-hook --scope user
+      OpenClaw:     local linked plugin from plugins/bark-agent-hook-openclaw
+    """
+    results = _install_for_available_agents(agents)
+    _print_install_results(results, Console(highlight=False, width=120))
+    if _found_cli_count(results) > 0 and _succeeded(results) == 0:
+        raise typer.Exit(1)
+
+
+@cmd.command()
+def uninstall(
+    agents: list[AgentOption] | None = typer.Option(None, "--agent", help="Agent plugin to uninstall. Repeat for multiple agents. Defaults to all supported agents."),
+) -> None:
+    """Uninstall bark-agent-hook plugins for locally available agents."""
+    results = _uninstall_for_available_agents(agents)
+    _print_uninstall_results(results, Console(highlight=False, width=120))
+    if _found_cli_count(results) > 0 and _succeeded(results) == 0:
+        raise typer.Exit(1)
+
+
+@cmd.command()
+def hook(
+    runtime: Runtime = typer.Option("auto", "--runtime", help="Hook runtime: codex, claude, openclaw, or auto."),
+    event: Event = typer.Option("auto", "--event", help="Notification event override."),
+    message: str | None = typer.Option(None, "--message", help="Override short notification body."),
+    group_mode: GroupModeOption | None = typer.Option(None, "--group-mode", help="Bark group mode: agent, project, or project-branch."),
+    summary_mode: SummaryMode = typer.Option("fixed", "--summary-mode", help="Notification summary mode: fixed or extract."),
+    summary_max_chars: int = typer.Option(DEFAULT_SUMMARY_MAX_CHARS, "--summary-max-chars", min=1, help="Maximum extractive summary length."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print notification summary without sending Bark request."),
+    no_dedupe: bool = typer.Option(False, "--no-dedupe", help="Disable duplicate suppression."),
+) -> None:
+    """Read hook JSON from stdin and send a best-effort Bark notification."""
+    env = dict(os.environ)
+    payload = parse_hook_payload(_read_stdin())
+    lody_settings = LodySettings()
+    resolved_runtime = detect_runtime(runtime, env, payload, lody_settings)
+    resolved_event = detect_event(event, payload)
+    resolved_group_mode = resolve_group_mode(group_mode, env)
+    audit_record = _new_audit_record(runtime=resolved_runtime, event=resolved_event, payload=payload, summary_mode=summary_mode, lody_settings=lody_settings)
+    try:
+        if resolved_event is None:
+            _finish_audit_record(env, audit_record, status="skipped_unsupported_event")
+            if dry_run:
+                typer.echo("skip: unsupported hook event")
+            return
+
+        resolved_message = message
+        if resolved_message is None and summary_mode == "extract":
+            resolved_message = extract_summary(resolved_runtime, resolved_event, payload, summary_max_chars)
+
+        skip_reason = skip_notification_reason(resolved_runtime, resolved_event, payload, resolved_message)
+        if skip_reason is not None:
+            _finish_audit_record(env, audit_record, status=skip_reason)
+            if dry_run:
+                typer.echo("skip: OpenClaw event has no deliverable reply")
+            return
+
+        notification = build_notification(
+            runtime=resolved_runtime,
+            event=resolved_event,
+            message=resolved_message,
+            env=env,
+            payload=payload,
+            lody_settings=lody_settings,
+            group_mode=resolved_group_mode,
+        )
+        if notification is None:
+            _finish_audit_record(env, audit_record, status="skipped_missing_device_key")
+            if dry_run:
+                typer.echo("skip: BARK_DEVICE_KEY is missing")
+            return
+
+        if not no_dedupe and already_sent(notification.dedupe_key, env):
+            _finish_audit_record(env, audit_record, status="skipped_duplicate", notification=notification)
+            if dry_run:
+                typer.echo("skip: duplicate notification")
+            return
+
+        if dry_run:
+            _finish_audit_record(env, audit_record, status="sent", notification=notification)
+            output = {"title": notification.title, "body": notification.body, "icon": notification.icon_url, "group": notification.group, "url": notification.bark_url}
+            if notification.click_url:
+                output["click_url"] = notification.click_url
+            typer.echo(json.dumps(output, ensure_ascii=False))
+            return
+
+        try:
+            send_bark(notification)
+        except httpx.HTTPError as e:
+            _finish_audit_record(env, audit_record, status="bark_http_error", notification=notification, error=e)
+            typer.echo(f"Bark notification failed: {e}", err=True)
+            return
+        _finish_audit_record(env, audit_record, status="sent", notification=notification)
+    except Exception as e:
+        _finish_audit_record(env, audit_record, status="hook_exception", error=e)
+        typer.echo(f"Bark hook failed: {e}", err=True)
+        return

bark_agent_hook/constants.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from bark_agent_hook.models import GroupMode
+
+CODEX_ICON_URL = "https://raw.githubusercontent.com/lobehub/lobe-icons/refs/heads/master/packages/static-png/light/codex-color.png"
+
+
+CLAUDE_CODE_ICON_URL = "https://raw.githubusercontent.com/lobehub/lobe-icons/refs/heads/master/packages/static-png/light/claudecode-color.png"
+
+
+OPENCLAW_ICON_URL = "https://openclaw.ai/apple-touch-icon.png"
+
+
+LODY_ICON_URL = "https://lody.ai/favicon.ico"
+
+
+DEFAULT_MESSAGES: dict[str, str] = {
+    "completion": "任务已完成",
+    "approval_needed": "需要你审批当前操作",
+    "failed": "本轮因错误停止",
+}
+
+
+EVENT_LABELS: dict[str, str] = {
+    "completion": "Done",
+    "approval_needed": "Approval",
+    "failed": "Failed",
+}
+
+
+MAX_MESSAGE_LENGTH = 80
+
+
+DEFAULT_SUMMARY_MAX_CHARS = 120
+
+
+MAX_TRANSCRIPT_BYTES = 1024 * 1024
+
+
+DEDUP_TTL_SECONDS = 60 * 60
+
+
+HOOK_URL_TEMPLATE_ENV = "AGENT_BARK_NOTIFY_HOOK_URL"
+
+
+TITLE_TEMPLATE_ENV = "AGENT_BARK_NOTIFY_TITLE_TEMPLATE"
+
+
+DEFAULT_TITLE_TEMPLATE = "[{agent}][{event}][{project}][{branch}][{session}]"
+
+
+GROUP_MODE_ENV = "AGENT_BARK_NOTIFY_GROUP_MODE"
+
+
+GROUP_MODE_CHOICES: tuple[GroupMode, ...] = ("agent", "project", "project-branch")
+
+
+AUDIT_LOG_ENV = "AGENT_BARK_NOTIFY_AUDIT_LOG"
+
+
+AUDIT_LOG_FILE_ENV = "AGENT_BARK_NOTIFY_AUDIT_LOG_FILE"
+
+
+DEFAULT_AUDIT_LOG_PATH = Path("~/.bark-agent-hook/bark-agent-hook.log")
+
+
+SENSITIVE_KEY_RE = re.compile(r"(?i)\b(authorization|cookie|set-cookie|x-api-key|api[_-]?key|token|secret|password|passwd|bearer)\b")
+
+
+SENSITIVE_ASSIGNMENT_RE = re.compile(r"(?i)\b([a-z0-9_.-]*(?:token|secret|password|passwd|cookie|authorization|api[_-]?key)[a-z0-9_.-]*)\s*[:=]\s*('[^']*'|\"[^\"]*\"|[^\s,;]+)")
+
+
+BEARER_RE = re.compile(r"(?i)\bbearer\s+[a-z0-9._~+/=-]+")
+
+
+FENCED_CODE_RE = re.compile(r"```.*?```", re.DOTALL)
+
+
+SHELL_PREFIX_RE = re.compile(r"^\s*(?:bash|zsh|sh|fish|python|python3|node|npm|pnpm|yarn|curl|ssh|scp|rsync)\b", re.IGNORECASE)
+
+
+OPENCLAW_CONVERSATION_ACCESS_PATCH = '{"plugins":{"entries":{"bark-agent-hook-openclaw":{"hooks":{"allowConversationAccess":true}}}}}'

bark_agent_hook/hook.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+from bark_agent_hook.app import cmd
+from bark_agent_hook.commands import hook, install, uninstall
+from bark_agent_hook.constants import (
+    CLAUDE_CODE_ICON_URL,
+    CODEX_ICON_URL,
+    LODY_ICON_URL,
+    OPENCLAW_ICON_URL,
+)
+from bark_agent_hook.installer import _openclaw_plugin_dir
+
+__all__ = (
+    "CLAUDE_CODE_ICON_URL",
+    "CODEX_ICON_URL",
+    "LODY_ICON_URL",
+    "OPENCLAW_ICON_URL",
+    "_openclaw_plugin_dir",
+    "cmd",
+    "hook",
+    "install",
+    "shutil",
+    "subprocess",
+    "uninstall",
+)
+
+if __name__ == "__main__":
+    cmd()

bark_agent_hook/install.py

@@ -0,0 +1,3 @@
+from bark_agent_hook.hook import install, uninstall
+
+__all__ = ["install", "uninstall"]