feat(chat): support Matrix and Mattermost standalone (#12)

## Added

- Matrix or Mattermost can run as the only chat platform; Slack is no
  longer required to enter chat mode.
- Scheduled insight posts now go to every configured chat platform
  (Slack, Matrix, Mattermost), not just Slack.
- Matrix and Mattermost notifiers retry transient failures (HTTP 429,
  5xx, and common network errors), matching Slack's existing behavior.
- New `InsightSink` abstraction (`src/notify/insightSink.ts`) and
  `RetryNotifier` (`src/notify/retryNotifier.ts`) with unit tests.

## Changed

- `MATRIX_DEFAULT_ROOM_ID` is required whenever any Matrix env is set.
  It is used for scheduled insight posts and auto-join on startup,
  matching how Slack and Mattermost handle their channel.
- Helm chart: Matrix and Mattermost non-sensitive config now sits under
  `config.*` and their tokens under `secrets.*`, matching the Slack
  pattern. Slack token emission is now conditional, so a Matrix-only or
  Mattermost-only deploy no longer ships empty Slack env vars.
- Helm chart: removed env vars the app never read (`KAYTOO_OUTPUT`,
  `POLL_INTERVAL_SECONDS`, `DEDUPE_TTL_SECONDS`, `EGRESS_*`,
  `PORTSCAN_*`, `LOG_INCLUDE_DEBUG_BODIES`, `LOG_REDACT`,
  `MATRIX_SDK_LOG_LEVEL`). Output mode is auto-derived from which chat
  adapter envs are present.
- Helm chart: default image tag resolves to `v{Chart.AppVersion}` so it
  matches the GHCR semver tag convention out of the box.
- Logger reads `NODE_ENV` directly from `process.env`; the `nodeEnv`
  field on `LoggingInit` is gone.
- README: chat adapter section is platform-neutral and links to each
  adapter's setup. Releases section rewritten as a numbered flow.
- Cleaned up non-ASCII punctuation in source comments, tool
  descriptions, and test names. Test regex that intentionally rejects
  smart punctuation keeps its semantics via Unicode escapes.

## Fixed

- Config validation no longer demands Slack env when only Matrix or
  only Mattermost is configured.

Author: kgrubb

README.md

@@ -1,5 +1,5 @@
 > ⚠️ **Notice**  
-> This repo is a small, experimental project built for fun and learning. It’s shared publicly **as-is** with no promised support, roadmap, or guarantees.
+> This repo is a small, experimental project built for fun and learning. It's shared publicly **as-is** with no promised support, roadmap, or guarantees.
 
 <div align="center">
   <img src="assets/kaytoo.png" alt="Kaytoo logo" width="180" />
@@ -98,13 +98,11 @@ Kaytoo is configured via environment variables. For a minimal example, see `.env
 
 #### Environment variables
 
-**Slack** (required for chat mode. See [Slack setup (Socket Mode)](#slack-setup-socket-mode) below)
+**Chat adapters** - configure at least one to run in chat mode. Kaytoo posts scheduled insights to every configured platform and answers chat replies on the same platform a message arrives from. See the per-platform setup and full variable tables below:
 
-| Variable | Required | Default | Notes |
-| --- | --- | --- | --- |
-| `SLACK_BOT_TOKEN` | yes | - | Bot token (`xoxb-...`). |
-| `SLACK_APP_TOKEN` | yes | - | App-level token for Socket Mode (`xapp-...`). |
-| `SLACK_CHANNEL_ID` | yes | - | Channel for scheduled insight posts. |
+- [Slack](#slack): `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`, `SLACK_CHANNEL_ID`
+- [Matrix](#matrix): `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN`, `MATRIX_DEFAULT_ROOM_ID`
+- [Mattermost](#mattermost): `MATTERMOST_URL`, `MATTERMOST_TOKEN`, `MATTERMOST_CHANNEL_ID`
 
 **Search backend** (Choose either OpenSearch or Elasticsearch. Do not set both)
 
@@ -205,7 +203,7 @@ Uses [`matrix-js-sdk`](https://github.com/matrix-org/matrix-js-sdk) with an in-m
 | --- | --- | --- | --- |
 | `MATRIX_HOMESERVER` | yes | - | Homeserver base URL. |
 | `MATRIX_ACCESS_TOKEN` | yes | - | Access token for the bot user. |
-| `MATRIX_DEFAULT_ROOM_ID` | no | - | If set, Kaytoo attempts to join on startup. |
+| `MATRIX_DEFAULT_ROOM_ID` | yes | - | Room for scheduled insight posts. Kaytoo also attempts to join it on startup. |
 
 ##### Setup
 
@@ -224,8 +222,8 @@ Uses [`matrix-js-sdk`](https://github.com/matrix-org/matrix-js-sdk) with an in-m
    - Invite the bot user into each room where Kaytoo should respond.
    - Kaytoo auto-joins rooms it is invited to.
 
-5. **(Optional) default room**:
-   - Set `MATRIX_DEFAULT_ROOM_ID` if you want Kaytoo to attempt to join a specific room on startup.
+5. **Default room**:
+   - Set `MATRIX_DEFAULT_ROOM_ID` to the room that should receive scheduled insight posts. Kaytoo also attempts to join this room on startup.
 
 6. **Run Kaytoo** with OpenSearch/Elasticsearch + LLM configured (same as Slack).
 
@@ -235,7 +233,7 @@ Notes:
 
 #### Mattermost
 
-Inbound messages use the Mattermost WebSocket API (`/api/v4/websocket`); outbound replies use REST.
+Inbound messages use the Mattermost WebSocket API (`/api/v4/websocket`); outbound replies use REST. `MATTERMOST_URL`, `MATTERMOST_TOKEN`, and `MATTERMOST_CHANNEL_ID` enable chat mode.
 
 | Variable | Required | Default | Notes |
 | --- | --- | --- | --- |
@@ -322,7 +320,16 @@ helm upgrade --install kaytoo ./helm/kaytoo \
 
 #### Releases
 
-Pushes to `main` run [`elastiflow/gha-reusable` `prepare-release`](https://github.com/elastiflow/gha-reusable), which may open a pull request that bumps `helm/kaytoo/Chart.yaml`, `package.json`, and prepends `CHANGELOG.md`. **Squash-merge that PR** so the resulting commit subject is exactly `[release vX.Y.Z] (#NNN)` (GitHub’s default squash title matches the PR title). Merging with that message triggers the GitHub release, container push to `ghcr.io/<owner>/<repo>`, and a Helm chart GitHub release plus `cr index` publish to the `gh-pages` branch when GitHub Pages is enabled for that branch.
+Releases are driven by [`elastiflow/gha-reusable`](https://github.com/elastiflow/gha-reusable) `prepare-release`. The flow:
+
+1. **Push to `main`** runs `prepare-release`, which may open a PR that:
+   - bumps `helm/kaytoo/Chart.yaml` and `package.json`
+   - prepends a new entry to `CHANGELOG.md`
+2. **Squash-merge that PR.** Keep GitHub's default squash title so the commit subject is exactly `[release vX.Y.Z] (#NNN)`.
+3. **The release commit** then triggers:
+   - a GitHub release for `vX.Y.Z`
+   - a container push to `ghcr.io/<owner>/<repo>`
+   - a Helm chart GitHub release plus `cr index` publish to the `gh-pages` branch
 
 #### Useful scripts
 

e2e/README.md

@@ -13,7 +13,7 @@ Local stack: **Mermin** + OpenSearch ([`k8s/mermin-stack-values.yaml`](k8s/mermi
 | `npm run e2e:logs` | Tail Kaytoo in-cluster |
 | `npm run e2e:dev` | Run Kaytoo on the host against forwarded OpenSearch |
 
-**Host Helm is not required** — the bootstrap Job runs Helm in-cluster.
+**Host Helm is not required** - the bootstrap Job runs Helm in-cluster.
 
 ## Stack
 
@@ -46,9 +46,9 @@ Created during `e2e:up` (and by `npm run e2e:llm-overlay` for the LLM file only)
 
 | Artifact | Role |
 | --- | --- |
-| `kubeconfig-kind-kaytoo-e2e` | Host / `kind` CLI — API server `https://127.0.0.1:…` |
-| `kubeconfig-kind-kaytoo-e2e.docker` | Docker `kubectl port-forward` sidecars — same cluster, API host `host.docker.internal` |
-| `kaytoo-values.rendered.yaml` | [`k8s/kaytoo-values.yaml`](k8s/kaytoo-values.yaml) + real `OPENSEARCH_PASSWORD` → copied to node as `kaytoo-values.yaml` (**secrets**) |
+| `kubeconfig-kind-kaytoo-e2e` | Host / `kind` CLI - API server `https://127.0.0.1:...` |
+| `kubeconfig-kind-kaytoo-e2e.docker` | Docker `kubectl port-forward` sidecars - same cluster, API host `host.docker.internal` |
+| `kaytoo-values.rendered.yaml` | [`k8s/kaytoo-values.yaml`](k8s/kaytoo-values.yaml) + real `OPENSEARCH_PASSWORD` -> copied to node as `kaytoo-values.yaml` (**secrets**) |
 | `values-e2e.llm.local.json` | LLM Helm `-f` from `.env` via `e2e/write-e2e-llm-overlay.mjs` |
 
 Legacy `e2e/.kubeconfig-kind-*` at the `e2e/` root is moved into `.generated/` on first use.
@@ -60,10 +60,10 @@ npm run e2e:up
 ```
 
 1. kind cluster `kaytoo-e2e` (prompts if it already exists).
-2. `docker build` → `kaytoo-e2e:local` → `kind load`.
+2. `docker build` -> `kaytoo-e2e:local` -> `kind load`.
 3. Writes `.generated/` (LLM JSON, rendered Kaytoo values), copies chart + those files to the control-plane node (`/kaytoo-chart/`), applies bootstrap Job.
-4. Job: metrics-server, Mermin stack, `helm upgrade -i kaytoo … -f kaytoo-values.yaml -f values-e2e.llm.local.json`.
-5. Docker-based port-forwards: OpenSearch **9200**, Dashboards **5601**, chat **18080** → `8080`.
+4. Job: metrics-server, Mermin stack, `helm upgrade -i kaytoo ... -f kaytoo-values.yaml -f values-e2e.llm.local.json`.
+5. Docker-based port-forwards: OpenSearch **9200**, Dashboards **5601**, chat **18080** -> `8080`.
 
 **URLs after up:** OpenSearch `https://127.0.0.1:9200`, Dashboards `http://localhost:5601`, chat `http://127.0.0.1:18080`.
 

helm/kaytoo/templates/_helpers.tpl

@@ -30,4 +30,3 @@ app.kubernetes.io/instance: {{ .Release.Name }}
 {{- default "default" .Values.serviceAccount.name -}}
 {{- end -}}
 {{- end -}}
-

helm/kaytoo/templates/configmap.yaml

@@ -5,11 +5,13 @@ metadata:
   labels:
     {{- include "kaytoo.labels" . | nindent 4 }}
 data:
-  KAYTOO_OUTPUT: {{ .Values.kaytooOutput | quote }}
   {{- if .Values.httpChat.enabled }}
   KAYTOO_HTTP_CHAT_BIND: {{ printf "0.0.0.0:%d" (.Values.httpChat.port | int) | quote }}
   {{- end }}
+  {{- if .Values.config.slack.channelId }}
   SLACK_CHANNEL_ID: {{ .Values.config.slack.channelId | quote }}
+  {{- end }}
+
   OPENSEARCH_URL: {{ .Values.config.opensearch.url | quote }}
   OPENSEARCH_TLS_INSECURE: {{ .Values.config.opensearch.tlsInsecure | quote }}
   OPENSEARCH_INDEX_PATTERN: {{ .Values.config.opensearch.indexPattern | quote }}
@@ -20,36 +22,22 @@ data:
   LLM_BASE_URL: {{ .Values.config.llm.baseUrl | quote }}
   LLM_MODEL: {{ .Values.config.llm.model | quote }}
 
-  POLL_INTERVAL_SECONDS: {{ .Values.config.behavior.pollIntervalSeconds | quote }}
-  DEDUPE_TTL_SECONDS: {{ .Values.config.behavior.dedupeTtlSeconds | quote }}
-
-  EGRESS_MULTIPLIER: {{ .Values.config.thresholds.egressMultiplier | quote }}
-  EGRESS_MIN_BYTES: {{ .Values.config.thresholds.egressMinBytes | quote }}
-  PORTSCAN_PORTS_THRESHOLD: {{ .Values.config.thresholds.portscanDistinctDstPorts | quote }}
-  PORTSCAN_MIN_PACKETS: {{ .Values.config.thresholds.portscanMinPackets | quote }}
-
   LOG_LEVEL: {{ .Values.logging.level | quote }}
-  LOG_INCLUDE_DEBUG_BODIES: {{ .Values.logging.includeDebugBodies | quote }}
-  LOG_REDACT: {{ .Values.logging.redact | quote }}
-  MATRIX_SDK_LOG_LEVEL: {{ .Values.logging.matrixSdkLevel | quote }}
-  {{- if .Values.logging.nodeEnv }}
-  NODE_ENV: {{ .Values.logging.nodeEnv | quote }}
-  {{- end }}
 
-  {{- if and .Values.matrix.homeserver .Values.matrix.accessToken }}
-  MATRIX_HOMESERVER: {{ .Values.matrix.homeserver | quote }}
-  MATRIX_ACCESS_TOKEN: {{ .Values.matrix.accessToken | quote }}
-  {{- if .Values.matrix.defaultRoomId }}
-  MATRIX_DEFAULT_ROOM_ID: {{ .Values.matrix.defaultRoomId | quote }}
+  {{- if .Values.config.matrix.homeserver }}
+  MATRIX_HOMESERVER: {{ .Values.config.matrix.homeserver | quote }}
   {{- end }}
+  {{- if .Values.config.matrix.defaultRoomId }}
+  MATRIX_DEFAULT_ROOM_ID: {{ .Values.config.matrix.defaultRoomId | quote }}
   {{- end }}
 
-  {{- if and .Values.mattermost.url .Values.mattermost.token .Values.mattermost.channelId }}
-  MATTERMOST_URL: {{ .Values.mattermost.url | quote }}
-  MATTERMOST_TOKEN: {{ .Values.mattermost.token | quote }}
-  MATTERMOST_CHANNEL_ID: {{ .Values.mattermost.channelId | quote }}
-  {{- if .Values.mattermost.botUserId }}
-  MATTERMOST_BOT_USER_ID: {{ .Values.mattermost.botUserId | quote }}
+  {{- if .Values.config.mattermost.url }}
+  MATTERMOST_URL: {{ .Values.config.mattermost.url | quote }}
+  {{- end }}
+  {{- if .Values.config.mattermost.channelId }}
+  MATTERMOST_CHANNEL_ID: {{ .Values.config.mattermost.channelId | quote }}
   {{- end }}
+  {{- if .Values.config.mattermost.botUserId }}
+  MATTERMOST_BOT_USER_ID: {{ .Values.config.mattermost.botUserId | quote }}
   {{- end }}
 

helm/kaytoo/templates/deployment.yaml

@@ -19,7 +19,7 @@ spec:
         {{- toYaml .Values.podSecurityContext | nindent 8 }}
       containers:
         - name: kaytoo
-          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default (printf "v%s" .Chart.AppVersion) }}"
           imagePullPolicy: {{ .Values.image.pullPolicy }}
           securityContext:
             {{- toYaml .Values.securityContext | nindent 12 }}

helm/kaytoo/templates/secret.yaml

@@ -7,8 +7,18 @@ metadata:
     {{- include "kaytoo.labels" . | nindent 4 }}
 type: Opaque
 stringData:
+  {{- if .Values.secrets.slackBotToken }}
   SLACK_BOT_TOKEN: {{ .Values.secrets.slackBotToken | quote }}
+  {{- end }}
+  {{- if .Values.secrets.slackAppToken }}
   SLACK_APP_TOKEN: {{ .Values.secrets.slackAppToken | quote }}
+  {{- end }}
+  {{- if .Values.secrets.matrixAccessToken }}
+  MATRIX_ACCESS_TOKEN: {{ .Values.secrets.matrixAccessToken | quote }}
+  {{- end }}
+  {{- if .Values.secrets.mattermostToken }}
+  MATTERMOST_TOKEN: {{ .Values.secrets.mattermostToken | quote }}
+  {{- end }}
   OPENSEARCH_USERNAME: {{ .Values.secrets.opensearchUsername | quote }}
   OPENSEARCH_PASSWORD: {{ .Values.secrets.opensearchPassword | quote }}
   LLM_API_KEY: {{ .Values.secrets.llmApiKey | quote }}

helm/kaytoo/values.yaml

@@ -1,11 +1,8 @@
 replicaCount: 1
 
-# Passed to process env as KAYTOO_OUTPUT (slack | console). Console skips Slack / chat adapters.
-kaytooOutput: slack
-
 image:
-  repository: kaytoo
-  tag: "dev"
+  repository: ghcr.io/elastiflow/kaytoo
+  tag: ""
   pullPolicy: IfNotPresent
 
 serviceAccount:
@@ -33,50 +30,37 @@ resources:
 config:
   slack:
     channelId: ""
+  matrix:
+    homeserver: ""
+    defaultRoomId: ""
+  mattermost:
+    url: ""
+    channelId: ""
+    botUserId: ""
   opensearch:
     url: ""
     tlsInsecure: "false"
-    # Default matches ElastiFlow CODEX-style indices; use elastiflow-flow-* (or your alias) if your cluster uses a different pipeline/mapping. Must align with document fields Kaytoo resolves (see README).
+    # Default matches ElastiFlow CODEX-style indices.
+    # Use elastiflow-flow-* (or your alias) if your cluster uses a different pipeline/mapping.
+    # This must align with document fields that Kaytoo resolves (see README).
     indexPattern: "elastiflow-flow-codex-*"
     mcpUrl: ""
   llm:
     baseUrl: ""
     model: "gpt-5.3-codex"
-  behavior:
-    pollIntervalSeconds: "300"
-    dedupeTtlSeconds: "3600"
-  thresholds:
-    egressMultiplier: "3"
-    egressMinBytes: "50000000"
-    portscanDistinctDstPorts: "50"
-    portscanMinPackets: "200"
 
 secrets:
   existingSecret: ""
   slackBotToken: ""
   slackAppToken: ""
+  matrixAccessToken: ""
+  mattermostToken: ""
   opensearchUsername: ""
   opensearchPassword: ""
   llmApiKey: ""
 
-# Optional adapters (auto-enabled if configured)
-matrix:
-  homeserver: ""
-  accessToken: ""
-  defaultRoomId: ""
-
-mattermost:
-  url: ""
-  token: ""
-  channelId: ""
-  botUserId: ""
-
 logging:
   level: "info"
-  includeDebugBodies: "false"
-  redact: ""
-  matrixSdkLevel: "WARN"
-  nodeEnv: "" # non-empty → ConfigMap `NODE_ENV`; empty → keep image default
 
 networkPolicy:
   enabled: false

src/agent/tools/definitions.ts

@@ -104,7 +104,7 @@ export function buildToolDefinitionList(opts: {
     },
     {
       name: 'topConversations5Tuple',
-      description: 'Top source→destination conversations by bytes using multi_terms on (srcIp,dstIp,srcPort,dstPort,proto).',
+      description: 'Top source->destination conversations by bytes using multi_terms on (srcIp,dstIp,srcPort,dstPort,proto).',
       argsSchema: {
         type: 'object',
         properties: {
@@ -210,7 +210,7 @@ export function buildToolDefinitionList(opts: {
     },
     {
       name: 'namespaceEdgesByBytes',
-      description: 'Top cross-namespace edges by bytes (source namespace → destination namespace).',
+      description: 'Top cross-namespace edges by bytes (source namespace -> destination namespace).',
       argsSchema: {
         type: 'object',
         properties: {

src/agent/tools/handlers/internalRfc1918DstFilter.ts

@@ -19,7 +19,7 @@ export function privateIpv4DstBool(dstIpField: string, opts?: { includeCgnat?: b
   };
 }
 
-/** Internal / private destination IPs including CGNAT (for “internal dst” filters in aggregations). */
+/** Internal / private destination IPs including CGNAT (for "internal dst" filters in aggregations). */
 export function internalRfc1918DstIpFilter(dstIpField: string): Record<string, unknown> {
   return privateIpv4DstBool(dstIpField, { includeCgnat: true });
 }