Move provider to a plugin-architecture (#661)

* refactor: introduce provider plugin registry

* refactor: move provider CLI to plugins

* docs: add provider plugin implementation notes

* refactor: shift provider runtime logic into plugins

* refactor: add plugin defaults and summaries

* docs: update provider plugin notes

* feat(commands): add /commands slash list

* Auto-reply: tidy help message

* Auto-reply: fix status command lint

* Tests: align google shared expectations

* Auto-reply: tidy help message

* Auto-reply: fix status command lint

* refactor: move provider routing into plugins

* test: align agent routing expectations

* docs: update provider plugin notes

* refactor: route replies via provider plugins

* docs: note route-reply plugin hooks

* refactor: extend provider plugin contract

* refactor: derive provider status from plugins

* refactor: unify gateway provider control

* refactor: use plugin metadata in auto-reply

* fix: parenthesize cron target selection

* refactor: derive gateway methods from plugins

* refactor: generalize provider logout

* refactor: route provider logout through plugins

* refactor: move WhatsApp web login methods into plugin

* refactor: generalize provider log prefixes

* refactor: centralize default chat provider

* refactor: derive provider lists from registry

* refactor: move provider reload noops into plugins

* refactor: resolve web login provider via alias

* refactor: derive CLI provider options from plugins

* refactor: derive prompt provider list from plugins

* style: apply biome lint fixes

* fix: resolve provider routing edge cases

* docs: update provider plugin refactor notes

* fix(gateway): harden agent provider routing

* refactor: move provider routing into plugins

* refactor: move provider CLI to plugins

* refactor: derive provider lists from registry

* fix: restore slash command parsing

* refactor: align provider ids for schema

* refactor: unify outbound target resolution

* fix: keep outbound labels stable

* feat: add msteams to cron surfaces

* fix: clean up lint build issues

* refactor: localize chat provider alias normalization

* refactor: drive gateway provider lists from plugins

* docs: update provider plugin notes

* style: format message-provider

* fix: avoid provider registry init cycles

* style: sort message-provider imports

* fix: relax provider alias map typing

* refactor: move provider routing into plugins

* refactor: add plugin pairing/config adapters

* refactor: route pairing and provider removal via plugins

* refactor: align auto-reply provider typing

* test: stabilize telegram media mocks

* docs: update provider plugin refactor notes

* refactor: pluginize outbound targets

* refactor: pluginize provider selection

* refactor: generalize text chunk limits

* docs: update provider plugin notes

* refactor: generalize group session/config

* fix: normalize provider id for room detection

* fix: avoid provider init in system prompt

* style: formatting cleanup

* refactor: normalize agent delivery targets

* test: update outbound delivery labels

* chore: fix lint regressions

* refactor: extend provider plugin adapters

* refactor: move elevated/block streaming defaults to plugins

* refactor: defer outbound send deps to plugins

* docs: note plugin-driven streaming/elevated defaults

* refactor: centralize webchat provider constant

* refactor: add provider setup adapters

* refactor: delegate provider add config to plugins

* docs: document plugin-driven provider add

* refactor: add plugin state/binding metadata

* refactor: build agent provider status from plugins

* docs: note plugin-driven agent bindings

* refactor: centralize internal provider constant usage

* fix: normalize WhatsApp targets for groups and E.164 (#631) (thanks @imfing)

* refactor: centralize default chat provider

* refactor: centralize WhatsApp target normalization

* refactor: move provider routing into plugins

* refactor: normalize agent delivery targets

* chore: fix lint regressions

* fix: normalize WhatsApp targets for groups and E.164 (#631) (thanks @imfing)

* feat: expand provider plugin adapters

* refactor: route auto-reply via provider plugins

* fix: align WhatsApp target normalization

* fix: normalize WhatsApp targets for groups and E.164 (#631) (thanks @imfing)

* refactor: centralize WhatsApp target normalization

* feat: add /config chat config updates

* docs: add /config get alias

* feat(commands): add /commands slash list

* refactor: centralize default chat provider

* style: apply biome lint fixes

* chore: fix lint regressions

* fix: clean up whatsapp allowlist typing

* style: format config command helpers

* refactor: pluginize tool threading context

* refactor: normalize session announce targets

* docs: note new plugin threading and announce hooks

* refactor: pluginize message actions

* docs: update provider plugin actions notes

* fix: align provider action adapters

* refactor: centralize webchat checks

* style: format message provider helpers

* refactor: move provider onboarding into adapters

* docs: note onboarding provider adapters

* feat: add msteams onboarding adapter

* style: organize onboarding imports

* fix: normalize msteams allowFrom types

* feat: add plugin text chunk limits

* refactor: use plugin chunk limit fallbacks

* feat: add provider mention stripping hooks

* style: organize provider plugin type imports

* refactor: generalize health snapshots

* refactor: update macOS health snapshot handling

* docs: refresh health snapshot notes

* style: format health snapshot updates

* refactor: drive security warnings via plugins

* docs: note provider security adapter

* style: format provider security adapters

* refactor: centralize provider account defaults

* refactor: type gateway client identity constants

* chore: regen gateway protocol swift

* fix: degrade health on failed provider probe

* refactor: centralize pairing approve hint

* docs: add plugin CLI command references

* refactor: route auth and tool sends through plugins

* docs: expand provider plugin hooks

* refactor: document provider docking touchpoints

* refactor: normalize internal provider defaults

* refactor: streamline outbound delivery wiring

* refactor: make provider onboarding plugin-owned

* refactor: support provider-owned agent tools

* refactor: move telegram draft chunking into telegram module

* refactor: infer provider tool sends via extractToolSend

* fix: repair plugin onboarding imports

* refactor: de-dup outbound target normalization

* style: tidy plugin and agent imports

* refactor: data-drive provider selection line

* fix: satisfy lint after provider plugin rebase

* test: deflake gateway-cli coverage

* style: format gateway-cli coverage test

* refactor(provider-plugins): simplify provider ids

* test(pairing-cli): avoid provider-specific ternary

* style(macos): swiftformat HealthStore

* refactor(sandbox): derive provider tool denylist

* fix(sandbox): avoid plugin init in defaults

* refactor(provider-plugins): centralize provider aliases

* style(test): satisfy biome

* refactor(protocol): v3 providers.status maps

* refactor(ui): adapt to protocol v3

* refactor(macos): adapt to protocol v3

* test: update providers.status v3 fixtures

* refactor(gateway): map provider runtime snapshot

* test(gateway): update reload runtime snapshot

* refactor(whatsapp): normalize heartbeat provider id

* docs(refactor): update provider plugin notes

* style: satisfy biome after rebase

* fix: describe sandboxed elevated in prompt

* feat(gateway): add agent image attachments + live probe

* refactor: derive CLI provider options from plugins

* fix(gateway): harden agent provider routing

* fix(gateway): harden agent provider routing

* refactor: align provider ids for schema

* fix(protocol): keep agent provider string

* fix(gateway): harden agent provider routing

* fix(protocol): keep agent provider string

* refactor: normalize agent delivery targets

* refactor: support provider-owned agent tools

* refactor(config): provider-keyed elevated allowFrom

* style: satisfy biome

* fix(gateway): appease provider narrowing

* style: satisfy biome

* refactor(reply): move group intro hints into plugin

* fix(reply): avoid plugin registry init cycle

* refactor(providers): add lightweight provider dock

* refactor(gateway): use typed client id in connect

* refactor(providers): document docks and avoid init cycles

* refactor(providers): make media limit helper generic

* fix(providers): break plugin registry import cycles

* style: satisfy biome

* refactor(status-all): build providers table from plugins

* refactor(gateway): delegate web login to provider plugin

* refactor(provider): drop web alias

* refactor(provider): lazy-load monitors

* style: satisfy lint/format

* style: format status-all providers table

* style: swiftformat gateway discovery model

* test: make reload plan plugin-driven

* fix: avoid token stringification in status-all

* refactor: make provider IDs explicit in status

* feat: warn on signal/imessage provider runtime errors

* test: cover gateway provider runtime warnings in status

* fix: add runtime kind to provider status issues

* test: cover health degradation on probe failure

* fix: keep routeReply lightweight

* style: organize routeReply imports

* refactor(web): extract auth-store helpers

* refactor(whatsapp): lazy login imports

* refactor(outbound): route replies via plugin outbound

* docs: update provider plugin notes

* style: format provider status issues

* fix: make sandbox scope warning wrap-safe

* refactor: load outbound adapters from provider plugins

* docs: update provider plugin outbound notes

* style(macos): fix swiftformat lint

* docs: changelog for provider plugins

* fix(macos): satisfy swiftformat

* fix(macos): open settings via menu action

* style: format after rebase

* fix(macos): open Settings via menu action

---------

Co-authored-by: LK <luke@kyohere.com>
Co-authored-by: Luke K (pr-0f3t) <2609441+lc0rp@users.noreply.github.com>
Co-authored-by: Xin <xin@imfing.com>

src/gateway/protocol/client-info.ts

@@ -0,0 +1,74 @@
+export const GATEWAY_CLIENT_IDS = {
+  WEBCHAT_UI: "webchat-ui",
+  CONTROL_UI: "clawdbot-control-ui",
+  WEBCHAT: "webchat",
+  CLI: "cli",
+  GATEWAY_CLIENT: "gateway-client",
+  MACOS_APP: "clawdbot-macos",
+  TEST: "test",
+  FINGERPRINT: "fingerprint",
+  PROBE: "clawdbot-probe",
+} as const;
+
+export type GatewayClientId =
+  (typeof GATEWAY_CLIENT_IDS)[keyof typeof GATEWAY_CLIENT_IDS];
+
+// Back-compat naming (internal): these values are IDs, not display names.
+export const GATEWAY_CLIENT_NAMES = GATEWAY_CLIENT_IDS;
+export type GatewayClientName = GatewayClientId;
+
+export const GATEWAY_CLIENT_MODES = {
+  WEBCHAT: "webchat",
+  CLI: "cli",
+  UI: "ui",
+  BACKEND: "backend",
+  PROBE: "probe",
+  TEST: "test",
+} as const;
+
+export type GatewayClientMode =
+  (typeof GATEWAY_CLIENT_MODES)[keyof typeof GATEWAY_CLIENT_MODES];
+
+export type GatewayClientInfo = {
+  id: GatewayClientId;
+  displayName?: string;
+  version: string;
+  platform: string;
+  deviceFamily?: string;
+  modelIdentifier?: string;
+  mode: GatewayClientMode;
+  instanceId?: string;
+};
+
+const GATEWAY_CLIENT_ID_SET = new Set<GatewayClientId>(
+  Object.values(GATEWAY_CLIENT_IDS),
+);
+const GATEWAY_CLIENT_MODE_SET = new Set<GatewayClientMode>(
+  Object.values(GATEWAY_CLIENT_MODES),
+);
+
+export function normalizeGatewayClientId(
+  raw?: string | null,
+): GatewayClientId | undefined {
+  const normalized = raw?.trim().toLowerCase();
+  if (!normalized) return undefined;
+  return GATEWAY_CLIENT_ID_SET.has(normalized as GatewayClientId)
+    ? (normalized as GatewayClientId)
+    : undefined;
+}
+
+export function normalizeGatewayClientName(
+  raw?: string | null,
+): GatewayClientName | undefined {
+  return normalizeGatewayClientId(raw);
+}
+
+export function normalizeGatewayClientMode(
+  raw?: string | null,
+): GatewayClientMode | undefined {
+  const normalized = raw?.trim().toLowerCase();
+  if (!normalized) return undefined;
+  return GATEWAY_CLIENT_MODE_SET.has(normalized as GatewayClientMode)
+    ? (normalized as GatewayClientMode)
+    : undefined;
+}

src/gateway/protocol/index.ts

@@ -86,8 +86,12 @@ import {
   type PresenceEntry,
   PresenceEntrySchema,
   ProtocolSchemas,
+  type ProvidersLogoutParams,
+  ProvidersLogoutParamsSchema,
   type ProvidersStatusParams,
   ProvidersStatusParamsSchema,
+  type ProvidersStatusResult,
+  ProvidersStatusResultSchema,
   type RequestFrame,
   RequestFrameSchema,
   type ResponseFrame,
@@ -247,6 +251,9 @@ export const validateTalkModeParams =
 export const validateProvidersStatusParams = ajv.compile<ProvidersStatusParams>(
   ProvidersStatusParamsSchema,
 );
+export const validateProvidersLogoutParams = ajv.compile<ProvidersLogoutParams>(
+  ProvidersLogoutParamsSchema,
+);
 export const validateModelsListParams = ajv.compile<ModelsListParams>(
   ModelsListParamsSchema,
 );
@@ -344,6 +351,8 @@ export {
   WizardStartResultSchema,
   WizardStatusResultSchema,
   ProvidersStatusParamsSchema,
+  ProvidersStatusResultSchema,
+  ProvidersLogoutParamsSchema,
   WebLoginStartParamsSchema,
   WebLoginWaitParamsSchema,
   AgentSummarySchema,
@@ -409,6 +418,8 @@ export type {
   WizardStatusResult,
   TalkModeParams,
   ProvidersStatusParams,
+  ProvidersStatusResult,
+  ProvidersLogoutParams,
   WebLoginStartParams,
   WebLoginWaitParams,
   AgentSummary,

src/gateway/protocol/schema.ts

@@ -1,5 +1,6 @@
 import { type Static, type TSchema, Type } from "@sinclair/typebox";
 import { SESSION_LABEL_MAX_LENGTH } from "../../sessions/session-label.js";
+import { GATEWAY_CLIENT_IDS, GATEWAY_CLIENT_MODES } from "./client-info.js";
 
 const NonEmptyString = Type.String({ minLength: 1 });
 const SessionLabelString = Type.String({
@@ -7,6 +8,13 @@ const SessionLabelString = Type.String({
   maxLength: SESSION_LABEL_MAX_LENGTH,
 });
 
+const GatewayClientIdSchema = Type.Union(
+  Object.values(GATEWAY_CLIENT_IDS).map((value) => Type.Literal(value)),
+);
+const GatewayClientModeSchema = Type.Union(
+  Object.values(GATEWAY_CLIENT_MODES).map((value) => Type.Literal(value)),
+);
+
 export const PresenceEntrySchema = Type.Object(
   {
     host: Type.Optional(NonEmptyString),
@@ -69,12 +77,13 @@ export const ConnectParamsSchema = Type.Object(
     maxProtocol: Type.Integer({ minimum: 1 }),
     client: Type.Object(
       {
-        name: NonEmptyString,
+        id: GatewayClientIdSchema,
+        displayName: Type.Optional(NonEmptyString),
         version: NonEmptyString,
         platform: NonEmptyString,
         deviceFamily: Type.Optional(NonEmptyString),
         modelIdentifier: Type.Optional(NonEmptyString),
-        mode: NonEmptyString,
+        mode: GatewayClientModeSchema,
         instanceId: Type.Optional(NonEmptyString),
       },
       { additionalProperties: false },
@@ -587,6 +596,68 @@ export const ProvidersStatusParamsSchema = Type.Object(
   { additionalProperties: false },
 );
 
+// Provider docking: providers.status is intentionally schema-light so new
+// providers can ship without protocol updates.
+export const ProviderAccountSnapshotSchema = Type.Object(
+  {
+    accountId: NonEmptyString,
+    name: Type.Optional(Type.String()),
+    enabled: Type.Optional(Type.Boolean()),
+    configured: Type.Optional(Type.Boolean()),
+    linked: Type.Optional(Type.Boolean()),
+    running: Type.Optional(Type.Boolean()),
+    connected: Type.Optional(Type.Boolean()),
+    reconnectAttempts: Type.Optional(Type.Integer({ minimum: 0 })),
+    lastConnectedAt: Type.Optional(Type.Integer({ minimum: 0 })),
+    lastError: Type.Optional(Type.String()),
+    lastStartAt: Type.Optional(Type.Integer({ minimum: 0 })),
+    lastStopAt: Type.Optional(Type.Integer({ minimum: 0 })),
+    lastInboundAt: Type.Optional(Type.Integer({ minimum: 0 })),
+    lastOutboundAt: Type.Optional(Type.Integer({ minimum: 0 })),
+    lastProbeAt: Type.Optional(Type.Integer({ minimum: 0 })),
+    mode: Type.Optional(Type.String()),
+    dmPolicy: Type.Optional(Type.String()),
+    allowFrom: Type.Optional(Type.Array(Type.String())),
+    tokenSource: Type.Optional(Type.String()),
+    botTokenSource: Type.Optional(Type.String()),
+    appTokenSource: Type.Optional(Type.String()),
+    baseUrl: Type.Optional(Type.String()),
+    allowUnmentionedGroups: Type.Optional(Type.Boolean()),
+    cliPath: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    dbPath: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    port: Type.Optional(
+      Type.Union([Type.Integer({ minimum: 0 }), Type.Null()]),
+    ),
+    probe: Type.Optional(Type.Unknown()),
+    audit: Type.Optional(Type.Unknown()),
+    application: Type.Optional(Type.Unknown()),
+  },
+  { additionalProperties: true },
+);
+
+export const ProvidersStatusResultSchema = Type.Object(
+  {
+    ts: Type.Integer({ minimum: 0 }),
+    providerOrder: Type.Array(NonEmptyString),
+    providerLabels: Type.Record(NonEmptyString, NonEmptyString),
+    providers: Type.Record(NonEmptyString, Type.Unknown()),
+    providerAccounts: Type.Record(
+      NonEmptyString,
+      Type.Array(ProviderAccountSnapshotSchema),
+    ),
+    providerDefaultAccountId: Type.Record(NonEmptyString, NonEmptyString),
+  },
+  { additionalProperties: false },
+);
+
+export const ProvidersLogoutParamsSchema = Type.Object(
+  {
+    provider: NonEmptyString,
+    accountId: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+);
+
 export const WebLoginStartParamsSchema = Type.Object(
   {
     force: Type.Optional(Type.Boolean()),
@@ -718,15 +789,7 @@ export const CronPayloadSchema = Type.Union([
       timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1 })),
       deliver: Type.Optional(Type.Boolean()),
       provider: Type.Optional(
-        Type.Union([
-          Type.Literal("last"),
-          Type.Literal("whatsapp"),
-          Type.Literal("telegram"),
-          Type.Literal("discord"),
-          Type.Literal("slack"),
-          Type.Literal("signal"),
-          Type.Literal("imessage"),
-        ]),
+        Type.Union([Type.Literal("last"), NonEmptyString]),
       ),
       to: Type.Optional(Type.String()),
       bestEffortDeliver: Type.Optional(Type.Boolean()),
@@ -975,6 +1038,8 @@ export const ProtocolSchemas: Record<string, TSchema> = {
   WizardStatusResult: WizardStatusResultSchema,
   TalkModeParams: TalkModeParamsSchema,
   ProvidersStatusParams: ProvidersStatusParamsSchema,
+  ProvidersStatusResult: ProvidersStatusResultSchema,
+  ProvidersLogoutParams: ProvidersLogoutParamsSchema,
   WebLoginStartParams: WebLoginStartParamsSchema,
   WebLoginWaitParams: WebLoginWaitParamsSchema,
   AgentSummary: AgentSummarySchema,
@@ -1006,7 +1071,7 @@ export const ProtocolSchemas: Record<string, TSchema> = {
   ShutdownEvent: ShutdownEventSchema,
 };
 
-export const PROTOCOL_VERSION = 2 as const;
+export const PROTOCOL_VERSION = 3 as const;
 
 export type ConnectParams = Static<typeof ConnectParamsSchema>;
 export type HelloOk = Static<typeof HelloOkSchema>;
@@ -1052,6 +1117,8 @@ export type WizardStartResult = Static<typeof WizardStartResultSchema>;
 export type WizardStatusResult = Static<typeof WizardStatusResultSchema>;
 export type TalkModeParams = Static<typeof TalkModeParamsSchema>;
 export type ProvidersStatusParams = Static<typeof ProvidersStatusParamsSchema>;
+export type ProvidersStatusResult = Static<typeof ProvidersStatusResultSchema>;
+export type ProvidersLogoutParams = Static<typeof ProvidersLogoutParamsSchema>;
 export type WebLoginStartParams = Static<typeof WebLoginStartParamsSchema>;
 export type WebLoginWaitParams = Static<typeof WebLoginWaitParamsSchema>;
 export type AgentSummary = Static<typeof AgentSummarySchema>;