@moda-labs/bobi-events-core 0.1.0

package/dist/circuit-breaker.js

@@ -0,0 +1,288 @@
+/**
+ * Delivery-path circuit breaker (#299, split from #215 loop-safety).
+ *
+ * Keying decision: the breaker keys on `(deployment_id, conversation)` where
+ * conversation is derived from external channel identity:
+ *   - Slack: thread_ts (or ts if no thread)
+ *   - GitHub: repo + issue/PR number
+ *   - Other: event type (coarse — acceptable because custom events rarely loop)
+ *
+ * EXEMPTIONS: `inbox/*` and `reply/*` topics are legitimate internal
+ * agent↔agent comms and are NEVER counted toward the breaker. They flow
+ * through a separate routing namespace (`agent/*` topics) that does not
+ * represent external conversation depth.
+ *
+ * Trip condition: ≥ THRESHOLD non-human-authored deliveries in one key within
+ * WINDOW_MS with zero human events → pause delivery for that key (buffered,
+ * not dropped). Emit `system.loop_detected`. Auto-resume after COOLDOWN_MS or
+ * on the next human-authored event in the same key.
+ */
+// ---------------------------------------------------------------------------
+// Tunables
+// ---------------------------------------------------------------------------
+export const BREAKER_THRESHOLD = 5;
+export const BREAKER_WINDOW_MS = 60_000; // 60s
+export const BREAKER_COOLDOWN_MS = 300_000; // 5min
+const AGENT_LIFECYCLE_EVENTS = new Set([
+    "agent/session.completed",
+    "agent/session.failed",
+    "session.completed",
+    "session.failed",
+]);
+// ---------------------------------------------------------------------------
+// Conversation key extraction
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if this event's type is exempt from breaker counting.
+ * inbox/* and reply/* are internal agent↔agent comms, not external
+ * conversation depth.
+ */
+export function isExemptFromBreaker(event) {
+    const t = event.type;
+    if (t.startsWith("inbox/") || t.startsWith("reply/"))
+        return true;
+    if (event.source === "agent" && AGENT_LIFECYCLE_EVENTS.has(t))
+        return true;
+    // Also check topics — events published on inbox/* or reply/* topics
+    // (via createTopicEvent) carry those as their routing keys.
+    if (event.topics?.some((topic) => topic.startsWith("inbox/") || topic.startsWith("reply/"))) {
+        return true;
+    }
+    if (event.source === "agent" && event.topics?.some((topic) => AGENT_LIFECYCLE_EVENTS.has(topic))) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Extract the conversation key from an event. Returns null if no meaningful
+ * conversation can be identified (breaker won't apply).
+ */
+export function conversationKey(event) {
+    const payload = event.payload;
+    const fields = event.fields;
+    const payloadString = (key) => {
+        const value = payload?.[key];
+        return typeof value === "string" ? value.trim() : "";
+    };
+    if (event.source === "slack") {
+        // Slack: thread_ts identifies a conversation (thread). If no thread,
+        // use ts (the message itself becomes the "thread" root).
+        const threadTs = payload?.thread_ts || fields?.thread_ts || "";
+        const ts = payload?.ts || fields?.ts || "";
+        const channel = payload?.channel || fields?.channel || "";
+        const key = threadTs || ts;
+        if (key && channel)
+            return `slack:${channel}:${key}`;
+        if (key)
+            return `slack:${key}`;
+        return null;
+    }
+    if (event.source === "github") {
+        // GitHub: repo + issue/PR number identifies the conversation.
+        const repo = payload?.repository?.full_name;
+        const issue = payload?.issue;
+        const pr = payload?.pull_request;
+        const num = (issue?.number ?? pr?.number);
+        if (repo && num !== undefined)
+            return `github:${repo}#${num}`;
+        // Fall back to repo-level for events without an issue/PR (e.g. push)
+        if (repo)
+            return `github:${repo}`;
+        return null;
+    }
+    if (event.source === "monitor") {
+        // Monitor findings are often batched by one scheduled run but emitted as
+        // separate actionable findings. Key by the monitor plus the scheduler's
+        // stable finding identity so one audit pass with several distinct
+        // findings does not look like a self-reinforcing event loop.
+        const monitor = payloadString("monitor");
+        const findingKey = payloadString("finding_key") || payloadString("key");
+        if (monitor && findingKey) {
+            return `monitor:${encodeURIComponent(monitor)}:${encodeURIComponent(findingKey)}`;
+        }
+        if (monitor)
+            return `monitor:${encodeURIComponent(monitor)}`;
+        return `monitor:${encodeURIComponent(event.type)}`;
+    }
+    // Fallback for custom/linear events: use the event type as a coarse key.
+    // This means N different events of the same type within one deployment
+    // share a single bucket — acceptable because custom loops are rare and
+    // the breaker trips only on sustained depth.
+    return `other:${event.type}`;
+}
+/**
+ * Determine whether an event is authored by a bot (non-human).
+ * Human-authored events reset the breaker window.
+ */
+export function isBotAuthored(event) {
+    const payload = event.payload;
+    if (event.source === "slack") {
+        // Slack: bot_id present on the inner event means a bot posted it.
+        const innerEvent = payload?.event;
+        const botId = innerEvent?.bot_id || payload?.bot_id || "";
+        return !!botId;
+    }
+    if (event.source === "github") {
+        // GitHub: sender.type === "Bot" or well-known agent logins.
+        const sender = payload?.sender;
+        if (sender?.type === "Bot")
+            return true;
+        const login = sender?.login || "";
+        // Common bot suffixes: [bot], -bot, _bot
+        if (login.endsWith("[bot]") || login.endsWith("-bot") || login.endsWith("_bot"))
+            return true;
+        return false;
+    }
+    // For custom/linear sources: conservatively treat as bot-authored if the
+    // source field suggests automation. This avoids false negatives on agent-
+    // published events while still allowing human-triggered custom events to
+    // reset the breaker.
+    const source = event.source || "";
+    if (source === "agent" || source === "monitor" || source === "system")
+        return true;
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Breaker engine (in-memory, per-process)
+// ---------------------------------------------------------------------------
+/** Map of `deploymentId:conversationKey` → BreakerState */
+const states = new Map();
+function getState(compositeKey) {
+    let s = states.get(compositeKey);
+    if (!s) {
+        s = { timestamps: [], tripped: false, paused: [] };
+        states.set(compositeKey, s);
+    }
+    return s;
+}
+/**
+ * Prune timestamps outside the current window.
+ */
+function pruneWindow(state, now) {
+    const cutoff = now - BREAKER_WINDOW_MS;
+    state.timestamps = state.timestamps.filter((t) => t > cutoff);
+}
+/**
+ * Check whether a tripped breaker has cooled down and should auto-resume.
+ */
+function checkCooldown(state, now) {
+    if (!state.tripped || !state.trippedAt)
+        return false;
+    return now - state.trippedAt >= BREAKER_COOLDOWN_MS;
+}
+/**
+ * Record a delivery attempt and return a verdict.
+ *
+ * Call this BEFORE actually delivering the event. If `allow` is false,
+ * the caller must buffer the event (it is already added to state.paused).
+ */
+export function recordDelivery(deploymentId, event) {
+    const convKey = conversationKey(event);
+    if (!convKey)
+        return { allow: true, justTripped: false };
+    const compositeKey = `${deploymentId}:${convKey}`;
+    const state = getState(compositeKey);
+    const now = Date.now();
+    // Auto-resume on cooldown expiry
+    if (state.tripped && checkCooldown(state, now)) {
+        resumeState(state);
+    }
+    // Human event resets the breaker
+    if (!isBotAuthored(event)) {
+        resumeState(state);
+        return { allow: true, justTripped: false };
+    }
+    // If already tripped, buffer the event
+    if (state.tripped) {
+        state.paused.push(event);
+        return { allow: false, justTripped: false };
+    }
+    // Record this bot delivery
+    pruneWindow(state, now);
+    state.timestamps.push(now);
+    // Check threshold
+    if (state.timestamps.length >= BREAKER_THRESHOLD) {
+        state.tripped = true;
+        state.trippedAt = now;
+        state.paused.push(event);
+        return { allow: false, justTripped: true };
+    }
+    return { allow: true, justTripped: false };
+}
+/**
+ * Resume a tripped breaker — returns any paused events that should now
+ * be delivered.
+ */
+function resumeState(state) {
+    state.tripped = false;
+    state.trippedAt = undefined;
+    state.timestamps = [];
+    // Note: paused events are drained by the caller via drainPaused()
+}
+/**
+ * Drain paused events for a deployment+conversation. Returns the events
+ * that were buffered and clears the pause buffer. The caller is responsible
+ * for delivering them.
+ */
+export function drainPaused(deploymentId, event) {
+    const convKey = conversationKey(event);
+    if (!convKey)
+        return [];
+    const compositeKey = `${deploymentId}:${convKey}`;
+    const state = states.get(compositeKey);
+    if (!state || state.paused.length === 0)
+        return [];
+    const drained = state.paused.splice(0);
+    return drained;
+}
+/**
+ * Check whether a breaker is currently tripped for a deployment+conversation.
+ * Used after cooldown to decide whether to flush paused events.
+ */
+export function isBreakerTripped(deploymentId, convKey) {
+    const compositeKey = `${deploymentId}:${convKey}`;
+    const state = states.get(compositeKey);
+    if (!state)
+        return false;
+    if (state.tripped && state.trippedAt && checkCooldown(state, Date.now())) {
+        resumeState(state);
+        return false;
+    }
+    return state.tripped;
+}
+/**
+ * Build the system.loop_detected event to be published.
+ */
+export function buildLoopDetectedEvent(deploymentId, convKey, triggerEvent) {
+    return {
+        v: 2,
+        id: crypto.randomUUID(),
+        source: "system",
+        type: "system.loop_detected",
+        topics: ["system.loop_detected"],
+        delivery: "bulk",
+        text: `Circuit breaker tripped: deployment=${deploymentId} conversation=${convKey} trigger=${triggerEvent.type}`,
+        fields: {
+            deployment_id: deploymentId,
+            conversation_key: convKey,
+            trigger_event_type: triggerEvent.type,
+            trigger_event_id: triggerEvent.id,
+            threshold: BREAKER_THRESHOLD,
+            window_ms: BREAKER_WINDOW_MS,
+            cooldown_ms: BREAKER_COOLDOWN_MS,
+        },
+        timestamp: new Date().toISOString(),
+        payload: {
+            deployment_id: deploymentId,
+            conversation_key: convKey,
+            trigger_event: triggerEvent,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Reset (for testing)
+// ---------------------------------------------------------------------------
+export function resetAllBreakers() {
+    states.clear();
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"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"}

package/dist/conversation.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Conversation references - channel-agnostic addressing for chat replies (#618).
+ *
+ * A conversation reference is an opaque string the agent echoes back verbatim
+ * to reply into the thread/DM an inbound event came from. Only adapters build
+ * refs and only the gateway parses them; the agent never learns platform
+ * addressing semantics.
+ *
+ * Grammar:
+ *   <source>:<scope>:<chat_type>:<chat_id>[:thread:<thread_id>]
+ *
+ * where <scope> is the platform's tenancy unit (Slack team id, WhatsApp phone
+ * number id). Segment values must not contain ":" - buildConversation enforces
+ * this, so a platform whose ids carry ":" (Matrix, Teams) needs a grammar
+ * extension (escaping or a new trailer), not a silent mis-parse.
+ */
+export type ChatType = "dm" | "group" | "channel";
+export interface Conversation {
+    source: string;
+    scope: string;
+    chatType: ChatType;
+    chatId: string;
+    threadId?: string;
+}
+export declare function buildConversation(c: Conversation): string;
+export declare function parseConversation(ref: string): Conversation | null;
+export declare function slackChatType(channelType: string): ChatType;
+export declare function slackConversation(teamId: string, channel: string, channelType: string, ts: string, threadTs?: string): string | undefined;
+//# sourceMappingURL=conversation.d.ts.map

package/dist/conversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;AAElD,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAUzD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAkBlE;AAID,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAI3D;AAMD,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,QAAQ,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAgBpB"}

package/dist/conversation.js

@@ -0,0 +1,86 @@
+/**
+ * Conversation references - channel-agnostic addressing for chat replies (#618).
+ *
+ * A conversation reference is an opaque string the agent echoes back verbatim
+ * to reply into the thread/DM an inbound event came from. Only adapters build
+ * refs and only the gateway parses them; the agent never learns platform
+ * addressing semantics.
+ *
+ * Grammar:
+ *   <source>:<scope>:<chat_type>:<chat_id>[:thread:<thread_id>]
+ *
+ * where <scope> is the platform's tenancy unit (Slack team id, WhatsApp phone
+ * number id). Segment values must not contain ":" - buildConversation enforces
+ * this, so a platform whose ids carry ":" (Matrix, Teams) needs a grammar
+ * extension (escaping or a new trailer), not a silent mis-parse.
+ */
+const CHAT_TYPES = new Set(["dm", "group", "channel"]);
+export function buildConversation(c) {
+    const segments = [c.source, c.scope, c.chatType, c.chatId];
+    if (c.threadId !== undefined)
+        segments.push(c.threadId);
+    for (const s of segments) {
+        if (!s || s.includes(":")) {
+            throw new Error(`invalid conversation segment: ${JSON.stringify(s)}`);
+        }
+    }
+    const base = `${c.source}:${c.scope}:${c.chatType}:${c.chatId}`;
+    return c.threadId ? `${base}:thread:${c.threadId}` : base;
+}
+export function parseConversation(ref) {
+    if (typeof ref !== "string")
+        return null;
+    const parts = ref.split(":");
+    if (parts.length !== 4 && parts.length !== 6)
+        return null;
+    if (parts.some((p) => p === ""))
+        return null;
+    const [source, scope, chatType, chatId] = parts;
+    if (!CHAT_TYPES.has(chatType))
+        return null;
+    const conv = {
+        source,
+        scope,
+        chatType: chatType,
+        chatId,
+    };
+    if (parts.length === 6) {
+        if (parts[4] !== "thread")
+            return null;
+        conv.threadId = parts[5];
+    }
+    return conv;
+}
+// Slack channel_type -> chat_type. "im" is a 1:1 DM, "mpim" a group DM;
+// public ("channel") and private ("group") channels both address as channel.
+export function slackChatType(channelType) {
+    if (channelType === "im")
+        return "dm";
+    if (channelType === "mpim")
+        return "group";
+    return "channel";
+}
+// Build the reply address for an inbound Slack message, or undefined when the
+// payload lacks usable ids. Owns the reply-anchoring policy: replies land in
+// the originating thread, and a top-level message anchors its own thread (ts),
+// matching where the placeholder handler posts.
+export function slackConversation(teamId, channel, channelType, ts, threadTs) {
+    if (!teamId || !channel)
+        return undefined;
+    const anchor = threadTs || ts;
+    try {
+        return buildConversation({
+            source: "slack",
+            scope: teamId,
+            chatType: slackChatType(channelType),
+            chatId: channel,
+            ...(anchor ? { threadId: anchor } : {}),
+        });
+    }
+    catch {
+        // A colon-bearing id in the webhook payload must not kill normalization;
+        // the event just ships without a reply address.
+        return undefined;
+    }
+}
+//# sourceMappingURL=conversation.js.map

package/dist/conversation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"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"}