@poolzin/pool-bot 2026.4.43 → 2026.4.45

package/dist/cli/webhooks-cli.js

@@ -1,140 +1,333 @@
-import { danger } from "../globals.js";
-import { DEFAULT_GMAIL_LABEL, DEFAULT_GMAIL_MAX_BYTES, DEFAULT_GMAIL_RENEW_MINUTES, DEFAULT_GMAIL_SERVE_BIND, DEFAULT_GMAIL_SERVE_PATH, DEFAULT_GMAIL_SERVE_PORT, DEFAULT_GMAIL_SUBSCRIPTION, DEFAULT_GMAIL_TOPIC, } from "../hooks/gmail.js";
-import { runGmailService, runGmailSetup, } from "../hooks/gmail-ops.js";
+/**
+ * Webhook CLI - Manage webhook ingress routes
+ *
+ * Commands:
+ *   poolbot webhooks list              # List all webhook routes
+ *   poolbot webhooks create <path>     # Create webhook route
+ *   poolbot webhooks show <id>         # Show webhook details
+ *   poolbot webhooks delete <id>       # Delete webhook route
+ *   poolbot webhooks enable <id>       # Enable webhook route
+ *   poolbot webhooks disable <id>      # Disable webhook route
+ *   poolbot webhooks stats             # Show webhook statistics
+ *   poolbot webhooks serve             # Start webhook server
+ */
+import crypto from "node:crypto";
+import { loadConfig } from "../config/config.js";
+import { resolveAgentWorkspaceDir } from "../agents/agent-scope.js";
 import { defaultRuntime } from "../runtime.js";
-import { formatDocsLink } from "../terminal/links.js";
 import { theme } from "../terminal/theme.js";
+import { danger, info, success } from "../globals.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { createWebhookRoute, getWebhookRoute, listWebhookRoutes, deleteWebhookRoute, updateWebhookRoute, getWebhookStats, startWebhookServer, } from "../plugins/webhook-ingress.js";
+import { runCommandWithRuntime } from "./cli-utils.js";
+import { callGatewayCli } from "../gateway/call.js";
+function runWebhookCommand(action) {
+    return runCommandWithRuntime(defaultRuntime, action);
+}
 export function registerWebhooksCli(program) {
     const webhooks = program
         .command("webhooks")
-        .description("Webhook helpers and integrations")
-        .addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/webhooks", "docs.molt.bot/cli/webhooks")}\n`);
-    const gmail = webhooks.command("gmail").description("Gmail Pub/Sub hooks (via gogcli)");
-    gmail
-        .command("setup")
-        .description("Configure Gmail watch + Pub/Sub + Poolbot hooks")
-        .requiredOption("--account <email>", "Gmail account to watch")
-        .option("--project <id>", "GCP project id (OAuth client owner)")
-        .option("--topic <name>", "Pub/Sub topic name", DEFAULT_GMAIL_TOPIC)
-        .option("--subscription <name>", "Pub/Sub subscription name", DEFAULT_GMAIL_SUBSCRIPTION)
-        .option("--label <label>", "Gmail label to watch", DEFAULT_GMAIL_LABEL)
-        .option("--hook-url <url>", "Poolbot hook URL")
-        .option("--hook-token <token>", "Poolbot hook token")
-        .option("--push-token <token>", "Push token for gog watch serve")
-        .option("--bind <host>", "gog watch serve bind host", DEFAULT_GMAIL_SERVE_BIND)
-        .option("--port <port>", "gog watch serve port", String(DEFAULT_GMAIL_SERVE_PORT))
-        .option("--path <path>", "gog watch serve path", DEFAULT_GMAIL_SERVE_PATH)
-        .option("--include-body", "Include email body snippets", true)
-        .option("--max-bytes <n>", "Max bytes for body snippets", String(DEFAULT_GMAIL_MAX_BYTES))
-        .option("--renew-minutes <n>", "Renew watch every N minutes", String(DEFAULT_GMAIL_RENEW_MINUTES))
-        .option("--tailscale <mode>", "Expose push endpoint via tailscale (funnel|serve|off)", "funnel")
-        .option("--tailscale-path <path>", "Path for tailscale serve/funnel")
-        .option("--tailscale-target <target>", "Tailscale serve/funnel target (port, host:port, or URL)")
-        .option("--push-endpoint <url>", "Explicit Pub/Sub push endpoint")
-        .option("--json", "Output JSON summary", false)
+        .description("Manage webhook ingress routes (create/list/delete/serve)")
+        .addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/plugins/webhooks", "docs.molt.bot/plugins/webhooks")}\n` +
+        `${theme.muted("Tip:")} Use 'poolbot webhooks serve' to start the webhook server\n`);
+    // webhooks list
+    webhooks
+        .command("list")
+        .description("List webhook routes")
+        .option("--json", "Output JSON", false)
         .action(async (opts) => {
-        try {
-            const parsed = parseGmailSetupOptions(opts);
-            await runGmailSetup(parsed);
-        }
-        catch (err) {
-            defaultRuntime.error(danger(String(err)));
-            defaultRuntime.exit(1);
-        }
+        await runWebhookCommand(async () => {
+            const config = loadConfig();
+            const workspaceDir = resolveAgentWorkspaceDir(config, "main");
+            const routes = listWebhookRoutes(workspaceDir);
+            if (opts.json) {
+                defaultRuntime.log(JSON.stringify(routes, null, 2));
+                return;
+            }
+            defaultRuntime.log("");
+            defaultRuntime.log(theme.heading("Webhook Routes"));
+            defaultRuntime.log(theme.muted("─────────────────────────────────────────"));
+            if (routes.length === 0) {
+                defaultRuntime.log(info("No webhook routes configured."));
+                defaultRuntime.log("Create one with: poolbot webhooks create /my-webhook");
+            }
+            else {
+                for (const route of routes) {
+                    const status = route.enabled ? theme.success("●") : theme.muted("○");
+                    const methods = route.methods.join("/");
+                    defaultRuntime.log(`  ${status} ${route.path} [${methods}] ${route.enabled ? "" : theme.muted("(disabled)")}`);
+                    defaultRuntime.log(theme.muted(`      ID: ${route.id} | Triggers: ${route.triggerCount}`));
+                }
+            }
+            defaultRuntime.log("");
+            const stats = getWebhookStats(workspaceDir);
+            defaultRuntime.log(theme.muted(`Total: ${stats.total} routes | Enabled: ${stats.enabled} | Total triggers: ${stats.totalTriggers}`));
+            defaultRuntime.exit(0);
+        });
+    });
+    // webhooks create
+    webhooks
+        .command("create <path>")
+        .description("Create webhook route")
+        .requiredOption("--agent <id>", "Agent ID to run")
+        .requiredOption("--message <text>", "Message/prompt to send")
+        .option("--session <key>", "Session key (optional)")
+        .option("--skills <list>", "Comma-separated skills to enable")
+        .option("--secret <secret>", "Shared secret (auto-generated if omitted)")
+        .option("--methods <methods>", "HTTP methods (default: POST)")
+        .option("--rate-limit <n>", "Rate limit per minute", Number.parseInt)
+        .action(async (path, opts) => {
+        await runWebhookCommand(async () => {
+            const config = loadConfig();
+            const workspaceDir = resolveAgentWorkspaceDir(config, "main");
+            const secret = opts.secret ?? crypto.randomUUID();
+            const methods = opts.methods ? opts.methods.split(",").map((m) => m.trim()) : ["POST"];
+            const skills = opts.skills ? opts.skills.split(",").map((s) => s.trim()) : undefined;
+            try {
+                const routeId = createWebhookRoute(workspaceDir, {
+                    path,
+                    secret,
+                    taskFlow: {
+                        agentId: opts.agent ?? "main",
+                        message: opts.message ?? "",
+                        sessionKey: opts.session,
+                        skills,
+                    },
+                    methods,
+                    rateLimitPerMin: opts.rateLimit,
+                });
+                defaultRuntime.log("");
+                defaultRuntime.log(success(`Created webhook route: ${path}`));
+                defaultRuntime.log(`  ID: ${routeId}`);
+                defaultRuntime.log(`  Secret: ${theme.error(secret)} (keep this secret!)`);
+                defaultRuntime.log(`  Methods: ${methods.join("/")}`);
+                defaultRuntime.log("");
+                defaultRuntime.log(info("Usage example:"));
+                defaultRuntime.log(`  curl -X POST http://localhost:8888${path} \\`);
+                defaultRuntime.log(`    -H "Content-Type: application/json" \\`);
+                defaultRuntime.log(`    -H "X-Webhook-Signature: <hmac-sha256>" \\`);
+                defaultRuntime.log(`    -d '{"key": "value"}'`);
+                defaultRuntime.log("");
+                defaultRuntime.log(info("Start the webhook server with: poolbot webhooks serve"));
+                defaultRuntime.exit(0);
+            }
+            catch (error) {
+                defaultRuntime.log(danger(`Failed to create webhook: ${error instanceof Error ? error.message : String(error)}`));
+                defaultRuntime.exit(1);
+            }
+        });
+    });
+    // webhooks show
+    webhooks
+        .command("show <id>")
+        .description("Show webhook details")
+        .option("--json", "Output JSON", false)
+        .action(async (id, opts) => {
+        await runWebhookCommand(async () => {
+            const config = loadConfig();
+            const workspaceDir = resolveAgentWorkspaceDir(config, "main");
+            const route = getWebhookRoute(workspaceDir, id);
+            if (!route) {
+                defaultRuntime.log(danger(`Webhook "${id}" not found.`));
+                defaultRuntime.exit(1);
+                return;
+            }
+            if (opts.json) {
+                defaultRuntime.log(JSON.stringify(route, null, 2));
+                return;
+            }
+            defaultRuntime.log("");
+            defaultRuntime.log(theme.heading(`Webhook: ${route.path}`));
+            defaultRuntime.log(theme.muted("─────────────────────────────────────────"));
+            defaultRuntime.log(`  ID: ${route.id}`);
+            defaultRuntime.log(`  Path: ${route.path}`);
+            defaultRuntime.log(`  Status: ${route.enabled ? theme.success("enabled") : theme.warn("disabled")}`);
+            defaultRuntime.log(`  Methods: ${route.methods.join("/")}`);
+            defaultRuntime.log(`  Rate limit: ${route.rateLimitPerMin ?? "none"} /min`);
+            defaultRuntime.log(`  Created: ${new Date(route.createdAt).toLocaleString()}`);
+            if (route.lastTriggeredAt) {
+                defaultRuntime.log(`  Last triggered: ${new Date(route.lastTriggeredAt).toLocaleString()}`);
+            }
+            defaultRuntime.log(`  Trigger count: ${route.triggerCount}`);
+            defaultRuntime.log("");
+            defaultRuntime.log(theme.heading("Task Flow"));
+            defaultRuntime.log(theme.muted("─────────────────────────────────────────"));
+            defaultRuntime.log(`  Agent: ${route.taskFlow.agentId}`);
+            defaultRuntime.log(`  Message: ${route.taskFlow.message.substring(0, 100)}...`);
+            if (route.taskFlow.sessionKey) {
+                defaultRuntime.log(`  Session: ${route.taskFlow.sessionKey}`);
+            }
+            if (route.taskFlow.skills?.length) {
+                defaultRuntime.log(`  Skills: ${route.taskFlow.skills.join(", ")}`);
+            }
+            defaultRuntime.exit(0);
+        });
+    });
+    // webhooks delete
+    webhooks
+        .command("delete <id>")
+        .description("Delete webhook route")
+        .option("--yes", "Skip confirmation", false)
+        .action(async (id, opts) => {
+        await runWebhookCommand(async () => {
+            const config = loadConfig();
+            const workspaceDir = resolveAgentWorkspaceDir(config, "main");
+            const route = getWebhookRoute(workspaceDir, id);
+            if (!route) {
+                defaultRuntime.log(danger(`Webhook "${id}" not found.`));
+                defaultRuntime.exit(1);
+                return;
+            }
+            if (!opts.yes) {
+                defaultRuntime.log("");
+                defaultRuntime.log(danger(`⚠️  This will permanently delete webhook "${route.path}"`));
+                defaultRuntime.log("This action cannot be undone.");
+                defaultRuntime.log("");
+                defaultRuntime.log(info("Use --yes to skip this confirmation."));
+                defaultRuntime.exit(1);
+                return;
+            }
+            const deleted = deleteWebhookRoute(workspaceDir, id);
+            if (deleted) {
+                defaultRuntime.log("");
+                defaultRuntime.log(success(`Webhook "${route.path}" deleted.`));
+            }
+            else {
+                defaultRuntime.log(danger(`Failed to delete webhook "${id}".`));
+                defaultRuntime.exit(1);
+            }
+        });
+    });
+    // webhooks enable/disable
+    webhooks
+        .command("enable <id>")
+        .description("Enable webhook route")
+        .action(async (id) => {
+        await runWebhookCommand(async () => {
+            const config = loadConfig();
+            const workspaceDir = resolveAgentWorkspaceDir(config, "main");
+            const route = updateWebhookRoute(workspaceDir, id, { enabled: true });
+            if (!route) {
+                defaultRuntime.log(danger(`Webhook "${id}" not found.`));
+                defaultRuntime.exit(1);
+                return;
+            }
+            defaultRuntime.log("");
+            defaultRuntime.log(success(`Webhook "${route.path}" enabled.`));
+            defaultRuntime.exit(0);
+        });
+    });
+    webhooks
+        .command("disable <id>")
+        .description("Disable webhook route")
+        .action(async (id) => {
+        await runWebhookCommand(async () => {
+            const config = loadConfig();
+            const workspaceDir = resolveAgentWorkspaceDir(config, "main");
+            const route = updateWebhookRoute(workspaceDir, id, { enabled: false });
+            if (!route) {
+                defaultRuntime.log(danger(`Webhook "${id}" not found.`));
+                defaultRuntime.exit(1);
+                return;
+            }
+            defaultRuntime.log("");
+            defaultRuntime.log(success(`Webhook "${route.path}" disabled.`));
+            defaultRuntime.exit(0);
+        });
     });
