@interactive-inc/claude-funnel 0.26.1 → 0.28.0

package/dist/connector-diagnostic-log-OPpPi9V9.d.ts

@@ -0,0 +1,208 @@
+import { z } from "zod";
+
+//#region lib/connectors/connector-listener.d.ts
+type NotifyFn = (content: string, meta?: Record<string, string>) => Promise<void>;
+/**
+ * Long-lived event source for one connector.
+ *
+ * `start()` opens the underlying connection (Slack Socket Mode, Discord
+ * Gateway, GH polling, schedule tick) and pushes events through `notify`.
+ * `stop()` releases the resources so the supervisor can recreate the listener
+ * with new config without restarting the whole gateway. `isAlive()` lets the
+ * supervisor periodically health-check and auto-restart dead listeners; the
+ * default optimistic implementation is fine for poll/tick-based listeners
+ * that self-heal.
+ */
+declare abstract class FunnelConnectorListener {
+  abstract start(notify: NotifyFn): Promise<void>;
+  abstract stop(): Promise<void>;
+  isAlive(): boolean;
+}
+//#endregion
+//#region lib/engine/logger/logger.d.ts
+/**
+ * Structured logger with three levels and an optional log-file path.
+ * Defaults to NodeFunnelLogger (appends to `<os.tmpdir()>/funnel/funnel.log`);
+ * MemoryFunnelLogger captures entries in memory and NoopFunnelLogger silences output.
+ */
+declare abstract class FunnelLogger {
+  abstract info(message: string, meta?: Record<string, unknown>): void;
+  abstract warn(message: string, meta?: Record<string, unknown>): void;
+  abstract error(message: string, meta?: Record<string, unknown>): void;
+  abstract readonly file: string | null;
+}
+//#endregion
+//#region lib/gateway/connector-diagnostic-log.d.ts
+/**
+ * Points in the listener's connection lifecycle. The single source of truth
+ * for the value set: the `status` column schema, the `ConnectorConnectionStatus`
+ * union, and the runtime Set used to narrow on read-back all derive from this
+ * array, so adding a status is a one-line change that cannot drift out of sync.
+ *
+ *   started       start() was called
+ *   connected     the socket opened and events can flow
+ *   disconnected  the socket was closed by a stop() call (a clean teardown)
+ *   auth-failed   the token was rejected before the socket opened
+ *   stopped       the listener was fully torn down (always follows a stop(),
+ *                 paired with the disconnected/error that preceded it)
+ *   error         start/stop threw, or Bolt surfaced an error frame — this is
+ *                 also where an unsolicited socket drop shows up when Bolt
+ *                 reports it (an `error` with no following `stopped` means the
+ *                 supervisor recycled the listener, not a clean stop)
+ *
+ * A connection row is independent of any single inbound event, so it carries
+ * no `eventId`. This is how "no notification arrived because the listener
+ * never connected (or dropped, or failed auth)" becomes visible: the
+ * raw/processed tables only hold events that *did* arrive.
+ */
+declare const CONNECTOR_CONNECTION_STATUSES: readonly ["started", "connected", "disconnected", "auth-failed", "stopped", "error"];
+type ConnectorConnectionStatus = (typeof CONNECTOR_CONNECTION_STATUSES)[number];
+/**
+ * Rows stored in the diagnostic tables. Connector-agnostic on purpose: `type`
+ * carries the listener kind ("slack" | "discord" | "gh" | "schedule") so new
+ * connectors land in the same tables without a schema change. `event_id` is
+ * the correlation key the listener mints once per inbound event and stamps
+ * onto both the raw and processed rows, so the two are joinable even though
+ * they live in separate tables with independent `seq` counters.
+ *
+ * These schemas mirror the stored shape (snake_case columns) the way
+ * `FunnelEvent` does for the replay log; they exist for `z.infer` and to
+ * document the column set, not as a parse boundary.
+ */
+declare const connectorRawEventSchema: z.ZodObject<{
+  event_id: z.ZodString;
+  type: z.ZodString;
+  connector_id: z.ZodNullable<z.ZodString>;
+  channel_id: z.ZodNullable<z.ZodString>;
+  payload: z.ZodString;
+}, z.core.$strip>;
+type ConnectorRawEvent = z.infer<typeof connectorRawEventSchema>;
+declare const connectorProcessedEventSchema: z.ZodObject<{
+  event_id: z.ZodString;
+  type: z.ZodString;
+  connector_id: z.ZodNullable<z.ZodString>;
+  channel_id: z.ZodNullable<z.ZodString>;
+  outcome: z.ZodString;
+  payload: z.ZodString;
+}, z.core.$strip>;
+type ConnectorProcessedEvent = z.infer<typeof connectorProcessedEventSchema>;
+declare const connectorConnectionEventSchema: z.ZodObject<{
+  type: z.ZodString;
+  connector_id: z.ZodNullable<z.ZodString>;
+  channel_id: z.ZodNullable<z.ZodString>;
+  status: z.ZodEnum<{
+    error: "error";
+    started: "started";
+    connected: "connected";
+    disconnected: "disconnected";
+    "auth-failed": "auth-failed";
+    stopped: "stopped";
+  }>;
+  detail: z.ZodString;
+}, z.core.$strip>;
+type ConnectorConnectionEvent = z.infer<typeof connectorConnectionEventSchema>;
+/** The connector a row belongs to — the axis every diagnostic table shares. */
+type ConnectorRef = {
+  type: string;
+  connectorId: string | null;
+  channelId: string | null;
+};
+/** A row tied to one inbound event, joinable to its twin by `eventId`. */
+type ConnectorEventKeys = ConnectorRef & {
+  /** Correlation id shared by the raw and processed rows of the same inbound event. */eventId: string;
+};
+/** One untouched inbound event to persist, before any processing. */
+type ConnectorRawRecord = ConnectorEventKeys & {
+  /** The listener's untouched payload, already JSON-stringified by the caller. */payload: string;
+};
+/** The processor's verdict for one inbound event. */
+type ConnectorProcessedRecord = ConnectorEventKeys & {
+  /**
+   * "emitted" on successful delivery, "emitted:delivery-failed" when the
+   * downstream notify threw, or "skip:<reason>" when the processor dropped it.
+   */
+  outcome: string;
+  /**
+   * The delivered body (content + meta) for an emitted event. For a skipped
+   * event there is no body, so the listener records the event JSON here
+   * instead — keeping a skipped row self-describing rather than blank.
+   */
+  payload: string;
+};
+type ConnectorConnectionRecord = ConnectorRef & {
+  status: ConnectorConnectionStatus; /** Free-form context (an error message, a reason) or "" when none. */
+  detail: string;
+};
+/**
+ * Filters every table query accepts — the read-side mirror of `ConnectorRef`.
+ * Each per-table query extends this with its own table's column, the same way
+ * each record extends `ConnectorRef`, so neither half of the file treats one
+ * table's shape as the base for the others.
+ */
+type ConnectorQuery = {
+  type?: string;
+  connectorId?: string | null;
+  channelId?: string | null; /** Cap on returned rows. The most recent matching rows are returned, oldest first. */
+  limit?: number;
+};
+type ConnectorRawQuery = ConnectorQuery;
+type ConnectorProcessedQuery = ConnectorQuery & {
+  outcome?: string;
+};
+type ConnectorConnectionQuery = ConnectorQuery & {
+  status?: ConnectorConnectionStatus;
+};
+/**
+ * A stored row, ascending by `seq`. `seq` is per-table (each table counts
+ * independently) and is for ordering within one table, not for correlating
+ * across them — use `eventId` to join raw and processed.
+ */
+type StoredRawEvent = ConnectorRawRecord & {
+  seq: number;
+  ts: number;
+};
+type StoredProcessedEvent = ConnectorProcessedRecord & {
+  seq: number;
+  ts: number;
+};
+type StoredConnectionEvent = ConnectorConnectionRecord & {
+  seq: number;
+  ts: number;
+};
+/**
+ * Three-table diagnostic log of everything a connector listener does, so
+ * "why was there no notification?" is answerable whichever way it failed:
+ *   - `raw` — every inbound event, before any filtering, with the listener's
+ *     untouched payload (the Slack Bolt event, the GH webhook, …)
+ *   - `processed` — the verdict for that event: `outcome` (emitted, or the
+ *     reason it was dropped) and, when emitted, the body that was delivered.
+ *     Shares an `eventId` with its raw row, so the two join into one story.
+ *   - `connection` — the listener's lifecycle (started, connected, dropped,
+ *     auth-failed, stopped, errored). This is the half the event tables can't
+ *     show: an event that never arrived leaves no raw row, but a listener that
+ *     never connected leaves a `connection` trail that says so.
+ *
+ * The three are physically separate (independent retention and payload-size
+ * policy) so a query never crosses them by accident and a huge raw payload
+ * never bloats the verdict or lifecycle trails. None flow to WS clients or the
+ * MCP channel — this is a separate store from `FunnelEventLog` (replay) and
+ * exists solely for debugging.
+ *
+ * Implementations:
+ *   - `SqliteConnectorDiagnosticLog` — the default; survives daemon restarts,
+ *     bounded by per-table row/age caps.
+ *   - `MemoryConnectorDiagnosticLog` — an in-process double for tests.
+ */
+declare abstract class ConnectorDiagnosticLog {
+  abstract recordRaw(record: ConnectorRawRecord): void;
+  abstract recordProcessed(record: ConnectorProcessedRecord): void;
+  abstract recordConnection(record: ConnectorConnectionRecord): void;
+  abstract queryRaw(query: ConnectorRawQuery): StoredRawEvent[];
+  abstract queryProcessed(query: ConnectorProcessedQuery): StoredProcessedEvent[];
+  abstract queryConnection(query: ConnectorConnectionQuery): StoredConnectionEvent[];
+  /** Drop every diagnostic row across all three tables and reclaim the files. */
+  abstract clear(): void;
+  abstract close(): void;
+}
+//#endregion
+export { NotifyFn as S, connectorConnectionEventSchema as _, ConnectorConnectionStatus as a, FunnelLogger as b, ConnectorProcessedQuery as c, ConnectorRawEvent as d, ConnectorRawQuery as f, StoredRawEvent as g, StoredProcessedEvent as h, ConnectorConnectionRecord as i, ConnectorProcessedRecord as l, StoredConnectionEvent as m, ConnectorConnectionEvent as n, ConnectorDiagnosticLog as o, ConnectorRawRecord as p, ConnectorConnectionQuery as r, ConnectorProcessedEvent as s, CONNECTOR_CONNECTION_STATUSES as t, ConnectorQuery as u, connectorProcessedEventSchema as v, FunnelConnectorListener as x, connectorRawEventSchema as y };

package/dist/connectors/discord.d.ts

@@ -1,6 +1,6 @@
-import { n as FunnelConnectorAdapter, t as CallInput } from "../connector-adapter-CXB-q_XC.js";
-import { n as discordConnectorSchema, t as DiscordConnectorConfig } from "../discord-connector-schema-Dww2I4zH.js";
-import { n as FunnelConnectorListener, r as NotifyFn, t as FunnelLogger } from "../logger-B3aXsVcX.js";
+import { n as FunnelConnectorAdapter, t as CallInput } from "../connector-adapter-VA6undzc.js";
+import { n as discordConnectorSchema, t as DiscordConnectorConfig } from "../discord-connector-schema-Df_McRJI.js";
+import { S as NotifyFn, b as FunnelLogger, o as ConnectorDiagnosticLog, x as FunnelConnectorListener } from "../connector-diagnostic-log-OPpPi9V9.js";
 
 //#region lib/engine/http/http-client.d.ts
 type HttpRequest = {
@@ -21,7 +21,8 @@ declare abstract class FunnelHttpClient {
 //#endregion
 //#region lib/connectors/discord-adapter.d.ts
 type Deps$1 = {
-  config: DiscordConnectorConfig;
+  config: DiscordConnectorConfig; /** Environment used to resolve a `botTokenEnv` reference. Defaults to process.env. */
+  env?: NodeJS.ProcessEnv;
   http?: FunnelHttpClient;
 };
 declare class FunnelDiscordAdapter extends FunnelConnectorAdapter {
@@ -60,17 +61,26 @@ declare class FunnelDiscordEventProcessor {
 //#endregion
 //#region lib/connectors/discord-listener.d.ts
 type Deps = {
-  config: DiscordConnectorConfig;
-  logger?: FunnelLogger;
+  config: DiscordConnectorConfig; /** Funnel channel uuid this connector lives under; stamped onto diagnostic-log rows. */
+  channelId?: string; /** Environment used to resolve a `botTokenEnv` reference. Defaults to process.env. */
+  env?: NodeJS.ProcessEnv;
+  logger?: FunnelLogger; /** Diagnostic log of inbound events, before and after processing. No-op when absent. */
+  diagnosticLog?: ConnectorDiagnosticLog;
 };
 declare class FunnelDiscordListener extends FunnelConnectorListener {
   private readonly config;
+  private readonly channelId;
+  private readonly env;
   private readonly logger;
+  private readonly diagnosticLog;
   private client;
   constructor(deps: Deps);
   start(notify: NotifyFn): Promise<void>;
   stop(): Promise<void>;
   isAlive(): boolean;
+  private recordRaw;
+  private recordProcessed;
+  private recordConnection;
 }
 //#endregion
 export { DiscordConnectorConfig, DiscordInboundMessage, DiscordProcessed, DiscordProcessedEmit, DiscordProcessedSkip, FunnelDiscordAdapter, FunnelDiscordEventProcessor, FunnelDiscordListener, discordConnectorSchema };

package/dist/connectors/discord.js

@@ -1,2 +1,2 @@
-import { i as FunnelDiscordAdapter, n as FunnelDiscordListener, r as FunnelDiscordEventProcessor, t as discordConnectorSchema } from "../discord-connector-schema-CpuI6rmE.js";
+import { i as FunnelDiscordAdapter, n as FunnelDiscordListener, r as FunnelDiscordEventProcessor, t as discordConnectorSchema } from "../discord-connector-schema-RzDvrNE5.js";
 export { FunnelDiscordAdapter, FunnelDiscordEventProcessor, FunnelDiscordListener, discordConnectorSchema };

package/dist/connectors/gh.d.ts

@@ -1,6 +1,6 @@
-import { n as FunnelConnectorAdapter, t as CallInput } from "../connector-adapter-CXB-q_XC.js";
-import { n as FunnelConnectorListener, r as NotifyFn, t as FunnelLogger } from "../logger-B3aXsVcX.js";
-import { a as FunnelProcessRunner, n as ghConnectorSchema, t as GhConnectorConfig } from "../gh-connector-schema-Cmi57jvL.js";
+import { n as FunnelConnectorAdapter, t as CallInput } from "../connector-adapter-VA6undzc.js";
+import { S as NotifyFn, b as FunnelLogger, o as ConnectorDiagnosticLog, x as FunnelConnectorListener } from "../connector-diagnostic-log-OPpPi9V9.js";
+import { a as FunnelProcessRunner, n as ghConnectorSchema, t as GhConnectorConfig } from "../gh-connector-schema-CQmEWzdV.js";
 
 //#region lib/connectors/gh-adapter.d.ts
 type Deps$1 = {
@@ -14,15 +14,19 @@ declare class FunnelGhAdapter extends FunnelConnectorAdapter {
 //#endregion
 //#region lib/connectors/gh-listener.d.ts
 type Deps = {
-  config: GhConnectorConfig;
+  config: GhConnectorConfig; /** Funnel channel uuid this connector lives under; stamped onto diagnostic-log rows. */
+  channelId?: string;
   process?: FunnelProcessRunner;
-  logger?: FunnelLogger;
+  logger?: FunnelLogger; /** Diagnostic log of inbound events, before and after processing. No-op when absent. */
+  diagnosticLog?: ConnectorDiagnosticLog;
   now?: () => Date;
 };
 declare class FunnelGhListener extends FunnelConnectorListener {
   private readonly config;
+  private readonly channelId;
   private readonly process;
   private readonly logger;
+  private readonly diagnosticLog;
   private readonly now;
   private readonly seen;
   private bootstrapped;
@@ -33,6 +37,9 @@ declare class FunnelGhListener extends FunnelConnectorListener {
   stop(): Promise<void>;
   isAlive(): boolean;
   pollOnce(notify: NotifyFn): Promise<void>;
+  private recordRaw;
+  private recordProcessed;
+  private recordConnection;
 }
 //#endregion
 export { FunnelGhAdapter, FunnelGhListener, GhConnectorConfig, ghConnectorSchema };

package/dist/connectors/gh.js

@@ -1,2 +1,2 @@
-import { n as FunnelGhListener, r as FunnelGhAdapter, t as ghConnectorSchema } from "../gh-connector-schema-CQRIvPpz.js";
+import { n as FunnelGhListener, r as FunnelGhAdapter, t as ghConnectorSchema } from "../gh-connector-schema-eYE4g77K.js";
 export { FunnelGhAdapter, FunnelGhListener, ghConnectorSchema };

package/dist/connectors/schedule.d.ts

@@ -1,4 +1,4 @@
-import { c as ScheduleEntry, d as scheduleEntrySchema, l as scheduleCatchupPolicySchema, n as ScheduleOnFired, o as ScheduleCatchupPolicy, r as ScheduleStateStore, s as ScheduleConnectorConfig, t as FunnelScheduleListener, u as scheduleConnectorSchema } from "../schedule-listener-CBYF2bGZ.js";
+import { c as ScheduleEntry, d as scheduleEntrySchema, l as scheduleCatchupPolicySchema, n as ScheduleOnFired, o as ScheduleCatchupPolicy, r as ScheduleStateStore, s as ScheduleConnectorConfig, t as FunnelScheduleListener, u as scheduleConnectorSchema } from "../schedule-listener-3M6WkH1Y.js";
 
 //#region lib/connectors/match-cron.d.ts
 declare const matchCron: (expr: string, date: Date) => boolean;

package/dist/connectors/schedule.js

@@ -1,2 +1,2 @@
-import { a as ScheduleStateStore, c as matchCron, i as FunnelScheduleListener, n as scheduleConnectorSchema, r as scheduleEntrySchema, t as scheduleCatchupPolicySchema } from "../schedule-connector-schema-CuCjP7z4.js";
+import { a as ScheduleStateStore, c as matchCron, i as FunnelScheduleListener, n as scheduleConnectorSchema, r as scheduleEntrySchema, t as scheduleCatchupPolicySchema } from "../schedule-connector-schema-CM-sRkac.js";
 export { FunnelScheduleListener, ScheduleStateStore, matchCron, scheduleCatchupPolicySchema, scheduleConnectorSchema, scheduleEntrySchema };

package/dist/connectors/slack.d.ts

@@ -1,12 +1,13 @@
-import { n as FunnelConnectorAdapter, t as CallInput } from "../connector-adapter-CXB-q_XC.js";
-import { a as SlackProcessed, c as SlackRawEvent, i as FunnelSlackEventProcessor, l as SlackConnectorConfig, n as SlackOnAppCreated, o as SlackProcessedEmit, r as SlackPreprocessEvent, s as SlackProcessedSkip, t as FunnelSlackListener, u as slackConnectorSchema } from "../slack-listener-DbNCPMqY.js";
+import { n as FunnelConnectorAdapter, t as CallInput } from "../connector-adapter-VA6undzc.js";
+import { a as SlackProcessed, c as SlackRawEvent, d as slackConnectorSchema, i as FunnelSlackEventProcessor, l as SlackSkipReason, n as SlackOnAppCreated, o as SlackProcessedEmit, r as SlackPreprocessEvent, s as SlackProcessedSkip, t as FunnelSlackListener, u as SlackConnectorConfig } from "../slack-listener-CLTiOEJw.js";
 
 //#region lib/connectors/slack-adapter.d.ts
 type SlackWebClientLike = {
   apiCall: (method: string, options?: Record<string, unknown>) => Promise<unknown>;
 };
 type Deps = {
-  config: SlackConnectorConfig;
+  config: SlackConnectorConfig; /** Environment used to resolve a `botTokenEnv` reference. Defaults to process.env. */
+  env?: NodeJS.ProcessEnv;
   client?: SlackWebClientLike;
 };
 declare class FunnelSlackAdapter extends FunnelConnectorAdapter {
@@ -15,4 +16,4 @@ declare class FunnelSlackAdapter extends FunnelConnectorAdapter {
   call(input: CallInput): Promise<unknown>;
 }
 //#endregion
-export { FunnelSlackAdapter, FunnelSlackEventProcessor, FunnelSlackListener, SlackConnectorConfig, SlackOnAppCreated, SlackPreprocessEvent, SlackProcessed, SlackProcessedEmit, SlackProcessedSkip, SlackRawEvent, SlackWebClientLike, slackConnectorSchema };
+export { FunnelSlackAdapter, FunnelSlackEventProcessor, FunnelSlackListener, SlackConnectorConfig, SlackOnAppCreated, SlackPreprocessEvent, SlackProcessed, SlackProcessedEmit, SlackProcessedSkip, SlackRawEvent, SlackSkipReason, SlackWebClientLike, slackConnectorSchema };

package/dist/connectors/slack.js

@@ -1,2 +1,2 @@
-import { i as FunnelSlackAdapter, n as FunnelSlackListener, r as FunnelSlackEventProcessor, t as slackConnectorSchema } from "../slack-connector-schema-BWL7dWlY.js";
+import { i as FunnelSlackAdapter, n as FunnelSlackListener, r as FunnelSlackEventProcessor, t as slackConnectorSchema } from "../slack-connector-schema-CHbRJHGp.js";
 export { FunnelSlackAdapter, FunnelSlackEventProcessor, FunnelSlackListener, slackConnectorSchema };

package/dist/{discord-connector-schema-Dww2I4zH.d.ts → discord-connector-schema-Df_McRJI.d.ts}

@@ -1,11 +1,17 @@
 import { z } from "zod";
 
 //#region lib/connectors/discord-connector-schema.d.ts
+/**
+ * Like slack, a discord connector holds either a literal `botToken` or a
+ * `botTokenEnv` reference resolved from the environment at listener start. The
+ * reference form keeps the secret in `.env.local` and out of settings.json.
+ */
 declare const discordConnectorSchema: z.ZodObject<{
   id: z.ZodString;
   name: z.ZodString;
   type: z.ZodLiteral<"discord">;
-  botToken: z.ZodString;
+  botToken: z.ZodOptional<z.ZodString>;
+  botTokenEnv: z.ZodOptional<z.ZodString>;
   createdAt: z.ZodOptional<z.ZodString>;
   updatedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;

package/dist/{discord-connector-schema-CpuI6rmE.js → discord-connector-schema-RzDvrNE5.js}

@@ -1,5 +1,6 @@
 import { t as FunnelConnectorAdapter } from "./connector-adapter-D5Utumgz.js";
-import { n as FunnelConnectorListener } from "./logger-D1A3_JXV.js";
+import { t as resolveConnectorToken } from "./resolve-connector-token-Ch6XWMJM.js";
+import { n as FunnelConnectorListener } from "./logger-Czli2OKh.js";
 import { Client, GatewayIntentBits, Partials } from "discord.js";
 import { z } from "zod";
 //#region lib/engine/http/http-client.ts
@@ -34,7 +35,12 @@ var FunnelDiscordAdapter = class extends FunnelConnectorAdapter {
 	http;
 	constructor(deps) {
 		super();
-		this.token = deps.config.botToken;
+		this.token = resolveConnectorToken({
+			literal: deps.config.botToken,
+			envVar: deps.config.botTokenEnv,
+			env: deps.env ?? process.env,
+			label: `${deps.config.name}.botToken`
+		});
 		this.http = deps.http ?? defaultHttp;
 		Object.freeze(this);
 	}
@@ -84,14 +90,21 @@ var FunnelDiscordEventProcessor = class {
 //#region lib/connectors/discord-listener.ts
 var FunnelDiscordListener = class extends FunnelConnectorListener {
 	config;
+	channelId;
+	env;
 	logger;
+	diagnosticLog;
 	client = null;
 	constructor(deps) {
 		super();
 		this.config = deps.config;
+		this.channelId = deps.channelId ?? null;
+		this.env = deps.env ?? process.env;
 		this.logger = deps.logger;
+		this.diagnosticLog = deps.diagnosticLog;
 	}
 	async start(notify) {
+		this.recordConnection("started", "");
 		const client = new Client({
 			intents: [
 				GatewayIntentBits.Guilds,
@@ -113,23 +126,30 @@ var FunnelDiscordListener = class extends FunnelConnectorListener {
 				ownUserId,
 				mentioned: String(mentionedUserIds.includes(ownUserId))
 			});
+			const rawEvent = message.toJSON();
+			const eventId = crypto.randomUUID();
+			this.recordRaw(eventId, rawEvent);
 			const result = new FunnelDiscordEventProcessor({ ownUserId }).process({
 				authorId: message.author.id,
 				authorIsBot: message.author.bot,
 				channelId: message.channelId,
 				guildId: message.guildId,
 				mentionedUserIds,
-				raw: message.toJSON()
+				raw: rawEvent
 			});
 			if (result.skip) {
+				this.recordProcessed(eventId, rawEvent, "skip:bot", "");
 				this.logger?.info("discord skip", { reason: "bot author" });
 				return;
 			}
 			try {
 				await notify(result.content, result.meta);
 			} catch (error) {
-				this.logger?.error("discord notify error", { error: error instanceof Error ? error.message : String(error) });
+				this.recordProcessed(eventId, rawEvent, "emitted:delivery-failed", result.content);
+				this.logger?.error("discord notify error", { error: messageOf(error) });
+				return;
 			}
+			this.recordProcessed(eventId, rawEvent, "emitted", result.content);
 		});
 		client.on("ready", (readyClient) => {
 			this.logger?.info("discord ready", {
@@ -139,32 +159,85 @@ var FunnelDiscordListener = class extends FunnelConnectorListener {
 			});
 		});
 		client.on("error", (error) => {
-			this.logger?.error("discord client error", { error: error instanceof Error ? error.message : String(error) });
+			this.recordConnection("error", messageOf(error));
+			this.logger?.error("discord client error", { error: messageOf(error) });
 		});
-		await client.login(this.config.botToken);
+		try {
+			await client.login(resolveConnectorToken({
+				literal: this.config.botToken,
+				envVar: this.config.botTokenEnv,
+				env: this.env,
+				label: `${this.config.name}.botToken`
+			}));
+		} catch (error) {
+			this.recordConnection("error", messageOf(error));
+			throw error;
+		}
 		this.client = client;
+		this.recordConnection("connected", "");
 	}
 	async stop() {
 		if (!this.client) return;
 		try {
 			await this.client.destroy();
+			this.recordConnection("disconnected", "");
 		} catch (error) {
-			this.logger?.error("discord stop error", { error: error instanceof Error ? error.message : String(error) });
+			this.recordConnection("error", messageOf(error));
+			this.logger?.error("discord stop error", { error: messageOf(error) });
 		} finally {
 			this.client = null;
+			this.recordConnection("stopped", "");
 		}
 	}
 	isAlive() {
 		return this.client !== null;
 	}
+	recordRaw(eventId, rawEvent) {
+		this.diagnosticLog?.recordRaw({
+			eventId,
+			type: "discord",
+			connectorId: this.config.id,
+			channelId: this.channelId,
+			payload: JSON.stringify(rawEvent)
+		});
+	}
+	recordProcessed(eventId, rawEvent, outcome, content) {
+		this.diagnosticLog?.recordProcessed({
+			eventId,
+			type: "discord",
+			connectorId: this.config.id,
+			channelId: this.channelId,
+			outcome,
+			payload: content || JSON.stringify(rawEvent)
+		});
+	}
+	recordConnection(status, detail) {
+		this.diagnosticLog?.recordConnection({
+			type: "discord",
+			connectorId: this.config.id,
+			channelId: this.channelId,
+			status,
+			detail
+		});
+	}
+};
+const messageOf = (error) => {
+	return error instanceof Error ? error.message : String(error);
 };
 //#endregion
 //#region lib/connectors/discord-connector-schema.ts
+/**
+* Like slack, a discord connector holds either a literal `botToken` or a
+* `botTokenEnv` reference resolved from the environment at listener start. The
+* reference form keeps the secret in `.env.local` and out of settings.json.
+*/
 const discordConnectorSchema = z.object({
 	id: z.string(),
 	name: z.string(),
 	type: z.literal("discord"),
-	botToken: z.string().min(10),
+	botToken: z.string().min(10).optional(),
+	/** Name of the env var holding the bot token, resolved at listener start. */
+	botTokenEnv: z.string().optional(),
 	createdAt: z.string().datetime().optional(),
 	updatedAt: z.string().datetime().optional()
 });