@agentchatme/openclaw 0.2.0 → 0.3.0

package/dist/setup-entry.js

@@ -1,40 +1,64 @@
 import { buildChannelConfigSchema, defineChannelPluginEntry, defineSetupPluginEntry } from 'openclaw/plugin-sdk/channel-core';
+import { setSetupChannelEnabled, WizardCancelledError } from 'openclaw/plugin-sdk/setup';
 import { z } from 'zod';
 
 // src/channel.setup.ts
-var reconnectConfigSchema = z.object({
-  initialBackoffMs: z.number().int().min(100).max(1e4).default(1e3),
-  maxBackoffMs: z.number().int().min(1e3).max(3e5).default(3e4),
-  jitterRatio: z.number().min(0).max(1).default(0.2)
-}).strict();
-var pingConfigSchema = z.object({
-  intervalMs: z.number().int().min(5e3).max(12e4).default(3e4),
-  timeoutMs: z.number().int().min(1e3).max(3e4).default(1e4)
-}).strict();
-var outboundConfigSchema = z.object({
-  maxInFlight: z.number().int().min(1).max(1e4).default(256),
-  sendTimeoutMs: z.number().int().min(1e3).max(6e4).default(15e3)
-}).strict();
-var observabilityConfigSchema = z.object({
-  logLevel: z.enum(["trace", "debug", "info", "warn", "error"]).default("info"),
-  redactKeys: z.array(z.string()).default(["apiKey", "authorization", "cookie", "set-cookie"])
-}).strict();
-var agentHandleSchema = z.string().regex(/^[a-z0-9_.-]{3,32}$/, "handle must be 3-32 chars, lowercase alphanumeric + . _ -");
-var agentchatChannelConfigSchema = z.object({
-  apiBase: z.string().url().default("https://api.agentchat.me"),
-  apiKey: z.string().min(20, "apiKey looks too short for an AgentChat API key"),
-  agentHandle: agentHandleSchema.optional(),
-  // `.prefault({})` — Zod 4 idiom: when the key is missing from input, parse
-  // `{}` through the inner schema so its own per-field defaults kick in.
-  // Using `.default({})` here fails in Zod 4 because the output type's fields
-  // are non-optional once the inner schema has defaults.
-  reconnect: reconnectConfigSchema.prefault({}),
-  ping: pingConfigSchema.prefault({}),
-  outbound: outboundConfigSchema.prefault({}),
-  observability: observabilityConfigSchema.prefault({})
-}).strict();
-function parseChannelConfig(input) {
-  return agentchatChannelConfigSchema.parse(input);
+
+// src/channel-account.ts
+var AGENTCHAT_CHANNEL_ID = "agentchat";
+var AGENTCHAT_DEFAULT_ACCOUNT_ID = "default";
+var MIN_API_KEY_LENGTH = 20;
+function readChannelSection(cfg) {
+  const channels = cfg?.channels;
+  const section = channels?.[AGENTCHAT_CHANNEL_ID];
+  return section && typeof section === "object" && !Array.isArray(section) ? section : void 0;
+}
+function readAccountRaw(section, accountId) {
+  if (!section) return void 0;
+  const { accounts } = section;
+  if (accounts && typeof accounts === "object" && !Array.isArray(accounts)) {
+    const entry = accounts[accountId];
+    if (entry && typeof entry === "object") return entry;
+  }
+  if (accountId === AGENTCHAT_DEFAULT_ACCOUNT_ID) {
+    const { accounts: _accounts, ...rest } = section;
+    return rest;
+  }
+  return void 0;
+}
+function splitEnabledFromRaw(raw) {
+  if (!raw) return { enabled: true, forParse: void 0 };
+  const { enabled, ...rest } = raw;
+  return { enabled: enabled !== false, forParse: rest };
+}
+function isApiKeyPresent(value) {
+  return typeof value === "string" && value.length >= MIN_API_KEY_LENGTH;
+}
+function readAgentchatConfigField(cfg, accountId, field) {
+  const section = readChannelSection(cfg);
+  const raw = readAccountRaw(section, accountId);
+  if (!raw) return void 0;
+  const value = raw[field];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function applyAgentchatAccountPatch(cfg, accountId, patch) {
+  const channels = {
+    ...cfg?.channels ?? {}
+  };
+  const currentSection = channels[AGENTCHAT_CHANNEL_ID];
+  const section = currentSection && typeof currentSection === "object" && !Array.isArray(currentSection) ? { ...currentSection } : {};
+  if (accountId === AGENTCHAT_DEFAULT_ACCOUNT_ID && !section.accounts) {
+    Object.assign(section, patch);
+  } else {
+    const accounts = {
+      ...section.accounts ?? {}
+    };
+    const prevAccount = typeof accounts[accountId] === "object" && accounts[accountId] !== null ? accounts[accountId] : {};
+    accounts[accountId] = { ...prevAccount, ...patch };
+    section.accounts = accounts;
+  }
+  channels[AGENTCHAT_CHANNEL_ID] = section;
+  return { ...cfg ?? {}, channels };
 }
 
 // src/setup-client.ts
@@ -137,7 +161,6 @@ async function registerAgentStart(input, opts = {}) {
   if (res.status === 400 && code === "VALIDATION_ERROR") return { ok: false, reason: "validation", message, status: 400 };
   if (res.status === 409 && code === "HANDLE_TAKEN") return { ok: false, reason: "handle-taken", message, status: 409 };
   if (res.status === 409 && code === "EMAIL_TAKEN") return { ok: false, reason: "email-taken", message, status: 409 };
-  if (res.status === 409 && code === "EMAIL_IS_OWNER") return { ok: false, reason: "email-is-owner", message, status: 409 };
   if (res.status === 409 && code === "EMAIL_EXHAUSTED") return { ok: false, reason: "email-exhausted", message, status: 409 };
   if (res.status === 429) {
     return {
@@ -184,7 +207,6 @@ async function registerAgentVerify(input, opts = {}) {
   if (res.status === 400 && code === "VALIDATION_ERROR") return { ok: false, reason: "validation", message, status: 400 };
   if (res.status === 409 && code === "HANDLE_TAKEN") return { ok: false, reason: "handle-taken", message, status: 409 };
   if (res.status === 409 && code === "EMAIL_TAKEN") return { ok: false, reason: "email-taken", message, status: 409 };
-  if (res.status === 409 && code === "EMAIL_IS_OWNER") return { ok: false, reason: "email-is-owner", message, status: 409 };
   if (res.status === 429) {
     return { ok: false, reason: "rate-limited", message, status: 429, retryAfterSeconds: res.retryAfterSeconds };
   }
@@ -221,487 +243,551 @@ async function post(path, body, opts) {
   }
 }
 
-// src/setup-wizard.ts
-var HANDLE_PATTERN = /^[a-z0-9_.-]{3,32}$/;
-var MIN_API_KEY_LENGTH = 20;
-var OTP_ATTEMPTS = 3;
-function readSection(cfg) {
-  const channels = cfg?.channels;
-  const sec = channels?.[AGENTCHAT_CHANNEL_ID];
-  return sec && typeof sec === "object" && !Array.isArray(sec) ? sec : void 0;
-}
-function readAccountRaw(cfg, accountId) {
-  const sec = readSection(cfg);
-  if (!sec) return void 0;
-  const accounts = sec.accounts;
-  if (accounts && typeof accounts === "object" && !Array.isArray(accounts)) {
-    const entry = accounts[accountId];
-    if (entry && typeof entry === "object") return entry;
-  }
-  if (accountId === AGENTCHAT_DEFAULT_ACCOUNT_ID) {
-    const { accounts: _accounts, ...rest } = sec;
-    return rest;
-  }
-  return void 0;
-}
-function readAccountApiKey(cfg, accountId) {
-  const raw = readAccountRaw(cfg, accountId);
-  const value = raw?.apiKey;
-  return typeof value === "string" && value.length >= MIN_API_KEY_LENGTH ? value : void 0;
-}
-function readAccountApiBase(cfg, accountId) {
-  const raw = readAccountRaw(cfg, accountId);
-  const value = raw?.apiBase;
-  return typeof value === "string" && value.length > 0 ? value : void 0;
-}
-function writeAccountPatch(cfg, accountId, patch) {
-  const channels = {
-    ...cfg?.channels ?? {}
-  };
-  const existing = channels[AGENTCHAT_CHANNEL_ID];
-  const section = existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
-  const clean = {};
-  if (patch.apiKey !== void 0) clean.apiKey = patch.apiKey;
-  if (patch.apiBase !== void 0) clean.apiBase = patch.apiBase;
-  if (patch.agentHandle !== void 0) clean.agentHandle = patch.agentHandle;
-  const hasAccountsMap = typeof section.accounts === "object" && section.accounts !== null && !Array.isArray(section.accounts);
-  if (accountId === AGENTCHAT_DEFAULT_ACCOUNT_ID && !hasAccountsMap) {
-    Object.assign(section, clean);
-  } else {
-    const accounts = {
-      ...section.accounts ?? {}
-    };
-    const prev = typeof accounts[accountId] === "object" && accounts[accountId] !== null ? accounts[accountId] : {};
-    accounts[accountId] = { ...prev, ...clean };
-    section.accounts = accounts;
-  }
-  channels[AGENTCHAT_CHANNEL_ID] = section;
-  return { ...cfg, channels };
+// src/channel.wizard.ts
+var JUST_REGISTERED_SENTINEL = "_agentchatJustRegistered";
+var HANDLE_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+var HANDLE_MIN_LENGTH = 3;
+var HANDLE_MAX_LENGTH = 30;
+var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isValidHandleShape(value) {
+  return value.length >= HANDLE_MIN_LENGTH && value.length <= HANDLE_MAX_LENGTH && HANDLE_PATTERN.test(value);
 }
-function isAccountConfigured(cfg, accountId) {
-  return Boolean(readAccountApiKey(cfg, accountId ?? AGENTCHAT_DEFAULT_ACCOUNT_ID));
-}
-async function promptApiKey(prompter) {
-  const value = await prompter.text({
-    message: "Paste your AgentChat API key",
-    placeholder: "ac_live_...",
-    validate: (v) => {
-      const trimmed = v.trim();
-      if (!trimmed) return "API key is required";
-      if (trimmed.length < MIN_API_KEY_LENGTH)
-        return `Looks too short (${trimmed.length} chars \u2014 expect \u2265${MIN_API_KEY_LENGTH})`;
-      return void 0;
-    }
-  });
-  return value.trim();
+var OTP_PATTERN = /^\d{6}$/;
+function hasConfiguredKey(cfg, accountId) {
+  return isApiKeyPresent(readAgentchatConfigField(cfg, accountId, "apiKey"));
 }
+var MAX_START_RETRIES = 5;
 async function promptEmail(prompter) {
-  const value = await prompter.text({
-    message: "Your email address (for OTP verification)",
+  return (await prompter.text({
+    message: "Email address (for the verification code)",
     placeholder: "you@example.com",
-    validate: (v) => {
-      const trimmed = v.trim();
+    validate: (value) => {
+      const trimmed = value.trim();
       if (!trimmed) return "Email is required";
-      if (!/.+@.+\..+/.test(trimmed)) return "Not a valid email address";
+      if (!EMAIL_PATTERN.test(trimmed)) return "That does not look like a valid email address";
       return void 0;
     }
-  });
-  return value.trim();
+  })).trim();
 }
-async function promptHandle(prompter, initial) {
-  const value = await prompter.text({
-    message: "Pick a handle for your agent",
-    placeholder: "alice",
-    initialValue: initial,
-    validate: (v) => {
-      const trimmed = v.trim().toLowerCase();
+async function promptHandle(prompter) {
+  return (await prompter.text({
+    message: "Choose a handle (your @name on AgentChat)",
+    placeholder: "my-agent",
+    validate: (value) => {
+      const trimmed = value.trim();
       if (!trimmed) return "Handle is required";
-      if (!HANDLE_PATTERN.test(trimmed))
-        return "3\u201332 chars; lowercase a-z / 0-9 / dot / underscore / dash";
+      if (!isValidHandleShape(trimmed)) {
+        return "Handle must be 3\u201330 chars \u2014 lowercase letters/digits/hyphens; must start with a letter";
+      }
       return void 0;
     }
-  });
-  return value.trim().toLowerCase();
+  })).trim();
 }
-async function promptOtp(prompter) {
-  const value = await prompter.text({
-    message: "Enter the 6-digit code we emailed you",
-    placeholder: "123456",
-    validate: (v) => /^\d{6}$/.test(v.trim()) ? void 0 : "6-digit numeric code required"
-  });
-  return value.trim();
-}
-async function promptOptionalText(prompter, message, placeholder) {
-  const value = await prompter.text({
-    message,
-    placeholder,
+async function promptDisplayName(prompter) {
+  return (await prompter.text({
+    message: "Display name (optional \u2014 shown next to your handle)",
+    placeholder: "",
     validate: () => void 0
-  });
-  return value.trim();
-}
-function describeRegisterStartFailure(r) {
-  switch (r.reason) {
-    case "invalid-handle":
-      return "That handle is not valid. Use 3\u201332 chars, lowercase a-z / 0-9 / . _ -.";
-    case "handle-taken":
-      return "That handle is already taken. Pick another.";
-    case "email-taken":
-      return "That email already has an agent. Sign in with the existing key instead, or use a different email.";
-    case "email-is-owner":
-      return "That email is reserved. Use a different address.";
-    case "email-exhausted":
-      return "This email has hit the per-address agent limit. Use a different email or delete an old agent.";
-    case "rate-limited":
-      return r.retryAfterSeconds ? `Too many attempts. Try again in ${r.retryAfterSeconds}s.` : "Too many attempts. Try again in a few minutes.";
-    case "otp-failed":
-      return "Could not send the verification email. Check the address and retry.";
-    case "network-error":
-      return `Network error: ${r.message}`;
-    case "validation":
-      return `Validation error: ${r.message}`;
-    case "server-error":
-      return `AgentChat API error (${r.status ?? "??"}): ${r.message}`;
-  }
+  })).trim();
 }
-function describeRegisterVerifyFailure(r) {
-  switch (r.reason) {
-    case "expired":
-      return "That code has expired. We'll request a new one \u2014 restart registration.";
-    case "invalid-code":
-      return "Wrong code. Check the email and try again.";
-    case "rate-limited":
-      return r.retryAfterSeconds ? `Too many attempts. Wait ${r.retryAfterSeconds}s before retrying.` : "Too many attempts. Try again in a few minutes.";
-    case "handle-taken":
-      return "Someone else just took that handle. Restart and pick another.";
-    case "email-taken":
-      return "That email was registered by someone else between these steps. Start over.";
-    case "email-is-owner":
-      return "That email is reserved.";
-    case "network-error":
-      return `Network error: ${r.message}`;
-    case "unexpected-shape":
-      return `Server returned an unexpected response (${r.status ?? "??"}). Try again shortly.`;
-    case "validation":
-      return `Validation error: ${r.message}`;
-    case "server-error":
-      return `AgentChat API error (${r.status ?? "??"}): ${r.message}`;
-  }
-}
-async function runHaveKeyFlow(cfg, accountId, prompter, apiBase) {
-  const apiKey = await promptApiKey(prompter);
-  const progress = prompter.progress("Validating key against AgentChat\u2026");
-  const result = await validateApiKey(apiKey, { apiBase });
-  if (!result.ok) {
-    progress.stop("Key rejected.");
+async function runChangeApiBaseFlow(params) {
+  const { cfg, accountId, prompter } = params;
+  const current = readAgentchatConfigField(cfg, accountId, "apiBase");
+  const input = (await prompter.text({
+    message: "New API base URL (blank to reset to default)",
+    placeholder: current ?? "https://api.agentchat.me",
+    validate: (value) => {
+      const trimmed = value.trim();
+      if (!trimmed) return void 0;
+      try {
+        const url = new URL(trimmed);
+        if (url.protocol !== "https:" && url.protocol !== "http:") {
+          return "API base must use http:// or https://";
+        }
+        return void 0;
+      } catch {
+        return "Not a valid URL";
+      }
+    }
+  })).trim();
+  if (!input) {
+    const patched2 = applyAgentchatAccountPatch(cfg, accountId, {
+      apiBase: void 0
+    });
     await prompter.note(
-      [
-        `AgentChat rejected the key (${result.reason}):`,
-        `  ${result.message}`,
-        "",
-        result.reason === "unauthorized" || result.reason === "deleted" ? "The key is invalid, revoked, or the agent was deleted. Grab a fresh key from agentchat.me/dashboard." : result.reason === "unreachable" || result.reason === "network-error" ? "Could not reach the API. Check your network, then run setup again." : "Try again, or pick the register flow."
-      ].join("\n"),
-      "Validation failed"
+      "API base reset to default (https://api.agentchat.me).",
+      "Updated"
     );
-    return runNewAccountFlow(cfg, accountId, prompter, apiBase);
+    return { cfg: patched2 };
   }
-  progress.stop(`Authenticated as @${result.agent.handle}.`);
-  const next = writeAccountPatch(cfg, accountId, {
-    apiKey,
-    agentHandle: result.agent.handle,
-    ...apiBase ? { apiBase } : {}
+  const patched = applyAgentchatAccountPatch(cfg, accountId, {
+    apiBase: input
   });
-  await prompter.note(
-    [
-      `Connected to AgentChat as @${result.agent.handle}.`,
-      `Email: ${result.agent.email}`,
-      result.agent.displayName ? `Display name: ${result.agent.displayName}` : void 0
-    ].filter((v) => Boolean(v)).join("\n"),
-    "AgentChat configured"
-  );
-  return { cfg: next };
+  await prompter.note(`API base set to ${input}`, "Updated");
+  return { cfg: patched };
 }
-async function runRegisterFlow(cfg, accountId, prompter, apiBase) {
+async function runRegisterFlow(params) {
+  const { cfg, accountId, prompter, apiBase } = params;
   await prompter.note(
     [
-      "We will email a 6-digit code to verify ownership of this address.",
-      "The email is hashed server-side and used only for account recovery."
+      "Registration mints a new AgentChat agent identity tied to your email.",
+      "You will receive a 6-digit code to verify \u2014 check your inbox (and spam)."
     ].join("\n"),
-    "New-agent registration"
-  );
-  const email = await promptEmail(prompter);
-  const handle = await promptHandle(prompter);
-  const displayName = await promptOptionalText(
-    prompter,
-    "Display name (optional, press Enter to skip)",
-    handle
+    "AgentChat: register a new agent"
   );
-  const description = await promptOptionalText(
-    prompter,
-    "Short description of your agent (optional)",
-    "Research assistant that summarises papers"
-  );
-  const startProgress = prompter.progress("Requesting OTP\u2026");
-  const start = await registerAgentStart(
-    {
-      email,
-      handle,
-      displayName: displayName || void 0,
-      description: description || void 0
-    },
-    { apiBase }
-  );
-  if (!start.ok) {
-    startProgress.stop("Registration could not start.");
-    await prompter.note(describeRegisterStartFailure(start), "Registration failed");
-    const retry = await prompter.confirm({
-      message: start.reason === "handle-taken" || start.reason === "invalid-handle" ? "Try a different handle?" : "Try again?",
-      initialValue: true
-    });
-    if (!retry) return { cfg };
-    return runRegisterFlow(cfg, accountId, prompter, apiBase);
+  let email = await promptEmail(prompter);
+  let handle = await promptHandle(prompter);
+  const displayName = await promptDisplayName(prompter);
+  let startResult;
+  let startedOk = false;
+  for (let attempt = 1; attempt <= MAX_START_RETRIES; attempt += 1) {
+    const startSpinner = prompter.progress(
+      attempt === 1 ? "Sending verification code\u2026" : "Retrying\u2026"
+    );
+    try {
+      startResult = await registerAgentStart(
+        {
+          email,
+          handle,
+          ...displayName ? { displayName } : {}
+        },
+        { apiBase }
+      );
+    } catch (err) {
+      startSpinner.stop("Could not reach AgentChat");
+      await prompter.note(
+        `${err instanceof Error ? err.message : String(err)}. Try again when the network is available, or paste an existing key instead.`,
+        "Registration failed"
+      );
+      return "abort";
+    }
+    if (startResult.ok) {
+      startSpinner.stop(`Verification code sent to ${email}`);
+      startedOk = true;
+      break;
+    }
+    startSpinner.stop("Registration rejected");
+    switch (startResult.reason) {
+      case "invalid-handle":
+      case "handle-taken": {
+        const detail = startResult.reason === "handle-taken" ? `Handle @${handle} is already taken.` : "That handle is not acceptable (3\u201330 chars \u2014 lowercase letters/digits/hyphens; must start with a letter).";
+        await prompter.note(`${detail} Pick a different handle and we'll try again.`, "Pick a different handle");
+        handle = await promptHandle(prompter);
+        continue;
+      }
+      case "email-taken": {
+        const choice = await prompter.select({
+          message: `${email} is already registered as an AgentChat agent. What would you like to do?`,
+          options: [
+            {
+              value: "paste",
+              label: "Paste the existing API key for this agent",
+              hint: "recommended if you own the account"
+            },
+            { value: "retry", label: "Use a different email address" },
+            { value: "cancel", label: "Cancel registration" }
+          ],
+          initialValue: "paste"
+        });
+        if (choice === "paste") return "user-chose-paste";
+        if (choice === "cancel") return "abort";
+        email = await promptEmail(prompter);
+        continue;
+      }
+      case "email-exhausted": {
+        const choice = await prompter.select({
+          message: `${email} has reached the per-email agent quota. What next?`,
+          options: [
+            { value: "retry", label: "Use a different email address" },
+            { value: "paste", label: "Paste a key from an existing agent" },
+            { value: "cancel", label: "Cancel registration" }
+          ],
+          initialValue: "retry"
+        });
+        if (choice === "paste") return "user-chose-paste";
+        if (choice === "cancel") return "abort";
+        email = await promptEmail(prompter);
+        continue;
+      }
+      case "rate-limited": {
+        const wait = startResult.retryAfterSeconds ? ` Try again in ${startResult.retryAfterSeconds}s.` : "";
+        await prompter.note(`Too many registration attempts.${wait}`, "Rate limited");
+        return "abort";
+      }
+      case "otp-failed": {
+        await prompter.note(
+          "The verification-code email could not be sent. Try again in a minute, or paste an existing key instead.",
+          "OTP delivery failed"
+        );
+        return "abort";
+      }
+      case "network-error":
+      case "server-error":
+      case "validation":
+      default: {
+        await prompter.note(describeRegisterStartError(startResult), "Could not start registration");
+        return "abort";
+      }
+    }
   }
-  startProgress.stop(`OTP sent to ${email}.`);
-  const pendingId = start.pendingId;
-  for (let attempt = 1; attempt <= OTP_ATTEMPTS; attempt += 1) {
-    const code = await promptOtp(prompter);
-    const verifyProgress = prompter.progress("Verifying code\u2026");
-    const verify = await registerAgentVerify({ pendingId, code }, { apiBase });
-    if (verify.ok) {
-      verifyProgress.stop(`Verified. Agent @${verify.agent.handle} created.`);
-      const next = writeAccountPatch(cfg, accountId, {
-        apiKey: verify.apiKey,
-        agentHandle: verify.agent.handle,
-        ...apiBase ? { apiBase } : {}
-      });
+  if (!startedOk || !startResult || !startResult.ok) {
+    await prompter.note(
+      "Too many attempts. Restart the wizard to try again, or paste an existing key at the next prompt.",
+      "Registration failed"
+    );
+    return "abort";
+  }
+  const maxCodeAttempts = 3;
+  let verifyResult = null;
+  for (let attempt = 1; attempt <= maxCodeAttempts; attempt += 1) {
+    const code = (await prompter.text({
+      message: attempt === 1 ? "Enter the 6-digit verification code from your email" : `Verification code (attempt ${attempt}/${maxCodeAttempts})`,
+      placeholder: "123456",
+      validate: (value) => {
+        const trimmed = value.trim();
+        if (!trimmed) return "Code is required";
+        if (!OTP_PATTERN.test(trimmed)) return "Code is 6 digits";
+        return void 0;
+      }
+    })).trim();
+    const verifySpinner = prompter.progress("Verifying code\u2026");
+    try {
+      verifyResult = await registerAgentVerify({ pendingId: startResult.pendingId, code }, { apiBase });
+    } catch (err) {
+      verifySpinner.stop("Could not reach AgentChat");
       await prompter.note(
-        [
-          "Your AgentChat API key has been written to config.",
-          "",
-          `  handle: @${verify.agent.handle}`,
-          `  email:  ${verify.agent.email}`,
-          "",
-          "Keep the key safe \u2014 it authenticates sends as this agent.",
-          "You can rotate it any time from agentchat.me/dashboard."
-        ].join("\n"),
-        "Registration complete"
+        `${err instanceof Error ? err.message : String(err)}. Try again, or paste an existing key instead.`,
+        "Verification failed"
       );
-      return { cfg: next };
+      return "abort";
     }
-    verifyProgress.stop(`Attempt ${attempt}/${OTP_ATTEMPTS} failed (${verify.reason}).`);
-    await prompter.note(describeRegisterVerifyFailure(verify), "Code rejected");
-    if (verify.reason === "expired") {
-      return runRegisterFlow(cfg, accountId, prompter, apiBase);
+    if (verifyResult.ok) {
+      verifySpinner.stop(`Registered as @${verifyResult.agent.handle}`);
+      break;
     }
-    if (verify.reason !== "invalid-code") {
-      const retry = await prompter.confirm({
-        message: "Start over with different details?",
-        initialValue: true
-      });
-      if (!retry) return { cfg };
-      return runRegisterFlow(cfg, accountId, prompter, apiBase);
+    verifySpinner.stop("Verification failed");
+    if (verifyResult.reason === "invalid-code" && attempt < maxCodeAttempts) {
+      await prompter.note(
+        "That code did not match. Check your email and try again.",
+        "Invalid verification code"
+      );
+      continue;
     }
+    await prompter.note(describeRegisterVerifyError(verifyResult), "Registration failed");
+    return "abort";
   }
+  if (!verifyResult || !verifyResult.ok) {
+    await prompter.note(
+      "Too many incorrect codes. Restart the wizard to receive a new code.",
+      "Registration failed"
+    );
+    return "abort";
+  }
+  const patch = { apiKey: verifyResult.apiKey };
+  if (isValidHandleShape(verifyResult.agent.handle)) {
+    patch.agentHandle = verifyResult.agent.handle;
+  }
+  const nextCfg = applyAgentchatAccountPatch(cfg, accountId, patch);
   await prompter.note(
-    "Too many invalid codes. Restart setup to request a new one.",
-    "Registration aborted"
+    [
+      `Handle:       @${verifyResult.agent.handle}`,
+      `Email:        ${verifyResult.agent.email}`,
+      `API key:      ${redactKey(verifyResult.apiKey)} (saved to your OpenClaw config)`
+    ].join("\n"),
+    "AgentChat account created"
   );
-  return { cfg };
-}
-async function runEditFlow(cfg, accountId, prompter) {
-  const currentKey = readAccountApiKey(cfg, accountId);
-  const currentBase = readAccountApiBase(cfg, accountId);
-  const choice = await prompter.select({
-    message: "AgentChat is already configured. What would you like to do?",
-    options: [
-      {
-        value: "validate",
-        label: "Re-validate the current key",
-        hint: "Hit /agents/me to confirm it still authenticates"
-      },
-      {
-        value: "rotate",
-        label: "Rotate to a new API key",
-        hint: "Paste a freshly generated key or register a new agent"
-      },
-      {
-        value: "change-base",
-        label: "Change API base URL",
-        hint: "Only for self-hosted AgentChat deployments"
-      },
-      { value: "skip", label: "Leave as is", hint: "No changes" }
-    ],
-    initialValue: "validate"
-  });
-  if (choice === "skip") return { cfg };
-  if (choice === "validate") {
-    if (!currentKey) {
-      await prompter.note("No API key is currently set.", "Nothing to validate");
-      return runNewAccountFlow(cfg, accountId, prompter, currentBase);
+  return {
+    cfg: nextCfg,
+    credentialValues: {
+      token: verifyResult.apiKey,
+      [JUST_REGISTERED_SENTINEL]: "1"
     }
-    const progress = prompter.progress("Probing /agents/me\u2026");
-    const result = await validateApiKey(currentKey, { apiBase: currentBase });
-    if (result.ok) {
-      progress.stop(`Still authenticated as @${result.agent.handle}.`);
-      return { cfg };
+  };
+}
+function describeRegisterStartError(result) {
+  switch (result.reason) {
+    case "invalid-handle":
+      return "That handle is not acceptable. Try a different one (3\u201330 chars \u2014 lowercase letters/digits/hyphens; must start with a letter).";
+    case "handle-taken":
+      return "That handle is already taken. Try a different one.";
+    case "email-taken":
+      return "That email is already registered as an agent. Paste the existing key instead, or use a different email.";
+    case "email-exhausted":
+      return "This email has reached the agent quota. Use a different email, or paste a key from an existing agent.";
+    case "rate-limited": {
+      const wait = result.retryAfterSeconds ? ` Try again in ${result.retryAfterSeconds}s.` : "";
+      return `Rate limited.${wait}`;
     }
-    progress.stop("Key no longer works.");
-    await prompter.note(`${result.message} [reason=${result.reason}]`, "Re-validation failed");
-    const doRotate = await prompter.confirm({
-      message: "Rotate to a new key now?",
-      initialValue: true
-    });
-    if (doRotate) return runNewAccountFlow(cfg, accountId, prompter, currentBase);
-    return { cfg };
-  }
-  if (choice === "rotate") {
-    return runNewAccountFlow(cfg, accountId, prompter, currentBase);
+    case "otp-failed":
+      return "The verification-code email could not be sent. Try again in a minute.";
+    case "network-error":
+    case "server-error":
+    case "validation":
+    default:
+      return result.message;
   }
-  const nextBase = await promptOptionalText(
-    prompter,
-    "New API base URL (blank to reset to default)",
-    currentBase ?? "https://api.agentchat.me"
-  );
-  if (nextBase) {
-    try {
-      const url = new URL(nextBase);
-      if (url.protocol !== "https:" && url.protocol !== "http:") {
-        await prompter.note("API base must use http:// or https://. Not updated.", "Ignored");
-        return { cfg };
-      }
-    } catch {
-      await prompter.note("Not a valid URL. API base not updated.", "Ignored");
-      return { cfg };
+}
+function describeRegisterVerifyError(result) {
+  switch (result.reason) {
+    case "expired":
+      return "This code expired. Restart the wizard to receive a new one.";
+    case "invalid-code":
+      return "Too many incorrect codes. Restart the wizard to receive a new one.";
+    case "handle-taken":
+      return "Your chosen handle was claimed by another registration in the meantime. Restart with a different handle.";
+    case "email-taken":
+      return "This email is already registered. Paste the existing key instead.";
+    case "rate-limited": {
+      const wait = result.retryAfterSeconds ? ` Try again in ${result.retryAfterSeconds}s.` : "";
+      return `Rate limited.${wait}`;
     }
+    case "network-error":
+    case "server-error":
+    case "unexpected-shape":
+    case "validation":
+    default:
+      return result.message;
   }
-  const next = writeAccountPatch(cfg, accountId, { apiBase: nextBase || void 0 });
-  await prompter.note(
-    nextBase ? `API base set to ${nextBase}` : "API base reset to default",
-    "Updated"
-  );
-  return { cfg: next };
 }
-async function runNewAccountFlow(cfg, accountId, prompter, apiBase) {
-  const choice = await prompter.select({
-    message: "How do you want to connect this agent?",
-    options: [
-      {
-        value: "register",
-        label: "Register a new agent (email + OTP)",
-        hint: "Mint a fresh API key \u2014 ~60 seconds"
-      },
-      {
-        value: "have-key",
-        label: "I already have an API key",
-        hint: "Paste ac_live_..."
-      }
-    ],
-    initialValue: "register"
-  });
-  if (choice === "have-key") return runHaveKeyFlow(cfg, accountId, prompter, apiBase);
-  return runRegisterFlow(cfg, accountId, prompter, apiBase);
+function redactKey(apiKey) {
+  if (apiKey.length < 12) return "\u2022\u2022\u2022\u2022";
+  return `${apiKey.slice(0, 8)}\u2026${apiKey.slice(-4)}`;
 }
 var agentchatSetupWizard = {
   channel: AGENTCHAT_CHANNEL_ID,
-  resolveShouldPromptAccountIds: () => false,
   status: {
-    configuredLabel: "connected",
-    unconfiguredLabel: "needs API key",
-    configuredHint: "configured",
-    unconfiguredHint: "needs agent credentials",
-    configuredScore: 2,
-    unconfiguredScore: 0,
-    resolveConfigured: ({ cfg, accountId }) => isAccountConfigured(cfg, accountId),
-    resolveStatusLines: async ({ cfg, accountId, configured }) => {
-      if (!configured) return ["AgentChat: needs API key \u2014 run setup to register or paste one"];
-      const id = accountId ?? AGENTCHAT_DEFAULT_ACCOUNT_ID;
-      const key = readAccountApiKey(cfg, id);
-      const apiBase = readAccountApiBase(cfg, id);
-      if (!key) return ["AgentChat: configured (no key visible)"];
-      try {
-        const result = await validateApiKey(key, { apiBase, timeoutMs: 3e3 });
-        if (result.ok) return [`AgentChat: connected as @${result.agent.handle}`];
-        return [`AgentChat: configured (live probe failed: ${result.reason})`];
-      } catch {
-        return ["AgentChat: configured (live probe unreachable)"];
+    configuredLabel: "configured",
+    unconfiguredLabel: "not configured",
+    configuredHint: "AgentChat agent is ready to receive messages",
+    unconfiguredHint: "connect your agent to the AgentChat messaging platform",
+    configuredScore: 90,
+    unconfiguredScore: 30,
+    resolveConfigured: ({ cfg, accountId }) => {
+      return hasConfiguredKey(cfg, accountId ?? "default");
+    },
+    resolveStatusLines: ({ cfg, accountId, configured }) => {
+      const id = accountId ?? "default";
+      if (!configured) {
+        return ["AgentChat: not configured \u2014 the wizard will register you or accept an existing key."];
       }
+      const handle = readAgentchatConfigField(cfg, id, "agentHandle");
+      return [`AgentChat: configured${handle ? ` (@${handle})` : ""}`];
     }
   },
   introNote: {
     title: "AgentChat",
     lines: [
-      "A messaging platform for AI agents \u2014 handle-based routing, realtime WebSocket,",
-      "typed error taxonomy, idempotent sends.",
+      "AgentChat is a messaging platform for AI agents \u2014 direct messages,",
+      "groups, presence, attachments. Registration is free.",
       "",
-      "You can paste an existing API key, or register a new agent inline (email + OTP)."
+      "This wizard will either mint a new account via email OTP, or accept",
+      "an existing API key \u2014 your choice in the next prompt."
     ]
   },
-  prepare: async ({ cfg, accountId, credentialValues }) => {
-    const flow = isAccountConfigured(cfg, accountId) ? "edit" : "new";
-    return { credentialValues: { ...credentialValues, _flow: flow } };
+  prepare: async ({ cfg, accountId, credentialValues, prompter }) => {
+    if (hasConfiguredKey(cfg, accountId) && typeof credentialValues.token === "string") {
+      const editChoice = await prompter.select({
+        message: "AgentChat is already configured. What would you like to do?",
+        options: [
+          {
+            value: "keep",
+            label: "Keep current config",
+            hint: "the credential step will still re-validate on the next run"
+          },
+          {
+            value: "change-base",
+            label: "Change API base URL",
+            hint: "only for self-hosted AgentChat deployments"
+          },
+          {
+            value: "replace-key",
+            label: "Replace the API key",
+            hint: "paste a new key, or register a new agent"
+          }
+        ],
+        initialValue: "keep"
+      });
+      if (editChoice === "keep") return;
+      if (editChoice === "change-base") {
+        return await runChangeApiBaseFlow({ cfg, accountId, prompter });
+      }
+    }
+    const choice = await prompter.select({
+      message: "How would you like to configure AgentChat?",
+      options: [
+        {
+          value: "register",
+          label: "Register a new agent (email OTP)",
+          hint: "no account yet \u2014 the wizard creates one"
+        },
+        {
+          value: "paste",
+          label: "I already have an API key",
+          hint: "paste ac_live_\u2026 on the next prompt"
+        }
+      ],
+      initialValue: "register"
+    });
+    if (choice === "paste") {
+      return;
+    }
+    const apiBase = readAgentchatConfigField(cfg, accountId, "apiBase");
+    try {
+      const result = await runRegisterFlow({ cfg, accountId, prompter, apiBase });
+      if (result === "abort") {
+        await prompter.note(
+          "Registration was not completed. You can still paste an existing API key at the next prompt, or cancel the wizard.",
+          "Falling back to credential entry"
+        );
+        return;
+      }
+      if (result === "user-chose-paste") {
+        return;
+      }
+      return result;
+    } catch (err) {
+      if (err instanceof WizardCancelledError) throw err;
+      await prompter.note(
+        `${err instanceof Error ? err.message : String(err)}`,
+        "Registration flow failed"
+      );
+      return;
+    }
   },
-  credentials: [],
-  finalize: async ({ cfg, accountId, prompter, credentialValues }) => {
-    const rawFlow = credentialValues._flow;
-    const flow = rawFlow === "edit" ? "edit" : "new";
-    const apiBase = readAccountApiBase(cfg, accountId);
-    return flow === "edit" ? await runEditFlow(cfg, accountId, prompter) : await runNewAccountFlow(cfg, accountId, prompter, apiBase);
+  credentials: [
+    {
+      inputKey: "token",
+      providerHint: "agentchat",
+      credentialLabel: "API key",
+      preferredEnvVar: "AGENTCHAT_API_KEY",
+      envPrompt: "AGENTCHAT_API_KEY detected in env. Use it?",
+      keepPrompt: "AgentChat API key already configured. Keep it?",
+      inputPrompt: "Paste your AgentChat API key (ac_live_\u2026)",
+      helpTitle: "AgentChat API key",
+      helpLines: [
+        "Format: ac_live_<base64>, \u226520 chars. Validated against",
+        "GET /v1/agents/me during this wizard \u2014 bad keys fail fast instead",
+        "of flapping reconnects at runtime."
+      ],
+      allowEnv: () => true,
+      shouldPrompt: ({ credentialValues, currentValue }) => {
+        if (credentialValues[JUST_REGISTERED_SENTINEL] === "1") return false;
+        if (!currentValue) return true;
+        return true;
+      },
+      inspect: ({ cfg, accountId }) => {
+        const apiKey = readAgentchatConfigField(cfg, accountId, "apiKey");
+        const configured = isApiKeyPresent(apiKey);
+        const envValue = process.env.AGENTCHAT_API_KEY?.trim();
+        return {
+          accountConfigured: configured,
+          hasConfiguredValue: configured,
+          resolvedValue: configured ? apiKey : void 0,
+          envValue: envValue && envValue.length >= MIN_API_KEY_LENGTH ? envValue : void 0
+        };
+      }
+    }
+  ],
+  finalize: async ({ cfg, accountId, credentialValues, prompter }) => {
+    const apiKey = typeof credentialValues.token === "string" && credentialValues.token.length >= MIN_API_KEY_LENGTH ? credentialValues.token : readAgentchatConfigField(cfg, accountId, "apiKey");
+    if (!apiKey || !isApiKeyPresent(apiKey)) {
+      return;
+    }
+    const apiBase = readAgentchatConfigField(cfg, accountId, "apiBase");
+    const spinner = prompter.progress("Validating API key against AgentChat\u2026");
+    try {
+      const result = await validateApiKey(apiKey, { apiBase });
+      if (result.ok) {
+        spinner.stop(`Authenticated as @${result.agent.handle}`);
+        const existingHandle = readAgentchatConfigField(cfg, accountId, "agentHandle");
+        if (!existingHandle && isValidHandleShape(result.agent.handle)) {
+          return {
+            cfg: applyAgentchatAccountPatch(cfg, accountId, {
+              agentHandle: result.agent.handle
+            })
+          };
+        }
+        return;
+      }
+      spinner.stop(`API key did not pass the live check (${result.reason})`);
+      await prompter.note(
+        [
+          result.message,
+          "",
+          "The config was saved \u2014 you can re-run `openclaw channels add agentchat`",
+          "to replace the key, or edit ~/.openclaw/config.yaml directly."
+        ].join("\n"),
+        "AgentChat validation warning"
+      );
+    } catch (err) {
+      spinner.stop("Could not reach AgentChat for validation");
+      await prompter.note(
+        [
+          err instanceof Error ? err.message : String(err),
+          "",
+          "The config was saved \u2014 the runtime will retry on startup."
+        ].join("\n"),
+        "AgentChat API unreachable"
+      );
+    }
+    return;
   },
   completionNote: {
     title: "AgentChat is ready",
     lines: [
-      "The channel runtime will auto-connect on the next `openclaw` boot.",
-      "Messages addressed to your handle arrive over WebSocket; sends go out",
-      "over HTTPS with at-least-once + idempotent semantics."
+      "Next steps:",
+      "  \u2022 Start OpenClaw \u2014 the AgentChat channel auto-connects via WebSocket.",
+      "  \u2022 DM another agent:  @<handle> <message>",
+      "  \u2022 Docs:              https://agentchat.me/docs"
     ]
   },
-  disable: (cfg) => {
-    const channels = {
-      ...cfg?.channels ?? {}
-    };
-    const existing = channels[AGENTCHAT_CHANNEL_ID];
-    const section = existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
-    section.enabled = false;
-    channels[AGENTCHAT_CHANNEL_ID] = section;
-    return { ...cfg, channels };
-  }
+  disable: (cfg) => setSetupChannelEnabled(cfg, AGENTCHAT_CHANNEL_ID, false)
 };
+var reconnectConfigSchema = z.object({
+  initialBackoffMs: z.number().int().min(100).max(1e4).default(1e3),
+  maxBackoffMs: z.number().int().min(1e3).max(3e5).default(3e4),
+  jitterRatio: z.number().min(0).max(1).default(0.2)
+}).strict();
+var pingConfigSchema = z.object({
+  intervalMs: z.number().int().min(5e3).max(12e4).default(3e4),
+  timeoutMs: z.number().int().min(1e3).max(3e4).default(1e4)
+}).strict();
+var outboundConfigSchema = z.object({
+  maxInFlight: z.number().int().min(1).max(1e4).default(256),
+  sendTimeoutMs: z.number().int().min(1e3).max(6e4).default(15e3)
+}).strict();
+var observabilityConfigSchema = z.object({
+  logLevel: z.enum(["trace", "debug", "info", "warn", "error"]).default("info"),
+  redactKeys: z.array(z.string()).default(["apiKey", "authorization", "cookie", "set-cookie"])
+}).strict();
+var agentHandleSchema = z.string().regex(
+  /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/,
+  "handle must be lowercase letters/digits/hyphens; start with a letter; no trailing or doubled hyphens"
+).min(3, "handle must be at least 3 characters").max(30, "handle must be at most 30 characters");
+var agentchatChannelConfigSchema = z.object({
+  apiBase: z.string().url().default("https://api.agentchat.me"),
+  apiKey: z.string().min(20, "apiKey looks too short for an AgentChat API key"),
+  agentHandle: agentHandleSchema.optional(),
+  // `.prefault({})` — Zod 4 idiom: when the key is missing from input, parse
+  // `{}` through the inner schema so its own per-field defaults kick in.
+  // Using `.default({})` here fails in Zod 4 because the output type's fields
+  // are non-optional once the inner schema has defaults.
+  reconnect: reconnectConfigSchema.prefault({}),
+  ping: pingConfigSchema.prefault({}),
+  outbound: outboundConfigSchema.prefault({}),
+  observability: observabilityConfigSchema.prefault({})
+}).strict();
+function parseChannelConfig(input) {
+  return agentchatChannelConfigSchema.parse(input);
+}
 
 // src/channel.ts
-var AGENTCHAT_CHANNEL_ID = "agentchat";
-var AGENTCHAT_DEFAULT_ACCOUNT_ID = "default";
-var MIN_API_KEY_LENGTH2 = 20;
-function readChannelSection(cfg) {
-  const channels = cfg?.channels;
-  const section = channels?.[AGENTCHAT_CHANNEL_ID];
-  return section && typeof section === "object" && !Array.isArray(section) ? section : void 0;
-}
-function readAccountRaw2(section, accountId) {
-  if (!section) return void 0;
-  const { accounts } = section;
-  if (accounts && typeof accounts === "object" && !Array.isArray(accounts)) {
-    const entry = accounts[accountId];
-    if (entry && typeof entry === "object") return entry;
-  }
-  if (accountId === AGENTCHAT_DEFAULT_ACCOUNT_ID) {
-    const { accounts: _accounts, ...rest } = section;
-    return rest;
-  }
-  return void 0;
-}
-function splitEnabledFromRaw(raw) {
-  if (!raw) return { enabled: true, forParse: void 0 };
-  const { enabled, ...rest } = raw;
-  return { enabled: enabled !== false, forParse: rest };
-}
-function isApiKeyPresent(value) {
-  return typeof value === "string" && value.length >= MIN_API_KEY_LENGTH2;
-}
 var uiHints = {
   apiKey: {
     label: "AgentChat API key",
     placeholder: "ac_live_...",
     sensitive: true,
-    help: "Obtain from AgentChat dashboard \u2192 Settings \u2192 API keys."
+    help: "The setup wizard registers you via email OTP and mints a key \u2014 or paste an existing ac_live_\u2026 key."
   },
   apiBase: {
     label: "API base URL",
@@ -712,7 +798,7 @@ var uiHints = {
   agentHandle: {
     label: "Agent handle",
     placeholder: "my-agent",
-    help: "3\u201332 chars, lowercase alphanumeric plus . _ -"
+    help: "3\u201330 chars, lowercase letters/digits/hyphens; must start with a letter."
   },
   reconnect: { label: "Reconnect backoff", advanced: true },
   ping: { label: "WebSocket ping cadence", advanced: true },
@@ -763,7 +849,7 @@ var agentchatPlugin = {
     resolveAccount(cfg, accountId) {
       const id = accountId ?? AGENTCHAT_DEFAULT_ACCOUNT_ID;
       const section = readChannelSection(cfg);
-      const raw = readAccountRaw2(section, id);
+      const raw = readAccountRaw(section, id);
       const { enabled, forParse } = splitEnabledFromRaw(raw);
       let config = null;
       let parseError = null;
@@ -828,8 +914,8 @@ var agentchatPlugin = {
       if (typeof input.token !== "string" || input.token.trim().length === 0) {
         return "apiKey is required \u2014 pass via --token or run the register flow";
       }
-      if (input.token.length < MIN_API_KEY_LENGTH2) {
-        return `apiKey looks too short (got ${input.token.length} chars, expect \u2265${MIN_API_KEY_LENGTH2})`;
+      if (input.token.length < MIN_API_KEY_LENGTH) {
+        return `apiKey looks too short (got ${input.token.length} chars, expect \u2265${MIN_API_KEY_LENGTH})`;
       }
       if (typeof input.url === "string" && input.url.length > 0) {
         try {
@@ -844,26 +930,10 @@ var agentchatPlugin = {
       return null;
     },
     applyAccountConfig({ cfg, accountId, input }) {
-      const channels = {
-        ...cfg?.channels ?? {}
-      };
-      const currentSection = channels[AGENTCHAT_CHANNEL_ID];
-      const section = currentSection && typeof currentSection === "object" && !Array.isArray(currentSection) ? { ...currentSection } : {};
       const patch = {};
       if (typeof input.token === "string" && input.token.length > 0) patch.apiKey = input.token;
       if (typeof input.url === "string" && input.url.length > 0) patch.apiBase = input.url;
-      if (accountId === AGENTCHAT_DEFAULT_ACCOUNT_ID && !section.accounts) {
-        Object.assign(section, patch);
-      } else {
-        const accounts = {
-          ...section.accounts ?? {}
-        };
-        const prevAccount = typeof accounts[accountId] === "object" && accounts[accountId] !== null ? accounts[accountId] : {};
-        accounts[accountId] = { ...prevAccount, ...patch };
-        section.accounts = accounts;
-      }
-      channels[AGENTCHAT_CHANNEL_ID] = section;
-      return { ...cfg, channels };
+      return applyAgentchatAccountPatch(cfg, accountId, patch);
     },
     /**
      * Post-write probe: call `GET /v1/agents/me` with the key we just wrote