-    gmail
-        .command("run")
-        .description("Run gog watch serve + auto-renew loop")
-        .option("--account <email>", "Gmail account to watch")
-        .option("--topic <topic>", "Pub/Sub topic path (projects/.../topics/..)")
-        .option("--subscription <name>", "Pub/Sub subscription name")
-        .option("--label <label>", "Gmail label to watch")
-        .option("--hook-url <url>", "Poolbot hook URL")
-        .option("--hook-token <token>", "Poolbot hook token")
-        .option("--push-token <token>", "Push token for gog watch serve")
-        .option("--bind <host>", "gog watch serve bind host")
-        .option("--port <port>", "gog watch serve port")
-        .option("--path <path>", "gog watch serve path")
-        .option("--include-body", "Include email body snippets")
-        .option("--max-bytes <n>", "Max bytes for body snippets")
-        .option("--renew-minutes <n>", "Renew watch every N minutes")
-        .option("--tailscale <mode>", "Expose push endpoint via tailscale (funnel|serve|off)")
-        .option("--tailscale-path <path>", "Path for tailscale serve/funnel")
-        .option("--tailscale-target <target>", "Tailscale serve/funnel target (port, host:port, or URL)")
+    // webhooks stats
+    webhooks
+        .command("stats")
+        .description("Show webhook statistics")
+        .option("--json", "Output JSON", false)
         .action(async (opts) => {
-        try {
-            const parsed = parseGmailRunOptions(opts);
-            await runGmailService(parsed);
-        }
-        catch (err) {
-            defaultRuntime.error(danger(String(err)));
-            defaultRuntime.exit(1);
-        }
+        await runWebhookCommand(async () => {
+            const config = loadConfig();
+            const workspaceDir = resolveAgentWorkspaceDir(config, "main");
+            const stats = getWebhookStats(workspaceDir);
+            if (opts.json) {
+                defaultRuntime.log(JSON.stringify(stats, null, 2));
+                return;
+            }
+            defaultRuntime.log("");
+            defaultRuntime.log(theme.heading("Webhook Statistics"));
+            defaultRuntime.log(theme.muted("─────────────────────────────────────────"));
+            defaultRuntime.log(`  Total routes: ${stats.total}`);
+            defaultRuntime.log(`  Enabled routes: ${stats.enabled}`);
+            defaultRuntime.log(`  Total triggers: ${stats.totalTriggers}`);
+            defaultRuntime.log("");
+            if (stats.routes.length > 0) {
+                defaultRuntime.log(theme.heading("Top Routes"));
+                defaultRuntime.log(theme.muted("─────────────────────────────────────────"));
+                const topRoutes = stats.routes.sort((a, b) => b.triggers - a.triggers).slice(0, 5);
+                for (const route of topRoutes) {
+                    defaultRuntime.log(`  ${route.path}: ${route.triggers} triggers`);
+                }
+            }
+            defaultRuntime.exit(0);
+        });
+    });
+    // webhooks serve
+    webhooks
+        .command("serve")
+        .description("Start webhook server")
+        .option("--port <n>", "Port to listen on", Number.parseInt)
+        .action(async (opts) => {
+        await runWebhookCommand(async () => {
+            const config = loadConfig();
+            const workspaceDir = resolveAgentWorkspaceDir(config, "main");
+            const port = opts.port ?? 8888;
+            defaultRuntime.log("");
+            defaultRuntime.log(theme.heading("Starting Webhook Server"));
+            defaultRuntime.log(theme.muted("─────────────────────────────────────────"));
+            const routes = listWebhookRoutes(workspaceDir);
+            if (routes.length === 0) {
+                defaultRuntime.log(info("No webhook routes configured."));
+                defaultRuntime.log("Create one with: poolbot webhooks create /my-webhook");
+                defaultRuntime.exit(0);
+                return;
+            }
+            defaultRuntime.log(`  Port: ${port}`);
+            defaultRuntime.log(`  Routes: ${routes.length}`);
+            defaultRuntime.log("");
+            defaultRuntime.log("Registered routes:");
+            for (const route of routes) {
+                const status = route.enabled ? theme.success("✓") : theme.muted("○");
+                defaultRuntime.log(`  ${status} ${route.path} [${route.methods.join("/")}]`);
+            }
+            defaultRuntime.log("");
+            // Start server
+            const { server } = await startWebhookServer(workspaceDir, port, async (route, payload) => {
+                // Execute agent with task flow configuration
+                defaultRuntime.log(`Triggered: ${route.path} -> ${route.taskFlow.agentId}`);
+                defaultRuntime.log(`  Message: ${route.taskFlow.message}`);
+                try {
+                    // Call gateway to run agent
+                    await callGatewayCli({
+                        method: "agent.run",
+                        params: {
+                            agentId: route.taskFlow.agentId,
+                            message: route.taskFlow.message,
+                            sessionKey: route.taskFlow.sessionKey,
+                            skills: route.taskFlow.skills,
+                            context: { webhookPayload: payload, webhookRoute: route.path },
+                        },
+                    });
+                    defaultRuntime.log(success(`Agent executed successfully`));
+                }
+                catch (error) {
+                    defaultRuntime.log(danger(`Agent execution failed: ${error instanceof Error ? error.message : String(error)}`));
+                    throw error;
+                }
+            });
+            defaultRuntime.log(info("Press Ctrl+C to stop"));
+            // Handle shutdown
+            process.on("SIGINT", () => {
+                defaultRuntime.log("");
+                defaultRuntime.log(info("Shutting down webhook server..."));
+                server.close();
+                process.exit(0);
+            });
+        });
     });
