@chrysb/alphaclaw 0.2.3 → 0.3.0

package/lib/server.js

@@ -5,6 +5,11 @@ const path = require("path");
 const fs = require("fs");
 
 const constants = require("./server/constants");
+const { initLogWriter, readLogTail } = require("./server/log-writer");
+initLogWriter({
+  rootDir: constants.kRootDir,
+  maxBytes: constants.kLogMaxBytes,
+});
 const {
   parseJsonFromNoisyOutput,
   normalizeOnboardingModels,
@@ -18,7 +23,26 @@ const {
   readGoogleCredentials,
   getClientKey,
 } = require("./server/helpers");
-const { readEnvFile, writeEnvFile, reloadEnv, startEnvWatcher } = require("./server/env");
+const {
+  initWebhooksDb,
+  insertRequest,
+  getRequests,
+  getRequestById,
+  getHookSummaries,
+  deleteRequestsByHook,
+} = require("./server/webhooks-db");
+const {
+  initWatchdogDb,
+  insertWatchdogEvent,
+  getRecentEvents,
+} = require("./server/watchdog-db");
+const { createWebhookMiddleware } = require("./server/webhook-middleware");
+const {
+  readEnvFile,
+  writeEnvFile,
+  reloadEnv,
+  startEnvWatcher,
+} = require("./server/env");
 const {
   gatewayEnv,
   isOnboarded,
@@ -29,14 +53,23 @@ const {
   ensureGatewayProxyConfig,
   syncChannelConfig,
   getChannelStatus,
+  launchGatewayProcess,
+  setGatewayExitHandler,
+  setGatewayLaunchHandler,
 } = require("./server/gateway");
 const { createCommands } = require("./server/commands");
 const { createAuthProfiles } = require("./server/auth-profiles");
 const { createLoginThrottle } = require("./server/login-throttle");
 const { createOpenclawVersionService } = require("./server/openclaw-version");
 const { createAlphaclawVersionService } = require("./server/alphaclaw-version");
+const {
+  createRestartRequiredState,
+} = require("./server/restart-required-state");
 const { syncBootstrapPromptFiles } = require("./server/onboarding/workspace");
 const { createTelegramApi } = require("./server/telegram-api");
+const { createDiscordApi } = require("./server/discord-api");
+const { createWatchdogNotifier } = require("./server/watchdog-notify");
+const { createWatchdog } = require("./server/watchdog");
 
 const { registerAuthRoutes } = require("./server/routes/auth");
 const { registerPageRoutes } = require("./server/routes/pages");
@@ -48,6 +81,8 @@ const { registerCodexRoutes } = require("./server/routes/codex");
 const { registerGoogleRoutes } = require("./server/routes/google");
 const { registerProxyRoutes } = require("./server/routes/proxy");
 const { registerTelegramRoutes } = require("./server/routes/telegram");
+const { registerWebhookRoutes } = require("./server/routes/webhooks");
+const { registerWatchdogRoutes } = require("./server/routes/watchdog");
 
 const { PORT, GATEWAY_URL, kTrustProxyHops, SETUP_API_PREFIXES } = constants;
 
@@ -56,6 +91,7 @@ attachGatewaySignalHandlers();
 
 const app = express();
 app.set("trust proxy", kTrustProxyHops);
+app.use(["/webhook", "/hooks"], express.raw({ type: "*/*", limit: "5mb" }));
 app.use(express.json());
 
 const proxy = httpProxy.createProxyServer({
@@ -73,6 +109,20 @@ proxy.on("error", (err, req, res) => {
 const authProfiles = createAuthProfiles();
 const loginThrottle = { ...createLoginThrottle(), getClientKey };
 const { shellCmd, clawCmd, gogCmd } = createCommands({ gatewayEnv });
+const resolveSetupUrl = () => {
+  const explicit =
+    process.env.ALPHACLAW_SETUP_URL ||
+    process.env.ALPHACLAW_BASE_URL ||
+    process.env.RENDER_EXTERNAL_URL ||
+    process.env.URL;
+  if (explicit) return String(explicit).trim();
+  if (process.env.RAILWAY_STATIC_URL) {
+    const domain = String(process.env.RAILWAY_STATIC_URL).trim();
+    if (!domain) return "";
+    return domain.startsWith("http") ? domain : `https://${domain}`;
+  }
+  return "";
+};
 const restartGateway = () => restartGatewayWithReload(reloadEnv);
 const openclawVersionService = createOpenclawVersionService({
   gatewayEnv,
@@ -80,12 +130,26 @@ const openclawVersionService = createOpenclawVersionService({
   isOnboarded,
 });
 const alphaclawVersionService = createAlphaclawVersionService();
+const restartRequiredState = createRestartRequiredState({ isGatewayRunning });
 
 const { requireAuth, isAuthorizedRequest } = registerAuthRoutes({
   app,
   loginThrottle,
 });
 app.use(express.static(path.join(__dirname, "public")));
+initWebhooksDb({
+  rootDir: constants.kRootDir,
+  pruneDays: constants.kWebhookPruneDays,
+});
+initWatchdogDb({
+  rootDir: constants.kRootDir,
+  pruneDays: constants.kWatchdogLogRetentionDays,
+});
+const webhookMiddleware = createWebhookMiddleware({
+  gatewayUrl: constants.GATEWAY_URL,
+  insertRequest,
+  maxPayloadBytes: constants.kMaxPayloadBytes,
+});
 
 registerPageRoutes({ app, requireAuth, isGatewayRunning });
 registerModelRoutes({
@@ -128,7 +192,9 @@ registerSystemRoutes({
   alphaclawVersionService,
   clawCmd,
   restartGateway,
+  onExpectedGatewayRestart: () => watchdog.onExpectedRestart(),
   OPENCLAW_DIR: constants.OPENCLAW_DIR,
+  restartRequiredState,
 });
 registerPairingRoutes({ app, clawCmd, isOnboarded });
 registerCodexRoutes({
@@ -149,14 +215,62 @@ registerGoogleRoutes({
   constants,
 });
 const telegramApi = createTelegramApi(() => process.env.TELEGRAM_BOT_TOKEN);
+const discordApi = createDiscordApi(() => process.env.DISCORD_BOT_TOKEN);
+const watchdogNotifier = createWatchdogNotifier({ telegramApi, discordApi });
+const watchdog = createWatchdog({
+  clawCmd,
+  launchGatewayProcess,
+  insertWatchdogEvent,
+  notifier: watchdogNotifier,
+  readEnvFile,
+  writeEnvFile,
+  reloadEnv,
+  resolveSetupUrl,
+});
+setGatewayExitHandler((payload) => watchdog.onGatewayExit(payload));
+setGatewayLaunchHandler((payload) => watchdog.onGatewayLaunch(payload));
 const doSyncPromptFiles = () =>
   syncBootstrapPromptFiles({ fs, workspaceDir: constants.WORKSPACE_DIR });
-registerTelegramRoutes({ app, telegramApi, syncPromptFiles: doSyncPromptFiles });
-registerProxyRoutes({ app, proxy, SETUP_API_PREFIXES, requireAuth });
+registerTelegramRoutes({
+  app,
+  telegramApi,
+  syncPromptFiles: doSyncPromptFiles,
+});
+registerWebhookRoutes({
+  app,
+  fs,
+  constants,
+  getBaseUrl,
+  shellCmd,
+  webhooksDb: {
+    getRequests,
+    getRequestById,
+    getHookSummaries,
+    deleteRequestsByHook,
+  },
+  restartRequiredState,
+});
+registerWatchdogRoutes({
+  app,
+  requireAuth,
+  watchdog,
+  getRecentEvents,
+  readLogTail,
+});
+registerProxyRoutes({
+  app,
+  proxy,
+  SETUP_API_PREFIXES,
+  requireAuth,
+  webhookMiddleware,
+});
 
 const server = http.createServer(app);
 server.on("upgrade", (req, socket, head) => {
-  const requestUrl = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+  const requestUrl = new URL(
+    req.url || "/",
+    `http://${req.headers.host || "localhost"}`,
+  );
   if (requestUrl.pathname.startsWith("/openclaw")) {
     const upgradeReq = {
       ...req,
@@ -182,6 +296,7 @@ server.listen(PORT, "0.0.0.0", () => {
     syncChannelConfig(readEnvFile());
     ensureGatewayProxyConfig(null);
     startGateway();
+    watchdog.start();
   } else {
     console.log("[alphaclaw] Awaiting onboarding via Setup UI");
   }

package/lib/setup/core-prompts/AGENTS.md

@@ -31,3 +31,87 @@ Use workspace-relative paths only for local files (no absolute paths). Include a
 Changes committed ([abc1234](commit url)): <-- linked commit hash
 • path/or/resource (new|edit|delete) — brief description
 ```
+
+### Telegram Notice Format (AlphaClaw)
+
+Use this format for any Telegram notices sent from AlphaClaw services (watchdog, system alerts, repair notices):
+
+1. Header line (Markdown): `🐺 *AlphaClaw Watchdog*`
+2. Headline line (simple, no `Status:` prefix):
+   - `🔴 Crash loop detected`
+   - `🔴 Crash loop detected, auto-repairing...`
+   - `🟡 Auto-repair started, awaiting health check`
+   - `🟢 Auto-repair complete, gateway healthy`
+   - `🟢 Gateway healthy again`
+   - `🔴 Auto-repair failed`
+3. Append a markdown link to the headline when URL is available:
+   - `... - [View logs](<full-url>/#/watchdog)`
+4. Optional context lines like `Trigger: ...`, `Attempt count: ...`
+5. For values with underscores or special characters (for example `crash_loop`), wrap the value in backticks:
+   - `Trigger: \`crash_loop\``
+6. Do not use HTML tags (`<b>`, `<a href>`) for Telegram watchdog notices.
+
+### UI Conventions
+
+Use these conventions for all UI work under `lib/public/js` and `lib/public/css`.
+
+#### Component structure
+
+- Use arrow-function components and helpers.
+- Prefer shared components over one-off markup when a pattern already exists.
+- Keep constants in `kName` format (e.g. `kUiTabs`, `kGroupOrder`, `kNamePattern`).
+- Keep component-level helpers near the top of the file, before the main export.
+
+#### Rendering and composition
+
+- Use the `htm` + `preact` pattern:
+  - `const html = htm.bind(h);`
+  - return `html\`...\``
+- Prefer early return for hidden states (e.g. `if (!visible) return null;`).
+- Use `<PageHeader />` for tab/page headers that need a title and right-side actions.
+- Use card shells consistently: `bg-surface border border-border rounded-xl`.
+
+#### Buttons
+
+- Primary actions: `ac-btn-cyan`
+- Secondary actions: `ac-btn-secondary`
+- Positive/success actions: `ac-btn-green`
+- Ghost/text actions: `ac-btn-ghost` (use for low-emphasis actions like "Disconnect" or "Add provider")
+- Destructive inline actions: `ac-btn-danger`
+- Use consistent disabled treatment: `opacity-50 cursor-not-allowed`.
+- Keep action sizing consistent (`text-xs px-3 py-1.5 rounded-lg` for compact controls unless there is a clear reason otherwise).
+- For `<PageHeader />` actions, use `ac-btn-cyan` (primary) or `ac-btn-secondary` (secondary) by default; avoid ghost/text-only styling for main header actions.
+- Prefer shared action components when available (`ActionButton`, `UpdateActionButton`, `ConfirmDialog`) before custom button logic.
+- In setup/onboarding auth flows (e.g. Codex OAuth), prefer `<ActionButton />` over raw `<button>` for consistency in tone, sizing, and loading behavior.
+- In multi-step auth flows, keep the active "finish" action visually primary and demote the "start/restart" action to secondary once the flow has started.
+
+#### Dialogs and modals
+
+- Use `<ConfirmDialog />` for destructive/confirmation flows.
+- Use `<ModalShell />` for non-confirm custom modals that need shared overlay and Escape handling.
+- Modal overlay convention:
+  - `fixed inset-0 bg-black/70 flex items-center justify-center p-4 z-50`
+- Modal panel convention:
+  - `bg-modal border border-border rounded-xl p-5 ...`
+- Support close-on-overlay click and Escape key for dialogs.
+
+#### Inputs and forms
+
+- Reuse `<SecretInput />` for sensitive values and token/key inputs.
+- Base input look should remain consistent:
+  - `bg-black/30 border border-border rounded-lg ... focus:border-gray-500`
+- Preserve monospace for technical values (`font-mono`) and codes/paths.
+- Prefer inline helper text under fields (`text-xs text-gray-500/600`) for setup guidance.
+
+#### Feedback and state
+
+- Use `showToast(...)` for user-visible operation outcomes.
+- Prefer semantic toast levels (`success`, `error`, `warning`, `info`) at callsites. Legacy color aliases are only for backwards compatibility.
+- Keep toast positioning relative to the active page container (not the viewport) when layout banners can shift content.
+- Keep loading/saving flags explicit in state (`saving`, `creating`, `restartingGateway`, etc.).
+- Reuse `<LoadingSpinner />` for loading indicators instead of inline spinner SVG markup.
+- Use `<Badge />` for compact status chips (e.g. connected/not connected) instead of one-off status span styling.
+- Use polling via `usePolling` for frequently refreshed backend-backed data.
+- For restart-required flows, render the standardized yellow restart banner style used in `providers`, `envars`, and `webhooks`.
+
+For inconsistencies tracking and DRY opportunities, see `lib/setup/core-prompts/UI-DRY-OPPORTUNITIES.md`.

package/lib/setup/core-prompts/TOOLS.md

@@ -11,6 +11,7 @@ AlphaClaw UI: `{{SETUP_UI_URL}}`
 | General   | `{{SETUP_UI_URL}}#general`   | Gateway status & restart, channel health (Telegram/Discord), pending pairings, feature health (Embeddings/Audio), Google Workspace connection, repo auto-sync schedule, OpenClaw dashboard |
 | Providers | `{{SETUP_UI_URL}}#providers` | AI provider credentials (Anthropic, OpenAI, Gemini, Mistral, Voyage, Groq, Deepgram), feature capabilities, Codex OAuth                                                                    |
 | Envars    | `{{SETUP_UI_URL}}#envars`    | View/edit/add environment variables (saved to `/data/.env`), gateway restart to apply changes                                                                                              |
+| Webhooks  | `{{SETUP_UI_URL}}#webhooks`  | Webhook endpoint visibility, create flow, request history, and gateway delivery debugging                                                                                                  |
 
 ### Environment variables
 
@@ -34,3 +35,15 @@ After pushing, include a link to the commit using the abbreviated hash: [abc1234
 ## Telegram Formatting
 
 - **Links:** Use markdown syntax `[text](URL)` — HTML `<a href>` does NOT render
+
+## Webhooks
+
+You can create webhooks yourself or the user can create them through the Setup UI.
+
+Webhook transform files must follow this convention:
+
+- Path: hooks/transforms/{hook-name}/{hook-name}-transform.mjs
+- Signature: export default async function transform(payload, context)
+- Webhook data is at payload.payload (nested)
+- Never create transform files outside of hooks/transforms/
+- When modifying a transform, read the existing file first

package/lib/setup/core-prompts/UI-DRY-OPPORTUNITIES.md

@@ -0,0 +1,50 @@
+### Prioritized Implementation Order
+
+1. **[P0 | S] Unify toast type mapping in one place so callers consistently use semantic levels.**
+   - [x] Update `lib/public/js/components/toast.js` (`showToast`, `ToastContainer`) to normalize legacy values.
+   - [x] Normalize highest-impact callers first: `lib/public/js/components/providers.js`, `lib/public/js/components/models.js`, `lib/public/js/components/google.js`, `lib/public/js/components/gateway.js`, `lib/public/js/components/envars.js`, `lib/public/js/components/webhooks.js`.
+   - Current inconsistency snapshot:
+     - Legacy color callers: `lib/public/js/components/providers.js`, `lib/public/js/components/models.js`, `lib/public/js/components/google.js`.
+     - Semantic callers: `lib/public/js/components/envars.js`, `lib/public/js/components/webhooks.js`, `lib/public/js/components/gateway.js`, `lib/public/js/components/telegram-workspace.js`.
+
+2. **[P0 | M] Add a shared restart banner component (and/or restart hook) for restart-required flows.**
+   - [x] Extract shared banner + handler state from: `lib/public/js/components/envars.js`, `lib/public/js/components/providers.js`, `lib/public/js/components/webhooks.js`.
+   - [x] Keep `restartGateway` integration aligned with existing gateway action UI in `lib/public/js/components/gateway.js`.
+   - Current inconsistency snapshot:
+     - Duplicate banner + state + handler logic in the same 3 files above.
+
+3. **[P1 | S] Add a small shared loading spinner component to replace repeated inline SVG.**
+   - [x] Replace inline spinners in: `lib/public/js/app.js`, `lib/public/js/components/providers.js`, `lib/public/js/components/models.js`, `lib/public/js/components/onboarding/welcome-setup-step.js`.
+   - [x] Evaluate whether `lib/public/js/components/update-action-button.js` should consume the shared spinner as well.
+   - Current inconsistency snapshot:
+     - Spinner markup shape and sizing differ slightly by file.
+
+4. **[P1 | M] Standardize button styles around `ac-btn-*` + common disabled treatment.**
+   - [x] Convert ad-hoc utility button patterns in: `lib/public/js/components/pairings.js` (Reject), `lib/public/js/components/device-pairings.js` (Reject), `lib/public/js/components/webhooks.js` (Create/Delete), `lib/public/js/components/google.js` (disconnect action), `lib/public/js/components/providers.js` (Codex reconnect/disconnect/restart).
+   - [x] Align onboarding variants in: `lib/public/js/components/onboarding/welcome-setup-step.js`, `lib/public/js/components/onboarding/welcome-form-step.js`, `lib/public/js/components/onboarding/welcome-pairing-step.js`.
+   - Current inconsistency snapshot:
+     - Mixed custom classes vs ad-hoc border utility buttons.
+
+5. **[P1 | S] Normalize disabled opacity usage to one convention.**
+   - [x] Standardize `opacity-50` vs `opacity-60` in:
+     - `lib/public/js/components/envars.js`
+     - `lib/public/js/components/providers.js`
+     - `lib/public/js/components/webhooks.js`
+     - `lib/public/js/components/telegram-workspace.js`
+     - `lib/public/js/components/onboarding/welcome-setup-step.js`
+     - `lib/public/js/components/onboarding/welcome-pairing-step.js`
+   - Current inconsistency snapshot:
+     - `opacity-50` and `opacity-60` both used for disabled states.
+
+6. **[P2 | M] Consider a shared action button wrapper for common save/create/delete states.**
+   - [x] Evaluate extraction points in: `lib/public/js/components/envars.js`, `lib/public/js/components/providers.js`, `lib/public/js/components/webhooks.js`, `lib/public/js/components/models.js`, `lib/public/js/components/pairings.js`, `lib/public/js/components/device-pairings.js`.
+   - Current inconsistency snapshot:
+     - Repeated action-label + loading-label + disabled-guard patterns.
+
+7. **[P2 | M] Extract a shared modal shell wrapper for non-confirm custom modals.**
+   - [x] Factor shared overlay/panel shell from:
+     - `lib/public/js/components/webhooks.js` (`CreateWebhookModal`)
+     - `lib/public/js/components/credentials-modal.js`
+   - [x] Keep parity with `lib/public/js/components/confirm-dialog.js` behavior (overlay click + Escape semantics).
+   - Current inconsistency snapshot:
+     - Same modal shell classes/structure repeated with minor differences.

package/lib/setup/gitignore

@@ -6,6 +6,8 @@
 !workspace/**
 workspace/.openclaw/
 workspace/.openclaw/**
+db/
+db/**
 !skills/
 !skills/**
 !cron/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrysb/alphaclaw",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -16,6 +16,7 @@
     "start": "node bin/alphaclaw.js start",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:watchdog": "vitest run tests/server/watchdog.test.js tests/server/watchdog-db.test.js tests/server/routes-watchdog.test.js",
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {