@agentchatme/openclaw 0.2.0

package/dist/index.cjs

@@ -0,0 +1,2412 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var channelCore = require('openclaw/plugin-sdk/channel-core');
+var zod = require('zod');
+var pino = require('pino');
+var ws = require('ws');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var pino__default = /*#__PURE__*/_interopDefault(pino);
+
+// src/channel.ts
+var reconnectConfigSchema = zod.z.object({
+  initialBackoffMs: zod.z.number().int().min(100).max(1e4).default(1e3),
+  maxBackoffMs: zod.z.number().int().min(1e3).max(3e5).default(3e4),
+  jitterRatio: zod.z.number().min(0).max(1).default(0.2)
+}).strict();
+var pingConfigSchema = zod.z.object({
+  intervalMs: zod.z.number().int().min(5e3).max(12e4).default(3e4),
+  timeoutMs: zod.z.number().int().min(1e3).max(3e4).default(1e4)
+}).strict();
+var outboundConfigSchema = zod.z.object({
+  maxInFlight: zod.z.number().int().min(1).max(1e4).default(256),
+  sendTimeoutMs: zod.z.number().int().min(1e3).max(6e4).default(15e3)
+}).strict();
+var observabilityConfigSchema = zod.z.object({
+  logLevel: zod.z.enum(["trace", "debug", "info", "warn", "error"]).default("info"),
+  redactKeys: zod.z.array(zod.z.string()).default(["apiKey", "authorization", "cookie", "set-cookie"])
+}).strict();
+var agentHandleSchema = zod.z.string().regex(/^[a-z0-9_.-]{3,32}$/, "handle must be 3-32 chars, lowercase alphanumeric + . _ -");
+var agentchatChannelConfigSchema = zod.z.object({
+  apiBase: zod.z.string().url().default("https://api.agentchat.me"),
+  apiKey: zod.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/errors.ts
+var AgentChatChannelError = class extends Error {
+  class_;
+  retryAfterMs;
+  statusCode;
+  constructor(class_, message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = "AgentChatChannelError";
+    this.class_ = class_;
+    this.retryAfterMs = options.retryAfterMs;
+    this.statusCode = options.statusCode;
+  }
+};
+function classifyHttpStatus(status, retryAfterHeader) {
+  if (status === 401 || status === 403) return "terminal-auth";
+  if (status === 409) return "idempotent-replay";
+  if (status === 429) return "retry-rate";
+  if (status >= 500 && status <= 599) return "retry-transient";
+  if (status >= 400 && status <= 499) return "terminal-user";
+  return "retry-transient";
+}
+function parseRetryAfter(header, nowMs) {
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.floor(seconds * 1e3);
+  const when = Date.parse(header);
+  if (Number.isFinite(when)) return Math.max(0, when - nowMs);
+  return void 0;
+}
+function classifyNetworkError(err) {
+  if (!err || typeof err !== "object") return "retry-transient";
+  const code = err.code;
+  if (typeof code === "string") {
+    if (code === "ECONNRESET" || code === "ETIMEDOUT" || code === "ECONNREFUSED") {
+      return "retry-transient";
+    }
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN") return "retry-transient";
+  }
+  return "retry-transient";
+}
+
+// src/setup-client.ts
+var DEFAULT_API_BASE = "https://api.agentchat.me";
+var DEFAULT_TIMEOUT_MS = 1e4;
+async function validateApiKey(apiKey, opts = {}) {
+  if (!apiKey || typeof apiKey !== "string") {
+    return { ok: false, reason: "unauthorized", message: "API key is empty" };
+  }
+  const base = (opts.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+  const url = `${base}/v1/agents/me`;
+  const controller = new AbortController();
+  const fetchImpl = opts.fetch ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json"
+      },
+      signal: controller.signal
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const unreachable = err instanceof Error && (err.name === "AbortError" || /ECONN|ETIMEDOUT|ENOTFOUND|EAI_AGAIN/i.test(message));
+    return {
+      ok: false,
+      reason: unreachable ? "unreachable" : "network-error",
+      message: `agentchat: GET /v1/agents/me failed: ${message}`
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+  if (res.status === 401) {
+    return { ok: false, reason: "unauthorized", status: 401, message: "API key is invalid or revoked" };
+  }
+  if (res.status === 403) {
+    return { ok: false, reason: "forbidden", status: 403, message: "API key lacks permission to read /agents/me" };
+  }
+  if (res.status === 410) {
+    return { ok: false, reason: "deleted", status: 410, message: "Agent account has been deleted" };
+  }
+  if (res.status >= 500) {
+    return { ok: false, reason: "server-error", status: res.status, message: `AgentChat API returned ${res.status}` };
+  }
+  if (!res.ok) {
+    return {
+      ok: false,
+      reason: "server-error",
+      status: res.status,
+      message: `AgentChat API returned ${res.status}`
+    };
+  }
+  const body = await res.json().catch(() => null);
+  const email = typeof body?.email === "string" ? body.email : typeof body?.email_masked === "string" ? body.email_masked : null;
+  if (!body || typeof body.handle !== "string" || email === null || typeof body.created_at !== "string") {
+    return {
+      ok: false,
+      reason: "unexpected-shape",
+      status: res.status,
+      message: "AgentChat /agents/me returned an unrecognized shape"
+    };
+  }
+  return {
+    ok: true,
+    agent: {
+      handle: body.handle,
+      displayName: typeof body.display_name === "string" ? body.display_name : null,
+      email,
+      createdAt: body.created_at
+    }
+  };
+}
+async function registerAgentStart(input, opts = {}) {
+  const res = await post("/v1/register", input, opts);
+  if (res.kind === "network") {
+    return { ok: false, reason: "network-error", message: res.message };
+  }
+  if (res.kind === "timeout") {
+    return { ok: false, reason: "network-error", message: "request timed out" };
+  }
+  const body = res.body ?? {};
+  if (res.status === 200) {
+    if (typeof body.pending_id !== "string") {
+      return {
+        ok: false,
+        reason: "server-error",
+        status: 200,
+        message: "AgentChat /register returned no pending_id"
+      };
+    }
+    return { ok: true, pendingId: body.pending_id };
+  }
+  const code = typeof body.code === "string" ? body.code : "";
+  const message = typeof body.message === "string" ? body.message : `status ${res.status}`;
+  if (res.status === 400 && code === "INVALID_HANDLE") return { ok: false, reason: "invalid-handle", message, status: 400 };
+  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 {
+      ok: false,
+      reason: "rate-limited",
+      message,
+      status: 429,
+      retryAfterSeconds: res.retryAfterSeconds
+    };
+  }
+  if (res.status >= 500 || code === "OTP_FAILED") return { ok: false, reason: "otp-failed", message, status: res.status };
+  return { ok: false, reason: "server-error", status: res.status, message };
+}
+async function registerAgentVerify(input, opts = {}) {
+  const res = await post("/v1/register/verify", { pending_id: input.pendingId, code: input.code }, opts);
+  if (res.kind === "network") return { ok: false, reason: "network-error", message: res.message };
+  if (res.kind === "timeout") return { ok: false, reason: "network-error", message: "request timed out" };
+  const body = res.body ?? {};
+  if (res.status === 201) {
+    const agent = body.agent;
+    if (typeof body.api_key !== "string" || !agent || typeof agent.handle !== "string" || typeof agent.email !== "string" || typeof agent.created_at !== "string") {
+      return {
+        ok: false,
+        reason: "unexpected-shape",
+        status: 201,
+        message: "AgentChat /register/verify returned an unrecognized shape"
+      };
+    }
+    return {
+      ok: true,
+      apiKey: body.api_key,
+      agent: {
+        handle: agent.handle,
+        displayName: typeof agent.display_name === "string" ? agent.display_name : null,
+        email: agent.email,
+        createdAt: agent.created_at
+      }
+    };
+  }
+  const code = typeof body.code === "string" ? body.code : "";
+  const message = typeof body.message === "string" ? body.message : `status ${res.status}`;
+  if (res.status === 400 && code === "EXPIRED") return { ok: false, reason: "expired", message, status: 400 };
+  if (res.status === 400 && code === "INVALID_CODE") return { ok: false, reason: "invalid-code", message, status: 400 };
+  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 };
+  }
+  return { ok: false, reason: "server-error", status: res.status, message };
+}
+async function post(path, body, opts) {
+  const base = (opts.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+  const url = `${base}${path}`;
+  const controller = new AbortController();
+  const fetchImpl = opts.fetch ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+    const parsed = await res.json().catch(() => null);
+    const retryAfterHeader = res.headers.get("retry-after");
+    const retryAfterSeconds = retryAfterHeader ? Number(retryAfterHeader) : void 0;
+    return {
+      kind: "http",
+      status: res.status,
+      body: parsed,
+      retryAfterSeconds: Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : void 0
+    };
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") return { kind: "timeout" };
+    return { kind: "network", message: err instanceof Error ? err.message : String(err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function assertApiKeyValid(apiKey, opts = {}) {
+  const result = await validateApiKey(apiKey, opts);
+  if (result.ok) return result.agent;
+  const class_ = result.reason === "unauthorized" || result.reason === "forbidden" || result.reason === "deleted" ? "terminal-auth" : result.reason === "server-error" ? "retry-transient" : "retry-transient";
+  throw new AgentChatChannelError(class_, `${result.message} [reason=${result.reason}]`, {
+    statusCode: result.status
+  });
+}
+
+// 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 };
+}
+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();
+}
+async function promptEmail(prompter) {
+  const value = await prompter.text({
+    message: "Your email address (for OTP verification)",
+    placeholder: "you@example.com",
+    validate: (v) => {
+      const trimmed = v.trim();
+      if (!trimmed) return "Email is required";
+      if (!/.+@.+\..+/.test(trimmed)) return "Not a valid email address";
+      return void 0;
+    }
+  });
+  return value.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();
+      if (!trimmed) return "Handle is required";
+      if (!HANDLE_PATTERN.test(trimmed))
+        return "3\u201332 chars; lowercase a-z / 0-9 / dot / underscore / dash";
+      return void 0;
+    }
+  });
+  return value.trim().toLowerCase();
+}
+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,
+    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}`;
+  }
+}
+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.");
+    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"
+    );
+    return runNewAccountFlow(cfg, accountId, prompter, apiBase);
+  }
+  progress.stop(`Authenticated as @${result.agent.handle}.`);
+  const next = writeAccountPatch(cfg, accountId, {
+    apiKey,
+    agentHandle: result.agent.handle,
+    ...apiBase ? { apiBase } : {}
+  });
+  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 };
+}
+async function runRegisterFlow(cfg, accountId, prompter, apiBase) {
+  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."
+    ].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
+  );
+  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);
+  }
+  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 } : {}
+      });
+      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"
+      );
+      return { cfg: next };
+    }
+    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 (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);
+    }
+  }
+  await prompter.note(
+    "Too many invalid codes. Restart setup to request a new one.",
+    "Registration aborted"
+  );
+  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);
+    }
+    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 };
+    }
+    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);
+  }
+  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 };
+    }
+  }
+  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);
+}
+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)"];
+      }
+    }
+  },
+  introNote: {
+    title: "AgentChat",
+    lines: [
+      "A messaging platform for AI agents \u2014 handle-based routing, realtime WebSocket,",
+      "typed error taxonomy, idempotent sends.",
+      "",
+      "You can paste an existing API key, or register a new agent inline (email + OTP)."
+    ]
+  },
+  prepare: async ({ cfg, accountId, credentialValues }) => {
+    const flow = isAccountConfigured(cfg, accountId) ? "edit" : "new";
+    return { credentialValues: { ...credentialValues, _flow: flow } };
+  },
+  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);
+  },
+  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."
+    ]
+  },
+  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 };
+  }
+};
+
+// 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."
+  },
+  apiBase: {
+    label: "API base URL",
+    placeholder: "https://api.agentchat.me",
+    help: "Override only when targeting a self-hosted AgentChat instance.",
+    advanced: true
+  },
+  agentHandle: {
+    label: "Agent handle",
+    placeholder: "my-agent",
+    help: "3\u201332 chars, lowercase alphanumeric plus . _ -"
+  },
+  reconnect: { label: "Reconnect backoff", advanced: true },
+  ping: { label: "WebSocket ping cadence", advanced: true },
+  outbound: { label: "Outbound send tuning", advanced: true },
+  observability: { label: "Logs & metrics", advanced: true }
+};
+var agentchatPlugin = {
+  id: AGENTCHAT_CHANNEL_ID,
+  meta: {
+    id: AGENTCHAT_CHANNEL_ID,
+    label: "AgentChat",
+    selectionLabel: "AgentChat (messaging platform for agents)",
+    detailLabel: "AgentChat",
+    docsPath: "/channels/agentchat",
+    docsLabel: "agentchat",
+    blurb: "connect your agent to the AgentChat messaging platform \u2014 handles, contacts, groups, presence, attachments.",
+    systemImage: "message",
+    markdownCapable: true,
+    order: 100
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: false,
+    edit: false,
+    unsend: true,
+    reply: true,
+    threads: false,
+    nativeCommands: false
+  },
+  reload: {
+    configPrefixes: [`channels.${AGENTCHAT_CHANNEL_ID}.`]
+  },
+  configSchema: channelCore.buildChannelConfigSchema(agentchatChannelConfigSchema, { uiHints }),
+  setupWizard: agentchatSetupWizard,
+  config: {
+    listAccountIds(cfg) {
+      const section = readChannelSection(cfg);
+      if (!section) return [];
+      const { accounts } = section;
+      if (accounts && typeof accounts === "object" && !Array.isArray(accounts)) {
+        const ids = Object.keys(accounts);
+        if (ids.length > 0) return ids;
+      }
+      const hasFlatFields = typeof section.apiKey === "string" || typeof section.apiBase === "string" || typeof section.agentHandle === "string";
+      return hasFlatFields ? [AGENTCHAT_DEFAULT_ACCOUNT_ID] : [];
+    },
+    resolveAccount(cfg, accountId) {
+      const id = accountId ?? AGENTCHAT_DEFAULT_ACCOUNT_ID;
+      const section = readChannelSection(cfg);
+      const raw = readAccountRaw2(section, id);
+      const { enabled, forParse } = splitEnabledFromRaw(raw);
+      let config = null;
+      let parseError = null;
+      if (forParse && Object.keys(forParse).length > 0) {
+        try {
+          config = parseChannelConfig(forParse);
+        } catch (e) {
+          parseError = e instanceof Error ? e.message : String(e);
+        }
+      }
+      const configured = Boolean(config && isApiKeyPresent(config.apiKey));
+      return { accountId: id, enabled, configured, config, parseError };
+    },
+    defaultAccountId() {
+      return AGENTCHAT_DEFAULT_ACCOUNT_ID;
+    },
+    isEnabled(account) {
+      return account.enabled;
+    },
+    disabledReason(account) {
+      return account.enabled ? "" : "channel disabled via channels.agentchat.enabled=false";
+    },
+    isConfigured(account) {
+      return account.configured;
+    },
+    unconfiguredReason(account) {
+      if (account.parseError) return `config invalid: ${account.parseError}`;
+      if (!account.config) return "missing channels.agentchat configuration";
+      if (!isApiKeyPresent(account.config.apiKey)) return "missing or too-short channels.agentchat.apiKey";
+      return "";
+    },
+    hasConfiguredState({ cfg }) {
+      const section = readChannelSection(cfg);
+      if (!section) return false;
+      const { accounts } = section;
+      if (accounts && typeof accounts === "object" && !Array.isArray(accounts)) {
+        for (const entry of Object.values(accounts)) {
+          if (entry && typeof entry === "object") {
+            const candidate = entry.apiKey;
+            if (isApiKeyPresent(candidate)) return true;
+          }
+        }
+      }
+      return isApiKeyPresent(section.apiKey);
+    },
+    describeAccount(account) {
+      return {
+        accountId: account.accountId,
+        enabled: account.enabled,
+        configured: account.configured,
+        linked: account.configured
+      };
+    }
+  },
+  setup: {
+    /**
+     * Pre-write gate: cheap, sync check that the caller supplied an API key
+     * that's at least plausibly shaped. Real authentication happens in
+     * `afterAccountConfigWritten` via a live /agents/me probe.
+     */
+    validateInput({ input }) {
+      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 (typeof input.url === "string" && input.url.length > 0) {
+        try {
+          const parsed = new URL(input.url);
+          if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+            return "apiBase must be http(s) \u2014 e.g. https://api.agentchat.me";
+          }
+        } catch {
+          return "apiBase is not a valid URL";
+        }
+      }
+      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 };
+    },
+    /**
+     * Post-write probe: call `GET /v1/agents/me` with the key we just wrote
+     * so the operator sees a clear "✓ authenticated as @handle" on success
+     * — or a specific failure reason (invalid, revoked, unreachable) they
+     * can act on *before* the runtime starts flapping reconnects in prod.
+     *
+     * Never throws: setup-time UX is "warn and proceed". If the probe can't
+     * reach the API (airgapped CI, corp proxy during first boot), we still
+     * want the config written so the user can retry without reconfiguring.
+     */
+    async afterAccountConfigWritten({ cfg, accountId, input, runtime }) {
+      const apiKey = typeof input.token === "string" ? input.token : void 0;
+      if (!apiKey) return;
+      const apiBase = typeof input.url === "string" && input.url.length > 0 ? input.url : void 0;
+      const logger = runtime?.logger;
+      try {
+        const result = await validateApiKey(apiKey, { apiBase });
+        if (result.ok) {
+          logger?.info?.(
+            `[agentchat:${accountId}] authenticated as @${result.agent.handle} (${result.agent.email})`
+          );
+        } else {
+          logger?.warn?.(
+            `[agentchat:${accountId}] api key did not pass live check (${result.reason}): ${result.message}`
+          );
+        }
+      } catch (err) {
+        logger?.warn?.(
+          `[agentchat:${accountId}] live key validation failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+};
+var agentchatChannelEntry = channelCore.defineChannelPluginEntry({
+  id: AGENTCHAT_CHANNEL_ID,
+  name: "AgentChat",
+  description: "Connect OpenClaw agents to the AgentChat messaging platform.",
+  plugin: agentchatPlugin
+});
+var agentchatSetupEntry = channelCore.defineSetupPluginEntry(agentchatPlugin);
+
+// src/configured-state.ts
+function hasAgentChatConfiguredState(config) {
+  if (!config || typeof config !== "object") return false;
+  const key = config.apiKey;
+  return typeof key === "string" && key.length >= 20;
+}
+function createLogger(options) {
+  if (options.delegate) {
+    return options.delegate;
+  }
+  const pinoLogger = pino__default.default({
+    level: options.level,
+    base: { plugin: "@agentchatme/openclaw" },
+    redact: {
+      paths: buildRedactPaths(options.redactKeys),
+      censor: "[REDACTED]"
+    },
+    timestamp: pino__default.default.stdTimeFunctions.isoTime
+  });
+  return wrapPino(pinoLogger);
+}
+function buildRedactPaths(keys) {
+  const prefixes = ["", "config.", "headers.", "context.", "req.headers.", "res.headers."];
+  const paths = [];
+  for (const key of keys) {
+    for (const prefix of prefixes) {
+      paths.push(`${prefix}${key}`);
+    }
+  }
+  paths.push(...keys.map((k) => `*.${k}`));
+  return paths;
+}
+function wrapPino(p) {
+  return {
+    trace: (obj, msg) => p.trace(obj, msg),
+    debug: (obj, msg) => p.debug(obj, msg),
+    info: (obj, msg) => p.info(obj, msg),
+    warn: (obj, msg) => p.warn(obj, msg),
+    error: (obj, msg) => p.error(obj, msg),
+    child: (bindings) => wrapPino(p.child(bindings))
+  };
+}
+
+// src/metrics.ts
+function createNoopMetrics() {
+  return {
+    incInboundDelivered: () => void 0,
+    incOutboundSent: () => void 0,
+    incOutboundFailed: () => void 0,
+    incReconnect: () => void 0,
+    observeSendLatency: () => void 0,
+    setConnectionState: () => void 0,
+    setInFlightDepth: () => void 0
+  };
+}
+
+// src/state-machine.ts
+function transition(state, event) {
+  switch (state.kind) {
+    case "DISCONNECTED": {
+      if (event.type === "CONNECT") {
+        return { kind: "CONNECTING", attempt: event.attempt, startedAt: event.now };
+      }
+      if (event.type === "DRAIN_REQUESTED") return { kind: "CLOSED" };
+      if (event.type === "AUTH_REJECTED") return { kind: "AUTH_FAIL", reason: event.reason };
+      return state;
+    }
+    case "CONNECTING": {
+      if (event.type === "SOCKET_OPEN") return { kind: "AUTHENTICATING", startedAt: event.now };
+      if (event.type === "SOCKET_CLOSED") return { kind: "DISCONNECTED" };
+      if (event.type === "AUTH_REJECTED") return { kind: "AUTH_FAIL", reason: event.reason };
+      if (event.type === "DRAIN_REQUESTED") return { kind: "CLOSED" };
+      return state;
+    }
+    case "AUTHENTICATING": {
+      if (event.type === "HELLO_OK") return { kind: "READY", connectedAt: event.now };
+      if (event.type === "AUTH_REJECTED") return { kind: "AUTH_FAIL", reason: event.reason };
+      if (event.type === "SOCKET_CLOSED") return { kind: "DISCONNECTED" };
+      if (event.type === "DRAIN_REQUESTED") return { kind: "CLOSED" };
+      return state;
+    }
+    case "READY": {
+      if (event.type === "PING_TIMEOUT") {
+        return { kind: "DEGRADED", since: event.now, reason: "ping-timeout" };
+      }
+      if (event.type === "BACKPRESSURE") {
+        return { kind: "DEGRADED", since: event.now, reason: event.reason };
+      }
+      if (event.type === "SOCKET_CLOSED") return { kind: "DISCONNECTED" };
+      if (event.type === "AUTH_REJECTED") return { kind: "AUTH_FAIL", reason: event.reason };
+      if (event.type === "DRAIN_REQUESTED") {
+        return { kind: "DRAINING", since: event.now, deadline: event.deadline };
+      }
+      return state;
+    }
+    case "DEGRADED": {
+      if (event.type === "RECOVERED") return { kind: "READY", connectedAt: event.now };
+      if (event.type === "SOCKET_CLOSED") return { kind: "DISCONNECTED" };
+      if (event.type === "AUTH_REJECTED") return { kind: "AUTH_FAIL", reason: event.reason };
+      if (event.type === "DRAIN_REQUESTED") {
+        return { kind: "DRAINING", since: event.now, deadline: event.deadline };
+      }
+      return state;
+    }
+    case "DRAINING": {
+      if (event.type === "DRAIN_COMPLETED") return { kind: "CLOSED" };
+      if (event.type === "SOCKET_CLOSED") return { kind: "CLOSED" };
+      return state;
+    }
+    case "AUTH_FAIL": {
+      if (event.type === "RECONFIGURED") return { kind: "DISCONNECTED" };
+      if (event.type === "DRAIN_REQUESTED") return { kind: "CLOSED" };
+      return state;
+    }
+    case "CLOSED": {
+      return state;
+    }
+  }
+}
+function canSend(state) {
+  return state.kind === "READY" || state.kind === "DEGRADED" || state.kind === "DRAINING";
+}
+function isTerminal(state) {
+  return state.kind === "CLOSED" || state.kind === "AUTH_FAIL";
+}
+
+// src/ws-client.ts
+var HELLO_ACK_TIMEOUT_MS = 4e3;
+var RECONNECT_HARD_CAP_ATTEMPTS = 60;
+var MAX_FRAME_BYTES = 2 * 1024 * 1024;
+var AUTH_CLOSE_CODES = /* @__PURE__ */ new Set([1008, 4401, 4403]);
+var AgentchatWsClient = class {
+  config;
+  logger;
+  metrics;
+  now;
+  WebSocketCtor;
+  random;
+  _setTimeout;
+  _clearTimeout;
+  _setInterval;
+  _clearInterval;
+  state = { kind: "DISCONNECTED" };
+  ws = null;
+  attempt = 0;
+  helloAckTimer = null;
+  pingTimer = null;
+  pongTimer = null;
+  reconnectTimer = null;
+  drainTimer = null;
+  listeners = {
+    stateChanged: /* @__PURE__ */ new Set(),
+    inboundFrame: /* @__PURE__ */ new Set(),
+    error: /* @__PURE__ */ new Set(),
+    authenticated: /* @__PURE__ */ new Set(),
+    closed: /* @__PURE__ */ new Set()
+  };
+  constructor(options) {
+    this.config = options.config;
+    this.logger = options.logger.child({ component: "ws-client" });
+    this.metrics = options.metrics;
+    this.now = options.now ?? Date.now;
+    this.WebSocketCtor = options.webSocketCtor ?? ws.WebSocket;
+    this.random = options.random ?? Math.random;
+    this._setTimeout = options.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+    this._clearTimeout = options.clearTimeout ?? ((h) => clearTimeout(h));
+    this._setInterval = options.setInterval ?? ((fn, ms) => setInterval(fn, ms));
+    this._clearInterval = options.clearInterval ?? ((h) => clearInterval(h));
+    this.metrics.setConnectionState(this.state.kind);
+  }
+  // ─── Public API ──────────────────────────────────────────────────────
+  /** Current connection state. Read-only from the caller's perspective. */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Kick off connection. No-op if already connecting, authenticating, or
+   * ready. Throws on `AUTH_FAIL` — the caller must call `reconfigured()`
+   * after rotating the API key before retrying.
+   */
+  start() {
+    if (this.state.kind === "AUTH_FAIL") {
+      throw new AgentChatChannelError(
+        "terminal-auth",
+        "cannot start: channel is in AUTH_FAIL \u2014 rotate api key and call reconfigured()"
+      );
+    }
+    if (this.state.kind === "CLOSED") {
+      throw new Error("cannot start: client is closed. Create a new instance.");
+    }
+    if (this.state.kind !== "DISCONNECTED") {
+      return;
+    }
+    this.openSocket(1);
+  }
+  /**
+   * Push a client-action frame. Requires `canSend(state)` — returns false
+   * if the socket is not ready. Callers should queue and retry from the
+   * outbound adapter (P4) rather than drop here.
+   */
+  send(frame) {
+    if (!canSend(this.state) || !this.ws || this.ws.readyState !== ws.WebSocket.OPEN) {
+      return false;
+    }
+    try {
+      this.ws.send(JSON.stringify(frame));
+      return true;
+    } catch (err) {
+      this.emitError(
+        new AgentChatChannelError(
+          classifyNetworkError(err),
+          "ws send failed",
+          { cause: err }
+        )
+      );
+      return false;
+    }
+  }
+  /**
+   * Request a graceful drain. The caller-supplied deadline is a Unix-ms
+   * timestamp; after it passes, the socket is force-closed regardless of
+   * remaining in-flight work. Safe to call from any state.
+   */
+  stop(deadline) {
+    const now = this.now();
+    const computedDeadline = deadline ?? now + 5e3;
+    if (this.state.kind === "DRAINING") {
+      if (computedDeadline < this.state.deadline) {
+        this.applyEvent({ type: "DRAIN_REQUESTED", now, deadline: computedDeadline });
+        this.scheduleDrainDeadline(computedDeadline);
+      }
+      return;
+    }
+    if (isTerminal(this.state)) {
+      return;
+    }
+    this.applyEvent({ type: "DRAIN_REQUESTED", now, deadline: computedDeadline });
+    const after = this.state.kind;
+    if (after === "DRAINING") {
+      this.scheduleDrainDeadline(computedDeadline);
+    } else if (after === "CLOSED") {
+      this.closeSocket(1e3, "client drain (immediate)");
+      this.emit("closed");
+    }
+  }
+  /**
+   * Signal that operator has rotated the API key. Transitions from
+   * AUTH_FAIL back to DISCONNECTED; the next `start()` call will attempt
+   * a fresh HELLO with the current config.
+   */
+  reconfigured() {
+    if (this.state.kind !== "AUTH_FAIL") return;
+    this.applyEvent({ type: "RECONFIGURED" });
+  }
+  on(event, handler) {
+    this.listeners[event].add(handler);
+    return () => {
+      this.listeners[event].delete(handler);
+    };
+  }
+  // ─── Internals: socket lifecycle ─────────────────────────────────────
+  openSocket(attempt) {
+    this.attempt = attempt;
+    const now = this.now();
+    this.applyEvent({ type: "CONNECT", now, attempt });
+    const url = `${this.config.apiBase.replace(/^http/, "ws")}/v1/ws`;
+    let ws;
+    try {
+      ws = new this.WebSocketCtor(url, {
+        perMessageDeflate: false,
+        // `ws` auto-pong is on by default — we keep it so heartbeat RTT
+        // is symmetric even when the server initiates the ping.
+        maxPayload: MAX_FRAME_BYTES
+      });
+    } catch (err) {
+      this.emitError(
+        new AgentChatChannelError(
+          classifyNetworkError(err),
+          "ws constructor threw",
+          { cause: err }
+        )
+      );
+      this.scheduleReconnect("ctor-failed");
+      return;
+    }
+    this.ws = ws;
+    this.bindSocket(ws);
+  }
+  bindSocket(ws) {
+    ws.on("open", () => this.handleOpen());
+    ws.on("message", (data, isBinary) => this.handleMessage(data, isBinary));
+    ws.on("pong", () => this.handlePong());
+    ws.on("close", (code, reason) => this.handleClose(code, reason.toString()));
+    ws.on("error", (err) => {
+      this.emitError(
+        new AgentChatChannelError(
+          classifyNetworkError(err),
+          "ws transport error",
+          { cause: err }
+        )
+      );
+    });
+  }
+  handleOpen() {
+    if (!this.ws) return;
+    const now = this.now();
+    this.applyEvent({ type: "SOCKET_OPEN", now });
+    try {
+      this.ws.send(
+        JSON.stringify({ type: "hello", api_key: this.config.apiKey })
+      );
+    } catch (err) {
+      this.emitError(
+        new AgentChatChannelError(
+          "retry-transient",
+          "hello send failed",
+          { cause: err }
+        )
+      );
+      this.closeSocket(1011, "hello send failed");
+      return;
+    }
+    this.helloAckTimer = this._setTimeout(() => {
+      this.helloAckTimer = null;
+      this.logger.warn({ timeoutMs: HELLO_ACK_TIMEOUT_MS }, "hello ack timeout");
+      this.emitError(
+        new AgentChatChannelError("retry-transient", "hello ack timeout")
+      );
+      this.closeSocket(1008, "hello ack timeout");
+    }, HELLO_ACK_TIMEOUT_MS);
+  }
+  handleMessage(data, isBinary) {
+    if (isBinary) {
+      this.logger.warn({}, "received binary frame \u2014 dropping (text-only protocol)");
+      return;
+    }
+    const received = this.now();
+    const text = typeof data === "string" ? data : Array.isArray(data) ? Buffer.concat(data).toString("utf8") : Buffer.isBuffer(data) ? data.toString("utf8") : Buffer.from(data).toString("utf8");
+    if (text.length > MAX_FRAME_BYTES) {
+      this.logger.warn({ bytes: text.length }, "oversized frame \u2014 dropping");
+      return;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch (err) {
+      this.emitError(
+        new AgentChatChannelError(
+          "validation",
+          "malformed json frame",
+          { cause: err }
+        )
+      );
+      return;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      this.emitError(
+        new AgentChatChannelError("validation", "frame not an object")
+      );
+      return;
+    }
+    const obj = parsed;
+    const type = typeof obj.type === "string" ? obj.type : null;
+    if (!type) {
+      this.emitError(
+        new AgentChatChannelError("validation", "frame missing type")
+      );
+      return;
+    }
+    if (this.state.kind === "AUTHENTICATING") {
+      if (type === "hello.ok") {
+        this.handleHelloOk(received);
+        return;
+      }
+      if (type === "hello.error" || type === "auth.rejected" || type === "error") {
+        const reason = this.extractReason(obj) ?? "auth rejected";
+        this.handleAuthRejected(reason);
+        return;
+      }
+      this.logger.warn({ type }, "frame arrived before hello.ok \u2014 ignoring");
+      return;
+    }
+    const payload = this.extractPayload(obj);
+    this.emit("inboundFrame", {
+      type,
+      payload,
+      receivedAt: received,
+      raw: parsed
+    });
+  }
+  extractReason(obj) {
+    const payload = obj.payload;
+    if (payload && typeof payload === "object") {
+      const msg = payload.message;
+      if (typeof msg === "string") return msg;
+      const reason = payload.reason;
+      if (typeof reason === "string") return reason;
+    }
+    const top = obj.message ?? obj.reason;
+    return typeof top === "string" ? top : void 0;
+  }
+  extractPayload(obj) {
+    const payload = obj.payload;
+    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  }
+  handleHelloOk(now) {
+    if (this.helloAckTimer) {
+      this._clearTimeout(this.helloAckTimer);
+      this.helloAckTimer = null;
+    }
+    this.applyEvent({ type: "HELLO_OK", now });
+    this.attempt = 0;
+    this.startHeartbeat();
+    this.emit("authenticated", now);
+  }
+  handleAuthRejected(reason) {
+    if (this.helloAckTimer) {
+      this._clearTimeout(this.helloAckTimer);
+      this.helloAckTimer = null;
+    }
+    this.logger.error({ reason }, "auth rejected \u2014 moving to AUTH_FAIL");
+    this.applyEvent({ type: "AUTH_REJECTED", reason });
+    this.emitError(
+      new AgentChatChannelError("terminal-auth", `auth rejected: ${reason}`)
+    );
+    this.closeSocket(1008, "auth rejected");
+  }
+  handleClose(code, reason) {
+    this.now();
+    const wasAuthenticating = this.state.kind === "AUTHENTICATING";
+    const wasDraining = this.state.kind === "DRAINING";
+    const authClass = AUTH_CLOSE_CODES.has(code);
+    this.stopHeartbeat();
+    if (this.helloAckTimer) {
+      this._clearTimeout(this.helloAckTimer);
+      this.helloAckTimer = null;
+    }
+    this.ws = null;
+    if (authClass && wasAuthenticating) {
+      this.applyEvent({ type: "AUTH_REJECTED", reason: `close ${code}: ${reason}` });
+      this.emitError(
+        new AgentChatChannelError(
+          "terminal-auth",
+          `socket closed with auth code ${code}: ${reason}`
+        )
+      );
+      this.emit("closed");
+      return;
+    }
+    this.applyEvent({ type: "SOCKET_CLOSED", code, reason });
+    if (wasDraining || this.state.kind === "CLOSED") {
+      this.emit("closed");
+      return;
+    }
+    this.logger.info(
+      { code, reason, attempt: this.attempt },
+      "socket closed \u2014 scheduling reconnect"
+    );
+    this.scheduleReconnect(`close-${code}`);
+  }
+  closeSocket(code, reason) {
+    if (!this.ws) return;
+    try {
+      this.ws.close(code, reason);
+    } catch {
+    }
+  }
+  // ─── Internals: heartbeat ────────────────────────────────────────────
+  startHeartbeat() {
+    this.stopHeartbeat();
+    const intervalMs = this.config.ping.intervalMs;
+    this.pingTimer = this._setInterval(() => this.sendPing(), intervalMs);
+  }
+  stopHeartbeat() {
+    if (this.pingTimer) {
+      this._clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+    if (this.pongTimer) {
+      this._clearTimeout(this.pongTimer);
+      this.pongTimer = null;
+    }
+  }
+  sendPing() {
+    if (!this.ws || this.ws.readyState !== ws.WebSocket.OPEN) return;
+    try {
+      this.ws.ping();
+    } catch (err) {
+      this.emitError(
+        new AgentChatChannelError(
+          "retry-transient",
+          "ws ping failed",
+          { cause: err }
+        )
+      );
+      return;
+    }
+    const timeoutMs = this.config.ping.timeoutMs;
+    if (this.pongTimer) this._clearTimeout(this.pongTimer);
+    this.pongTimer = this._setTimeout(() => {
+      this.pongTimer = null;
+      const now = this.now();
+      this.logger.warn({ timeoutMs }, "ping timeout \u2014 declaring degraded");
+      this.applyEvent({ type: "PING_TIMEOUT", now });
+      this.closeSocket(1011, "ping timeout");
+    }, timeoutMs);
+  }
+  handlePong() {
+    if (this.pongTimer) {
+      this._clearTimeout(this.pongTimer);
+      this.pongTimer = null;
+    }
+    if (this.state.kind === "DEGRADED" && this.state.reason === "ping-timeout") {
+      this.applyEvent({ type: "RECOVERED", now: this.now() });
+    }
+  }
+  // ─── Internals: reconnect ────────────────────────────────────────────
+  scheduleReconnect(reason) {
+    if (this.state.kind === "CLOSED" || this.state.kind === "AUTH_FAIL") return;
+    if (this.reconnectTimer) return;
+    const nextAttempt = this.attempt + 1;
+    if (nextAttempt > RECONNECT_HARD_CAP_ATTEMPTS) {
+      const msg = `reconnect hard cap (${RECONNECT_HARD_CAP_ATTEMPTS}) reached`;
+      this.logger.error({ attempt: nextAttempt }, msg);
+      this.applyEvent({ type: "AUTH_REJECTED", reason: msg });
+      this.emitError(
+        new AgentChatChannelError("terminal-auth", msg)
+      );
+      return;
+    }
+    const delay = this.computeReconnectDelay(nextAttempt);
+    this.metrics.incReconnect({ reason });
+    this.logger.info(
+      { attempt: nextAttempt, delayMs: delay, reason },
+      "scheduling reconnect"
+    );
+    this.reconnectTimer = this._setTimeout(() => {
+      this.reconnectTimer = null;
+      this.openSocket(nextAttempt);
+    }, delay);
+  }
+  computeReconnectDelay(attempt) {
+    const { initialBackoffMs, maxBackoffMs, jitterRatio } = this.config.reconnect;
+    const reconnectCount = Math.max(1, attempt - 1);
+    const exp = initialBackoffMs * Math.pow(2, Math.min(reconnectCount - 1, 20));
+    const capped = Math.min(exp, maxBackoffMs);
+    const jitter = 1 - jitterRatio + this.random() * 2 * jitterRatio;
+    return Math.max(0, Math.floor(capped * jitter));
+  }
+  // ─── Internals: drain ────────────────────────────────────────────────
+  scheduleDrainDeadline(deadline) {
+    if (this.drainTimer) this._clearTimeout(this.drainTimer);
+    const now = this.now();
+    const delay = Math.max(0, deadline - now);
+    this.drainTimer = this._setTimeout(() => {
+      this.drainTimer = null;
+      if (this.state.kind === "DRAINING") {
+        this.logger.warn({ deadline }, "drain deadline exceeded \u2014 force-closing");
+        this.applyEvent({ type: "DRAIN_COMPLETED" });
+        this.closeSocket(1e3, "drain deadline");
+        this.emit("closed");
+      }
+    }, delay);
+  }
+  /**
+   * Called by upper layers when their pending work has fully drained, to
+   * let the WS client transition CLOSED earlier than the deadline.
+   */
+  drainCompleted() {
+    if (this.state.kind !== "DRAINING") return;
+    if (this.drainTimer) {
+      this._clearTimeout(this.drainTimer);
+      this.drainTimer = null;
+    }
+    this.applyEvent({ type: "DRAIN_COMPLETED" });
+    this.closeSocket(1e3, "drain completed");
+    this.emit("closed");
+  }
+  // ─── Internals: state machine + emit ─────────────────────────────────
+  applyEvent(event) {
+    const prev = this.state;
+    const next = transition(prev, event);
+    if (next === prev) {
+      this.logger.debug(
+        { from: prev.kind, event: event.type },
+        "transition.invalid"
+      );
+      return;
+    }
+    this.state = next;
+    this.metrics.setConnectionState(next.kind);
+    this.logger.info(
+      { from: prev.kind, to: next.kind, event: event.type },
+      "state transition"
+    );
+    this.emit("stateChanged", next, prev);
+  }
+  emit(event, ...args) {
+    for (const listener of this.listeners[event]) {
+      try {
+        ;
+        listener(...args);
+      } catch (err) {
+        this.logger.error(
+          { event, err: err instanceof Error ? err.message : String(err) },
+          "listener threw \u2014 continuing"
+        );
+      }
+    }
+  }
+  emitError(error) {
+    this.metrics.incOutboundFailed({ errorClass: error.class_ });
+    this.logger.warn(
+      { class: error.class_, message: error.message, statusCode: error.statusCode },
+      "channel error"
+    );
+    this.emit("error", error);
+  }
+};
+var DIRECT_PREFIXES = ["conv_", "dir_"];
+var GROUP_PREFIX = "grp_";
+function classifyConversationId(id) {
+  for (const p of DIRECT_PREFIXES) {
+    if (id.startsWith(p)) return "direct";
+  }
+  if (id.startsWith(GROUP_PREFIX)) return "group";
+  return null;
+}
+var messageContentSchema = zod.z.object({
+  text: zod.z.string().optional(),
+  data: zod.z.record(zod.z.string(), zod.z.unknown()).optional(),
+  attachment_id: zod.z.string().optional()
+}).passthrough();
+var messageSchema = zod.z.object({
+  id: zod.z.string(),
+  conversation_id: zod.z.string(),
+  sender: zod.z.string(),
+  client_msg_id: zod.z.string(),
+  seq: zod.z.number().int().nonnegative(),
+  type: zod.z.enum(["text", "structured", "file", "system"]),
+  content: messageContentSchema,
+  metadata: zod.z.record(zod.z.string(), zod.z.unknown()).default({}),
+  // Per-recipient delivery state lives in `message_deliveries` since
+  // migration 011 — the `messages` row no longer carries `status`,
+  // `delivered_at`, or `read_at`. Fresh-send envelopes over WS omit
+  // them entirely; the drain path (syncUndelivered) still attaches
+  // `status: 'stored'` for backlogged frames. Accept both shapes.
+  status: zod.z.enum(["stored", "delivered", "read"]).optional(),
+  created_at: zod.z.string(),
+  delivered_at: zod.z.string().nullable().optional(),
+  read_at: zod.z.string().nullable().optional()
+}).passthrough();
+var messageNewSchema = messageSchema;
+var messageReadSchema = zod.z.object({
+  conversation_id: zod.z.string(),
+  // Per-agent read cursor. Everything with seq <= through_seq is read.
+  through_seq: zod.z.number().int().nonnegative(),
+  // Handle of the reader (who moved their cursor).
+  reader: zod.z.string(),
+  at: zod.z.string().optional()
+}).passthrough();
+var typingSchema = zod.z.object({
+  conversation_id: zod.z.string(),
+  sender: zod.z.string()
+}).passthrough();
+var presenceUpdateSchema = zod.z.object({
+  handle: zod.z.string(),
+  status: zod.z.enum(["online", "away", "offline"]),
+  last_active_at: zod.z.string().optional(),
+  custom_status: zod.z.string().nullable().optional()
+}).passthrough();
+var rateLimitWarningSchema = zod.z.object({
+  endpoint: zod.z.string().optional(),
+  limit: zod.z.number().optional(),
+  remaining: zod.z.number().optional(),
+  reset_at: zod.z.string().optional(),
+  message: zod.z.string().optional()
+}).passthrough();
+var groupInviteReceivedSchema = zod.z.object({
+  id: zod.z.string(),
+  group_id: zod.z.string(),
+  group_name: zod.z.string(),
+  group_description: zod.z.string().nullable().optional(),
+  group_avatar_url: zod.z.string().nullable().optional(),
+  group_member_count: zod.z.number().int().nonnegative(),
+  inviter_handle: zod.z.string(),
+  created_at: zod.z.string()
+}).passthrough();
+var groupDeletedSchema = zod.z.object({
+  group_id: zod.z.string(),
+  deleted_by_handle: zod.z.string(),
+  deleted_at: zod.z.string()
+}).passthrough();
+function normalizeInbound(frame) {
+  switch (frame.type) {
+    case "message.new":
+      return normalizeMessageNew(frame);
+    case "message.read":
+      return normalizeMessageRead(frame);
+    case "typing.start":
+      return normalizeTyping(frame, "start");
+    case "typing.stop":
+      return normalizeTyping(frame, "stop");
+    case "presence.update":
+      return normalizePresence(frame);
+    case "rate_limit.warning":
+      return normalizeRateLimitWarning(frame);
+    case "group.invite.received":
+      return normalizeGroupInvite(frame);
+    case "group.deleted":
+      return normalizeGroupDeleted(frame);
+    default:
+      return {
+        kind: "unknown",
+        type: frame.type,
+        payload: frame.payload,
+        receivedAt: frame.receivedAt
+      };
+  }
+}
+function validate(schema, payload, eventType) {
+  const parsed = schema.safeParse(payload);
+  if (!parsed.success) {
+    throw new AgentChatChannelError(
+      "validation",
+      `inbound ${eventType} schema invalid: ${parsed.error.message}`,
+      { cause: parsed.error }
+    );
+  }
+  return parsed.data;
+}
+function requireConvKind(conversationId, eventType) {
+  const kind = classifyConversationId(conversationId);
+  if (!kind) {
+    throw new AgentChatChannelError(
+      "validation",
+      `inbound ${eventType} has unknown conversation id prefix: ${conversationId}`
+    );
+  }
+  return kind;
+}
+function normalizeMessageNew(frame) {
+  const msg = validate(messageNewSchema, frame.payload, "message.new");
+  const conversationKind = requireConvKind(msg.conversation_id, "message.new");
+  return {
+    kind: "message",
+    conversationKind,
+    conversationId: msg.conversation_id,
+    sender: msg.sender,
+    messageId: msg.id,
+    clientMsgId: msg.client_msg_id,
+    seq: msg.seq,
+    messageType: msg.type,
+    content: {
+      text: msg.content.text,
+      data: msg.content.data,
+      attachmentId: msg.content.attachment_id
+    },
+    metadata: msg.metadata,
+    status: msg.status ?? null,
+    createdAt: msg.created_at,
+    deliveredAt: msg.delivered_at ?? null,
+    readAt: msg.read_at ?? null,
+    receivedAt: frame.receivedAt
+  };
+}
+function normalizeMessageRead(frame) {
+  const body = validate(messageReadSchema, frame.payload, "message.read");
+  const conversationKind = requireConvKind(body.conversation_id, "message.read");
+  return {
+    kind: "read-receipt",
+    conversationKind,
+    conversationId: body.conversation_id,
+    reader: body.reader,
+    throughSeq: body.through_seq,
+    at: body.at ?? null,
+    receivedAt: frame.receivedAt
+  };
+}
+function normalizeTyping(frame, action) {
+  const body = validate(typingSchema, frame.payload, `typing.${action}`);
+  const conversationKind = requireConvKind(body.conversation_id, `typing.${action}`);
+  return {
+    kind: "typing",
+    action,
+    conversationKind,
+    conversationId: body.conversation_id,
+    sender: body.sender,
+    receivedAt: frame.receivedAt
+  };
+}
+function normalizePresence(frame) {
+  const body = validate(presenceUpdateSchema, frame.payload, "presence.update");
+  return {
+    kind: "presence",
+    handle: body.handle,
+    status: body.status,
+    lastActiveAt: body.last_active_at ?? null,
+    customStatus: body.custom_status ?? null,
+    receivedAt: frame.receivedAt
+  };
+}
+function normalizeRateLimitWarning(frame) {
+  const body = validate(rateLimitWarningSchema, frame.payload, "rate_limit.warning");
+  return {
+    kind: "rate-limit-warning",
+    endpoint: body.endpoint ?? null,
+    limit: body.limit ?? null,
+    remaining: body.remaining ?? null,
+    resetAt: body.reset_at ?? null,
+    message: body.message ?? null,
+    receivedAt: frame.receivedAt
+  };
+}
+function normalizeGroupInvite(frame) {
+  const body = validate(groupInviteReceivedSchema, frame.payload, "group.invite.received");
+  return {
+    kind: "group-invite",
+    inviteId: body.id,
+    groupId: body.group_id,
+    groupName: body.group_name,
+    groupDescription: body.group_description ?? null,
+    groupAvatarUrl: body.group_avatar_url ?? null,
+    groupMemberCount: body.group_member_count,
+    inviterHandle: body.inviter_handle,
+    createdAt: body.created_at,
+    receivedAt: frame.receivedAt
+  };
+}
+function normalizeGroupDeleted(frame) {
+  const body = validate(groupDeletedSchema, frame.payload, "group.deleted");
+  return {
+    kind: "group-deleted",
+    groupId: body.group_id,
+    deletedByHandle: body.deleted_by_handle,
+    deletedAt: body.deleted_at,
+    receivedAt: frame.receivedAt
+  };
+}
+
+// src/retry.ts
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retryWithPolicy(fn, policy) {
+  const random = policy.random ?? Math.random;
+  const sleep = policy.sleep ?? defaultSleep;
+  let totalDelayMs = 0;
+  let lastErr;
+  for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
+    try {
+      const result = await fn(attempt);
+      return { result, attempts: attempt, totalDelayMs };
+    } catch (err) {
+      lastErr = err;
+      if (!(err instanceof AgentChatChannelError)) {
+        throw err;
+      }
+      if (isTerminalClass(err.class_)) {
+        throw err;
+      }
+      if (attempt >= policy.maxAttempts) {
+        throw err;
+      }
+      const delay = backoffDelay({
+        attempt,
+        errorClass: err.class_,
+        retryAfterMs: err.retryAfterMs,
+        policy,
+        random
+      });
+      totalDelayMs += delay;
+      await sleep(delay);
+    }
+  }
+  throw lastErr;
+}
+function isTerminalClass(class_) {
+  return class_ === "terminal-auth" || class_ === "terminal-user" || class_ === "validation" || class_ === "idempotent-replay";
+}
+function backoffDelay({ attempt, errorClass, retryAfterMs, policy, random }) {
+  if (errorClass === "retry-rate" && typeof retryAfterMs === "number") {
+    const jitter2 = 1 + random() * policy.jitterRatio;
+    return Math.min(policy.maxBackoffMs, Math.floor(retryAfterMs * jitter2));
+  }
+  const exp = policy.initialBackoffMs * Math.pow(2, Math.min(attempt - 1, 20));
+  const capped = Math.min(exp, policy.maxBackoffMs);
+  const jitter = 1 - policy.jitterRatio + random() * 2 * policy.jitterRatio;
+  return Math.max(0, Math.floor(capped * jitter));
+}
+var CircuitBreaker = class {
+  opts;
+  now;
+  state = "closed";
+  failureTimestamps = [];
+  openedAt = null;
+  halfOpenAt = null;
+  constructor(opts) {
+    this.opts = opts;
+    this.now = opts.now ?? Date.now;
+  }
+  snapshot() {
+    return {
+      state: this.state,
+      recentFailures: this.failureTimestamps.length,
+      openedAt: this.openedAt,
+      halfOpenAt: this.halfOpenAt
+    };
+  }
+  /**
+   * Check state at call time.
+   *   - `closed` / `half-open` → returns `{ allow: true }`. Caller must
+   *     invoke `onSuccess()` / `onFailure()` after the attempt.
+   *   - `open` → returns `{ allow: false, reason }` so the caller can
+   *     fast-fail without making the network call. If the cooldown has
+   *     elapsed, transitions to `half-open` first and allows one probe.
+   */
+  precheck() {
+    if (this.state === "open") {
+      const now = this.now();
+      const elapsed = now - (this.openedAt ?? now);
+      if (elapsed >= this.opts.cooldownMs) {
+        this.state = "half-open";
+        this.halfOpenAt = now;
+        return { allow: true };
+      }
+      return { allow: false, reason: "circuit open \u2014 API appears unhealthy" };
+    }
+    return { allow: true };
+  }
+  onSuccess() {
+    if (this.state === "half-open") {
+      this.state = "closed";
+      this.openedAt = null;
+      this.halfOpenAt = null;
+    }
+    this.failureTimestamps = [];
+  }
+  /**
+   * Record a failure. Only transient classes count toward the breaker —
+   * terminal-auth/terminal-user/validation failures are caller bugs or
+   * server contract violations, not "API down" signals.
+   */
+  onFailure(errorClass) {
+    if (isTerminalClass(errorClass)) return;
+    const now = this.now();
+    if (this.state === "half-open") {
+      this.state = "open";
+      this.openedAt = now;
+      this.halfOpenAt = null;
+      return;
+    }
+    this.failureTimestamps.push(now);
+    this.trimOldFailures(now);
+    if (this.failureTimestamps.length >= this.opts.failureThreshold) {
+      this.state = "open";
+      this.openedAt = now;
+    }
+  }
+  trimOldFailures(now) {
+    const cutoff = now - this.opts.windowMs;
+    let firstFresh = 0;
+    while (firstFresh < this.failureTimestamps.length && this.failureTimestamps[firstFresh] < cutoff) {
+      firstFresh++;
+    }
+    if (firstFresh > 0) this.failureTimestamps.splice(0, firstFresh);
+  }
+};
+
+// src/version.ts
+var PACKAGE_VERSION = "0.2.0";
+
+// src/outbound.ts
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 4,
+  initialBackoffMs: 250,
+  maxBackoffMs: 1e4,
+  jitterRatio: 0.3
+};
+var DEFAULT_CIRCUIT_OPTIONS = {
+  failureThreshold: 10,
+  windowMs: 6e4,
+  cooldownMs: 3e4
+};
+var OutboundAdapter = class {
+  config;
+  logger;
+  metrics;
+  fetchImpl;
+  now;
+  breaker;
+  retryPolicy;
+  onBacklogWarning;
+  // Backpressure bookkeeping.
+  inFlight = 0;
+  queue = [];
+  queueHardCap;
+  constructor(opts) {
+    this.config = opts.config;
+    this.logger = opts.logger.child({ component: "outbound" });
+    this.metrics = opts.metrics;
+    this.fetchImpl = opts.fetch ?? fetch;
+    this.now = opts.now ?? Date.now;
+    this.onBacklogWarning = opts.onBacklogWarning;
+    this.breaker = new CircuitBreaker(opts.circuitBreaker ?? DEFAULT_CIRCUIT_OPTIONS);
+    this.retryPolicy = {
+      ...DEFAULT_RETRY_POLICY,
+      ...opts.retryPolicy,
+      now: opts.now,
+      random: opts.random,
+      sleep: opts.sleep
+    };
+    this.queueHardCap = Math.max(10, this.config.outbound.maxInFlight * 10);
+  }
+  /**
+   * Send a message. Returns on success; throws `AgentChatChannelError` on
+   * terminal or exhausted-retry failure. The returned `SendResult.message`
+   * is the row the server minted (or echoed back on idempotent replay).
+   */
+  async sendMessage(input) {
+    const clientMsgId = input.clientMsgId ?? this.mintClientMsgId();
+    const correlationId = input.correlationId ?? clientMsgId;
+    const log = this.logger.child({ clientMsgId, correlationId, kind: input.kind });
+    const precheck = this.breaker.precheck();
+    if (!precheck.allow) {
+      this.metrics.incOutboundFailed({ errorClass: "retry-transient" });
+      throw new AgentChatChannelError("retry-transient", precheck.reason);
+    }
+    await this.acquireSlot();
+    const startedAt = this.now();
+    try {
+      const outcome = await retryWithPolicy(
+        (attempt) => this.sendOnce({ input, clientMsgId, attempt, log }),
+        this.retryPolicy
+      );
+      const endedAt = this.now();
+      this.breaker.onSuccess();
+      this.metrics.incOutboundSent({ kind: "message" });
+      this.metrics.observeSendLatency(endedAt - startedAt);
+      return {
+        ...outcome.result,
+        attempts: outcome.attempts,
+        latencyMs: endedAt - startedAt
+      };
+    } catch (err) {
+      if (err instanceof AgentChatChannelError) {
+        this.breaker.onFailure(err.class_);
+        this.metrics.incOutboundFailed({ errorClass: err.class_ });
+        log.warn(
+          { class: err.class_, status: err.statusCode, msg: err.message },
+          "send failed"
+        );
+      } else {
+        this.metrics.incOutboundFailed({ errorClass: "retry-transient" });
+        log.error(
+          { err: err instanceof Error ? err.message : String(err) },
+          "send failed \u2014 unexpected error"
+        );
+      }
+      throw err;
+    } finally {
+      this.releaseSlot();
+    }
+  }
+  /** Current state for observability / health checks. */
+  snapshot() {
+    return {
+      inFlight: this.inFlight,
+      queued: this.queue.length,
+      circuit: this.breaker.snapshot()
+    };
+  }
+  // ─── Internals ───────────────────────────────────────────────────────
+  async sendOnce(args) {
+    const { input, clientMsgId, attempt, log } = args;
+    const body = this.buildBody(input, clientMsgId);
+    const url = `${this.config.apiBase}/v1/messages`;
+    const headers = {
+      "authorization": `Bearer ${this.config.apiKey}`,
+      "content-type": "application/json",
+      "user-agent": `@agentchatme/openclaw/${PACKAGE_VERSION} (+attempt=${attempt})`
+    };
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body)
+      });
+    } catch (err) {
+      throw new AgentChatChannelError(
+        classifyNetworkError(err),
+        `POST /v1/messages network error: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err }
+      );
+    }
+    const requestId = res.headers.get("x-request-id");
+    const idempotentReplay = res.headers.get("idempotent-replay") === "true";
+    const backlogWarning = this.parseBacklogWarning(res.headers.get("x-backlog-warning"));
+    if (res.ok) {
+      const message = await res.json().catch(() => null);
+      if (!message || typeof message !== "object") {
+        throw new AgentChatChannelError(
+          "validation",
+          "POST /v1/messages returned non-JSON success body",
+          { statusCode: res.status }
+        );
+      }
+      if (idempotentReplay) {
+        log.info({ status: res.status, requestId }, "idempotent replay \u2014 server echoed existing message");
+      }
+      if (backlogWarning && this.onBacklogWarning) {
+        try {
+          this.onBacklogWarning(backlogWarning);
+        } catch (err) {
+          log.error(
+            { err: err instanceof Error ? err.message : String(err) },
+            "onBacklogWarning handler threw \u2014 swallowed to protect send path"
+          );
+        }
+      }
+      return { message, backlogWarning, idempotentReplay, requestId };
+    }
+    const errorBody = await res.json().catch(() => null);
+    const retryAfter = parseRetryAfter(res.headers.get("retry-after"), this.now());
+    const errorClass = classifyHttpStatus(res.status, res.headers.get("retry-after"));
+    const serverMessage = errorBody?.message ?? `HTTP ${res.status}`;
+    throw new AgentChatChannelError(
+      errorClass,
+      typeof serverMessage === "string" ? serverMessage : `HTTP ${res.status}`,
+      {
+        statusCode: res.status,
+        retryAfterMs: retryAfter
+      }
+    );
+  }
+  buildBody(input, clientMsgId) {
+    const content = {};
+    if (input.content.text !== void 0) content.text = input.content.text;
+    if (input.content.data !== void 0) content.data = input.content.data;
+    if (input.content.attachmentId !== void 0) content.attachment_id = input.content.attachmentId;
+    if (Object.keys(content).length === 0) {
+      throw new AgentChatChannelError(
+        "terminal-user",
+        "outbound message has empty content \u2014 at least one of text/data/attachmentId required"
+      );
+    }
+    const body = {
+      client_msg_id: clientMsgId,
+      content
+    };
+    if (input.type) body.type = input.type;
+    if (input.metadata) body.metadata = input.metadata;
+    if (input.kind === "direct") body.to = input.to;
+    else body.conversation_id = input.conversationId;
+    return body;
+  }
+  parseBacklogWarning(header) {
+    if (!header) return null;
+    const eq = header.indexOf("=");
+    if (eq <= 0 || eq === header.length - 1) return null;
+    const recipientHandle = header.slice(0, eq).trim();
+    const countStr = header.slice(eq + 1).trim();
+    const undeliveredCount = Number(countStr);
+    if (!recipientHandle) return null;
+    if (!Number.isFinite(undeliveredCount) || !Number.isInteger(undeliveredCount)) return null;
+    return { recipientHandle, undeliveredCount };
+  }
+  mintClientMsgId() {
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj?.randomUUID) return cryptoObj.randomUUID();
+    return `cmsg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
+  }
+  // ─── Backpressure ────────────────────────────────────────────────────
+  async acquireSlot() {
+    if (this.inFlight < this.config.outbound.maxInFlight) {
+      this.inFlight++;
+      this.metrics.setInFlightDepth(this.inFlight);
+      return;
+    }
+    if (this.queue.length >= this.queueHardCap) {
+      throw new AgentChatChannelError(
+        "retry-transient",
+        `outbound queue full (${this.queue.length}) \u2014 shedding load`
+      );
+    }
+    return new Promise((resolve) => {
+      this.queue.push(() => {
+        this.inFlight++;
+        this.metrics.setInFlightDepth(this.inFlight);
+        resolve();
+      });
+    });
+  }
+  releaseSlot() {
+    this.inFlight = Math.max(0, this.inFlight - 1);
+    this.metrics.setInFlightDepth(this.inFlight);
+    const next = this.queue.shift();
+    if (next) next();
+  }
+};
+
+// src/runtime.ts
+var AgentchatChannelRuntime = class {
+  config;
+  handlers;
+  logger;
+  metrics;
+  ws;
+  outbound;
+  now;
+  started = false;
+  authenticated = false;
+  stopPromise = null;
+  constructor(opts) {
+    this.config = opts.config;
+    this.handlers = opts.handlers ?? {};
+    this.now = opts.now ?? Date.now;
+    this.logger = opts.logger ?? createLogger({
+      level: this.config.observability.logLevel,
+      redactKeys: this.config.observability.redactKeys
+    });
+    this.metrics = opts.metrics ?? createNoopMetrics();
+    this.ws = new AgentchatWsClient({
+      config: this.config,
+      logger: this.logger,
+      metrics: this.metrics,
+      webSocketCtor: opts.webSocketCtor,
+      now: opts.now,
+      random: opts.random
+    });
+    this.outbound = new OutboundAdapter({
+      config: this.config,
+      logger: this.logger,
+      metrics: this.metrics,
+      fetch: opts.fetch,
+      now: opts.now,
+      random: opts.random,
+      sleep: opts.sleep,
+      onBacklogWarning: (warning) => {
+        try {
+          this.handlers.onBacklogWarning?.(warning);
+        } catch (err) {
+          this.logger.error(
+            { err: err instanceof Error ? err.message : String(err) },
+            "onBacklogWarning handler threw"
+          );
+        }
+      }
+    });
+    this.bindWsEvents();
+  }
+  /** Open the transport. Idempotent — subsequent calls are no-ops. */
+  start() {
+    if (this.started) return;
+    this.started = true;
+    this.ws.start();
+  }
+  /**
+   * Graceful shutdown. Waits for outbound in-flight to drain up to the
+   * deadline, then force-closes the WS. Returns a promise that resolves
+   * once the WS has emitted `closed`.
+   */
+  stop(deadlineMs) {
+    if (this.stopPromise) return this.stopPromise;
+    const deadline = deadlineMs ?? this.now() + 5e3;
+    this.stopPromise = new Promise((resolve) => {
+      const off = this.ws.on("closed", () => {
+        off();
+        resolve();
+      });
+      this.ws.stop(deadline);
+    });
+    void this.pollUntilIdle(deadline);
+    return this.stopPromise;
+  }
+  async pollUntilIdle(deadline) {
+    const step = 10;
+    for (; ; ) {
+      const snap = this.outbound.snapshot();
+      if (snap.inFlight === 0 && snap.queued === 0) {
+        this.ws.drainCompleted();
+        return;
+      }
+      if (this.now() >= deadline) return;
+      await new Promise((r) => setTimeout(r, step));
+    }
+  }
+  /**
+   * Send an outbound message. Delegates to the OutboundAdapter; callers
+   * should handle `AgentChatChannelError` with class dispatch.
+   */
+  sendMessage(input) {
+    return this.outbound.sendMessage(input);
+  }
+  /** Push a client-action frame over the WS (typing, read-ack, presence). */
+  sendWsAction(type, payload) {
+    return this.ws.send({ type, payload });
+  }
+  /**
+   * Operator has rotated the API key — signal the WS client so it can
+   * exit AUTH_FAIL. The caller is responsible for creating a new runtime
+   * with the updated config OR for calling this after config hot-reload.
+   */
+  reconfigured() {
+    this.ws.reconfigured();
+  }
+  getHealth() {
+    const outSnap = this.outbound.snapshot();
+    return {
+      state: this.ws.getState(),
+      authenticated: this.authenticated,
+      outbound: {
+        inFlight: outSnap.inFlight,
+        queued: outSnap.queued,
+        circuitState: outSnap.circuit.state
+      }
+    };
+  }
+  // ─── Internals ───────────────────────────────────────────────────────
+  bindWsEvents() {
+    this.ws.on("stateChanged", (next, prev) => {
+      if (next.kind !== "READY" && next.kind !== "DEGRADED") {
+        this.authenticated = false;
+      }
+      try {
+        this.handlers.onStateChanged?.(next, prev);
+      } catch (err) {
+        this.logger.error(
+          { err: err instanceof Error ? err.message : String(err) },
+          "onStateChanged handler threw"
+        );
+      }
+    });
+    this.ws.on("authenticated", (at) => {
+      this.authenticated = true;
+      try {
+        this.handlers.onAuthenticated?.(at);
+      } catch (err) {
+        this.logger.error(
+          { err: err instanceof Error ? err.message : String(err) },
+          "onAuthenticated handler threw"
+        );
+      }
+    });
+    this.ws.on("inboundFrame", (frame) => {
+      this.dispatchFrame(frame);
+    });
+    this.ws.on("error", (error) => {
+      try {
+        this.handlers.onError?.(error);
+      } catch (err) {
+        this.logger.error(
+          { err: err instanceof Error ? err.message : String(err) },
+          "onError handler threw"
+        );
+      }
+    });
+  }
+  dispatchFrame(frame) {
+    let normalized;
+    try {
+      normalized = normalizeInbound(frame);
+    } catch (err) {
+      if (err instanceof AgentChatChannelError) {
+        this.logger.warn(
+          { type: frame.type, class: err.class_, message: err.message },
+          "inbound validation failed \u2014 dropping"
+        );
+        try {
+          this.handlers.onValidationError?.(err, frame);
+        } catch (handlerErr) {
+          this.logger.error(
+            { err: handlerErr instanceof Error ? handlerErr.message : String(handlerErr) },
+            "onValidationError handler threw"
+          );
+        }
+      } else {
+        this.logger.error(
+          { err: err instanceof Error ? err.message : String(err) },
+          "inbound normalizer threw unexpectedly"
+        );
+      }
+      return;
+    }
+    this.recordInboundMetric(normalized);
+    try {
+      const result = this.handlers.onInbound?.(normalized);
+      if (result instanceof Promise) {
+        result.catch((err) => {
+          this.logger.error(
+            { err: err instanceof Error ? err.message : String(err), type: normalized.kind },
+            "async onInbound handler rejected"
+          );
+        });
+      }
+    } catch (err) {
+      this.logger.error(
+        { err: err instanceof Error ? err.message : String(err), type: normalized.kind },
+        "onInbound handler threw"
+      );
+    }
+  }
+  recordInboundMetric(n) {
+    switch (n.kind) {
+      case "message":
+        this.metrics.incInboundDelivered({
+          kind: n.conversationKind === "group" ? "group-message" : "message"
+        });
+        break;
+      case "typing":
+        this.metrics.incInboundDelivered({ kind: "typing" });
+        break;
+      case "read-receipt":
+        this.metrics.incInboundDelivered({ kind: "read" });
+        break;
+      case "presence":
+        this.metrics.incInboundDelivered({ kind: "presence" });
+        break;
+      case "rate-limit-warning":
+        this.metrics.incInboundDelivered({ kind: "rate-limit-warning" });
+        break;
+    }
+  }
+};
+
+exports.AGENTCHAT_CHANNEL_ID = AGENTCHAT_CHANNEL_ID;
+exports.AGENTCHAT_DEFAULT_ACCOUNT_ID = AGENTCHAT_DEFAULT_ACCOUNT_ID;
+exports.AgentChatChannelError = AgentChatChannelError;
+exports.AgentchatChannelRuntime = AgentchatChannelRuntime;
+exports.agentchatChannelEntry = agentchatChannelEntry;
+exports.agentchatPlugin = agentchatPlugin;
+exports.agentchatSetupEntry = agentchatSetupEntry;
+exports.agentchatSetupPlugin = agentchatPlugin;
+exports.agentchatSetupWizard = agentchatSetupWizard;
+exports.assertApiKeyValid = assertApiKeyValid;
+exports.default = agentchatChannelEntry;
+exports.hasAgentChatConfiguredState = hasAgentChatConfiguredState;
+exports.parseChannelConfig = parseChannelConfig;
+exports.registerAgentStart = registerAgentStart;
+exports.registerAgentVerify = registerAgentVerify;
+exports.validateApiKey = validateApiKey;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map