-}
-function parseGmailSetupOptions(raw) {
-    const accountRaw = raw.account;
-    const account = typeof accountRaw === "string" ? accountRaw.trim() : "";
-    if (!account)
-        throw new Error("--account is required");
-    return {
-        account,
-        project: stringOption(raw.project),
-        topic: stringOption(raw.topic),
-        subscription: stringOption(raw.subscription),
-        label: stringOption(raw.label),
-        hookUrl: stringOption(raw.hookUrl),
-        hookToken: stringOption(raw.hookToken),
-        pushToken: stringOption(raw.pushToken),
-        bind: stringOption(raw.bind),
-        port: numberOption(raw.port),
-        path: stringOption(raw.path),
-        includeBody: booleanOption(raw.includeBody),
-        maxBytes: numberOption(raw.maxBytes),
-        renewEveryMinutes: numberOption(raw.renewMinutes),
-        tailscale: stringOption(raw.tailscale),
-        tailscalePath: stringOption(raw.tailscalePath),
-        tailscaleTarget: stringOption(raw.tailscaleTarget),
-        pushEndpoint: stringOption(raw.pushEndpoint),
-        json: Boolean(raw.json),
-    };
-}
-function parseGmailRunOptions(raw) {
-    return {
-        account: stringOption(raw.account),
-        topic: stringOption(raw.topic),
-        subscription: stringOption(raw.subscription),
-        label: stringOption(raw.label),
-        hookUrl: stringOption(raw.hookUrl),
-        hookToken: stringOption(raw.hookToken),
-        pushToken: stringOption(raw.pushToken),
-        bind: stringOption(raw.bind),
-        port: numberOption(raw.port),
-        path: stringOption(raw.path),
-        includeBody: booleanOption(raw.includeBody),
-        maxBytes: numberOption(raw.maxBytes),
-        renewEveryMinutes: numberOption(raw.renewMinutes),
-        tailscale: stringOption(raw.tailscale),
-        tailscalePath: stringOption(raw.tailscalePath),
-        tailscaleTarget: stringOption(raw.tailscaleTarget),
-    };
-}
-function stringOption(value) {
-    if (typeof value !== "string")
-        return undefined;
-    const trimmed = value.trim();
-    return trimmed ? trimmed : undefined;
-}
-function numberOption(value) {
-    if (value === undefined || value === null)
-        return undefined;
-    const n = typeof value === "number" ? value : Number(value);
-    if (!Number.isFinite(n) || n <= 0)
-        return undefined;
-    return Math.floor(n);
-}
-function booleanOption(value) {
-    if (value === undefined || value === null)
-        return undefined;
-    return Boolean(value);
 }

package/dist/errors/user-friendly-errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * User-Friendly Error Messages
+ *
+ * Transforms technical errors into clear, actionable messages.
+ */
+export type ErrorCategory = "auth" | "network" | "config" | "model" | "rate_limit" | "permission" | "resource" | "validation" | "unknown";
+export type UserFriendlyError = {
+    category: ErrorCategory;
+    message: string;
+    cause?: string;
+    solution: string[];
+    docsLink?: string;
+    retryable?: boolean;
+};
+/**
+ * Convert an error to a user-friendly error.
+ */
+export declare function toUserFriendlyError(error: unknown): UserFriendlyError;
+/**
+ * Format a user-friendly error for display.
+ */
+export declare function formatUserFriendlyError(err: UserFriendlyError): string;
+//# sourceMappingURL=user-friendly-errors.d.ts.map

package/dist/errors/user-friendly-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-friendly-errors.d.ts","sourceRoot":"","sources":["../../src/errors/user-friendly-errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,SAAS,GACT,QAAQ,GACR,OAAO,GACP,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,SAAS,CAAC;AAEd,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AA4IF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CA2BrE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CA0BtE"}

package/dist/errors/user-friendly-errors.js

@@ -0,0 +1,182 @@
+/**
+ * User-Friendly Error Messages
+ *
+ * Transforms technical errors into clear, actionable messages.
+ */
+const ERROR_PATTERNS = [
+    // Auth errors
+    {
+        pattern: /unauthorized|401|authentication failed/i,
+        category: "auth",
+        message: "Authentication failed",
+        solution: [
+            "Check your API key or token is correct",
+            "Ensure the token hasn't expired",
+            "Run 'poolbot secret get <name>' to verify",
+        ],
+        docsLink: "/auth/troubleshooting",
+        retryable: false,
+    },
+    {
+        pattern: /forbidden|403|access denied/i,
+        category: "permission",
+        message: "Access denied",
+        solution: [
+            "Check you have the required permissions",
+            "Contact your administrator to grant access",
+        ],
+        docsLink: "/auth/permissions",
+        retryable: false,
+    },
+    // Network errors
+    {
+        pattern: /network|connection.*refused|ECONNREFUSED/i,
+        category: "network",
+        message: "Network connection failed",
+        solution: [
+            "Check your internet connection",
+            "Verify the service is running",
+            "Try again in a few moments",
+        ],
+        retryable: true,
+    },
+    {
+        pattern: /timeout|ETIMEDOUT/i,
+        category: "network",
+        message: "Request timed out",
+        solution: [
+            "The service is taking too long to respond",
+            "Check if the service is overloaded",
+            "Try again with a smaller request",
+        ],
+        retryable: true,
+    },
+    // Rate limit errors
+    {
+        pattern: /rate.*limit|429|too.*many.*request/i,
+        category: "rate_limit",
+        message: "Rate limit exceeded",
+        solution: [
+            "You've made too many requests",
+            "Wait before trying again",
+            "Consider upgrading your plan for higher limits",
+        ],
+        docsLink: "/limits",
+        retryable: true,
+    },
+    // Model errors
+    {
+        pattern: /model.*not.*found|invalid.*model/i,
+        category: "model",
+        message: "Model not found",
+        solution: [
+            "Check the model name is correct",
+            "Run 'poolbot models list' to see available models",
+            "Ensure the model provider is configured",
+        ],
+        docsLink: "/models",
+        retryable: false,
+    },
+    {
+        pattern: /context.*exceeded|context.*window|token.*limit/i,
+        category: "model",
+        message: "Context window exceeded",
+        solution: [
+            "Your message is too long for this model",
+            "Try splitting your request into smaller parts",
+            "Use a model with a larger context window",
+        ],
+        docsLink: "/models/context",
+        retryable: false,
+    },
+    // Config errors
+    {
+        pattern: /config.*not.*found|missing.*config/i,
+        category: "config",
+        message: "Configuration missing",
+        solution: [
+            "Run 'poolbot config show' to check your config",
+            "Set the required configuration values",
+            "Run 'poolbot onboard' for guided setup",
+        ],
+        docsLink: "/config",
+        retryable: false,
+    },
+    // Resource errors
+    {
+        pattern: /not.*found|404|resource.*not.*exist/i,
+        category: "resource",
+        message: "Resource not found",
+        solution: [
+            "Check the resource ID is correct",
+            "Ensure the resource exists",
+            "List available resources to verify",
+        ],
+        retryable: false,
+    },
+    // Validation errors
+    {
+        pattern: /invalid|validation.*failed|bad.*request|400/i,
+        category: "validation",
+        message: "Invalid input",
+        solution: [
+            "Check your input format",
+            "Review the required fields",
+            "See the documentation for examples",
+        ],
+        retryable: false,
+    },
+];
+/**
+ * Convert an error to a user-friendly error.
+ */
+export function toUserFriendlyError(error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    for (const pattern of ERROR_PATTERNS) {
+        if (pattern.pattern.test(errorMessage)) {
+            return {
+                category: pattern.category,
+                message: pattern.message,
+                cause: errorMessage,
+                solution: pattern.solution,
+                docsLink: pattern.docsLink,
+                retryable: pattern.retryable,
+            };
+        }
+    }
+    return {
+        category: "unknown",
+        message: "An unexpected error occurred",
+        cause: errorMessage,
+        solution: [
+            "Try again",
+            "Check the logs for more details",
+            "Contact support if the issue persists",
+        ],
+        retryable: true,
+    };
+}
+/**
+ * Format a user-friendly error for display.
+ */
+export function formatUserFriendlyError(err) {
+    const lines = [];
+    lines.push(`❌ ${err.message}`);
+    if (err.cause && err.cause !== err.message) {
+        lines.push(`   Cause: ${err.cause}`);
+    }
+    lines.push("");
+    lines.push("Solutions:");
+    for (const solution of err.solution) {
+        lines.push(`  • ${solution}`);
+    }
+    if (err.docsLink) {
+        lines.push("");
+        lines.push(`📖 Documentation: ${err.docsLink}`);
+    }
+    if (err.retryable) {
+        lines.push("");
+        lines.push("💡 This error is temporary. You can retry.");
+    }
+    return lines.join("\n");
+}