@mininglamp-oss/cc-channel-octo 1.0.1

package/dist/session-router.js

@@ -0,0 +1,432 @@
+/**
+ * Session Router — routing + concurrency control + mention gate + rate limiting.
+ */
+import { ChannelType, MessageType } from './octo/types.js';
+import { sendMessage } from './octo/api.js';
+import { isAuthenticCronFire } from './cron-fire-marker.js';
+const BUCKET_STALE_MS = 5 * 60 * 1000; // 5 minutes
+/** Global rate limit: 10x per-session limit, shared across all sessions. */
+const GLOBAL_RATE_MULTIPLIER = 10;
+/** Maximum allowed content length in bytes (Q10). Messages exceeding this are rejected. */
+const MAX_CONTENT_BYTES = 32_768; // 32 KB
+export class SessionRouter {
+    config;
+    robotId;
+    /** G18: owner_uid from registerBot. Stored for future permission model. */
+    ownerUid;
+    inboundQueues = new Map();
+    tokenBuckets = new Map();
+    /** G20: per-user buckets keyed by from_uid alone (cross-channel rate limit). */
+    userBuckets = new Map();
+    globalBucket = null;
+    /**
+     * G14: UIDs known to be bots. Initialized with this bot's robotId; can be
+     * extended via registerKnownBot() for future multi-bot deployments.
+     */
+    knownBotUids = new Set();
+    constructor(config, robotId, ownerUid = '') {
+        this.config = config;
+        this.robotId = robotId;
+        this.ownerUid = ownerUid;
+        this.knownBotUids.add(robotId);
+    }
+    /** G14: register another known bot uid (future multi-bot support). */
+    registerKnownBot(uid) {
+        if (uid)
+            this.knownBotUids.add(uid);
+    }
+    /** G18: owner_uid stored from registerBot. Used by future permission model. */
+    getOwnerUid() {
+        return this.ownerUid;
+    }
+    /**
+     * Acquire a per-session lock for the full message handling pipeline.
+     * Callers (e.g. index.ts) use this to ensure the entire handleMessage
+     * chain — not just routing — runs serially per session key.
+     */
+    async withSessionLock(key, fn) {
+        const prev = this.inboundQueues.get(key) ?? Promise.resolve();
+        let resolveGate;
+        const gate = new Promise((r) => {
+            resolveGate = r;
+        });
+        this.inboundQueues.set(key, gate);
+        try {
+            await prev;
+            return await fn();
+        }
+        finally {
+            resolveGate();
+            if (this.inboundQueues.get(key) === gate) {
+                this.inboundQueues.delete(key);
+            }
+        }
+    }
+    /**
+     * Route a message and, if it should be processed, run the handler callback
+     * under the same per-session lock. This ensures no gap between route decision
+     * and pipeline execution — concurrent same-session messages cannot interleave.
+     */
+    /**
+     * Route a message and, if it should be processed, run the handler callback
+     * under the same per-session lock. This ensures no gap between route decision
+     * and pipeline execution — concurrent same-session messages cannot interleave.
+     *
+     * Returns the RouteResult (or `null` for silent-drop cases) so the caller
+     * can inspect `rejectionReason` to decide whether the message should still
+     * influence downstream side-effects like group context caching
+     * (C1 / P2.5 — stage 6).
+     */
+    async routeAndHandle(msg, handler) {
+        const key = this.sessionKey(msg);
+        return this.withSessionLock(key, async () => {
+            const result = await this.processMessage(msg, key);
+            if (result && result.shouldProcess) {
+                await handler(result);
+            }
+            return result;
+        });
+    }
+    async route(msg) {
+        const key = this.sessionKey(msg);
+        return this.withSessionLock(key, () => this.processMessage(msg, key));
+    }
+    sessionKey(msg) {
+        const spaceId = this.extractSpaceId(msg);
+        if (msg.channel_type === ChannelType.DM) {
+            // DM is per-user (private): same peer always resumes the same session.
+            // from_uid IS the peer's identity here; a missing one is unroutable —
+            // never fall back to '' (that would collapse every uid-less DM into ONE
+            // shared session across unrelated peers, leaking history/memory). Mirrors
+            // the group channel_id guard below. Caught upstream → message dropped.
+            if (!msg.from_uid) {
+                throw new Error('DM message has no from_uid — cannot derive a session key');
+            }
+            return spaceId ? `${spaceId}:${msg.from_uid}` : msg.from_uid;
+        }
+        // Group is per-CHANNEL (shared): every member of a group shares one session,
+        // history, working dir, and memory — a group is a collective workspace, not
+        // N private chats. (Reverses the per-(channel×user) split from PR #64; see
+        // src/cwd-resolver.ts header. Space isolation is implicit: one bot = one
+        // space = one process with its own dataDir/cwdBase/memoryBase.)
+        //
+        // channel_id IS the group's identity here, so a missing one is unroutable —
+        // never fall back to '' (that would collapse every channel-less group message
+        // into ONE shared session across unrelated channels, leaking history/memory
+        // between them). Fail loud instead; route() treats the throw as a drop.
+        if (!msg.channel_id) {
+            throw new Error('Group message has no channel_id — cannot derive a session key');
+        }
+        return msg.channel_id;
+    }
+    /**
+     * Extract spaceId from channel_id.
+     * DM format: s{spaceId}_{uid1}@s{spaceId}_{uid2}
+     * Group format: s{spaceId}_{groupNo} (but groups already use channel_id in key)
+     */
+    extractSpaceId(msg) {
+        // For groups, channel_id already provides isolation
+        if (this.isGroupLike(msg.channel_type))
+            return "";
+        // DM: try from_uid first (format: s{spaceId}_{peerId})
+        const uid = msg.from_uid;
+        if (uid.startsWith("s")) {
+            const lastUnderscore = uid.lastIndexOf("_");
+            if (lastUnderscore > 0) {
+                return uid.substring(1, lastUnderscore);
+            }
+        }
+        // DM compound: s{spaceId}_{uid1}@s{spaceId}_{uid2}
+        const channelId = msg.channel_id;
+        if (channelId && channelId.startsWith("s")) {
+            const atIdx = channelId.indexOf("@");
+            const firstPart = atIdx > 0 ? channelId.substring(0, atIdx) : channelId;
+            if (firstPart.startsWith("s")) {
+                const lastUnderscore = firstPart.lastIndexOf("_");
+                if (lastUnderscore > 0) {
+                    return firstPart.substring(1, lastUnderscore);
+                }
+            }
+        }
+        return "";
+    }
+    isBlockedBot(uid) {
+        return this.config.botBlocklist?.includes(uid) ?? false;
+    }
+    /**
+     * G14: Heuristic bot detection. Octo bot uids conventionally end in `_bot`.
+     * This is NOT a perfect check — a human could pick that suffix — but it
+     * catches the common case where a bot DMs another bot and triggers an
+     * uncontrolled response loop. Bots whitelisted in `allowedBotUids` bypass
+     * this gate.
+     */
+    looksLikeBot(uid) {
+        if (this.knownBotUids.has(uid))
+            return true;
+        if (uid.endsWith('_bot'))
+            return true;
+        return false;
+    }
+    isAllowedBot(uid) {
+        return this.config.allowedBotUids?.includes(uid) ?? false;
+    }
+    isGroupLike(channelType) {
+        return channelType === ChannelType.Group || channelType === ChannelType.CommunityTopic;
+    }
+    /**
+     * Allowlist of channel types we actually converse on: DM, Group, and
+     * CommunityTopic. Octo also emits system/command channels (e.g. channel_type
+     * 8 "systemcmdonline" on connect) which are NOT user conversations — those
+     * must be dropped, otherwise they fall through the DM/group gates and get
+     * answered with an unsolicited LLM reply. Found in live deployment (#68).
+     */
+    isSupportedChannel(channelType) {
+        return channelType === ChannelType.DM || this.isGroupLike(channelType);
+    }
+    isMentioned(msg) {
+        const mention = msg.payload.mention;
+        if (!mention)
+            return false;
+        if (mention.uids?.includes(this.robotId))
+            return true;
+        // Note: mention.all is a humans-only signal (@所有人), bots do NOT respond.
+        if (mention.ais)
+            return true;
+        return false;
+    }
+    /**
+     * #115: True for a GENUINE in-process cron fire — `payload._cronFire` AND a
+     * matching per-process nonce. Such messages bypass the group @mention gate
+     * (owner-gated at creation, bound to this session). A forged inbound payload
+     * can set `_cronFire` but not the secret nonce, so it does not pass. Real
+     * inbound messages never carry the marker.
+     */
+    isCronFire(msg) {
+        return isAuthenticCronFire(msg.payload);
+    }
+    async processMessage(msg, key) {
+        // Skip messages from self.
+        if (msg.from_uid === this.robotId)
+            return null;
+        // Drop anything that isn't a real conversation channel (DM / group /
+        // community topic). Octo emits system/command channels (e.g. channel_type 8
+        // "systemcmdonline" on connect) that otherwise slip past the DM/group gates
+        // and get an unsolicited reply (#68).
+        if (!this.isSupportedChannel(msg.channel_type))
+            return null;
+        // Skip stream update messages (G21) — only process final (non-stream) messages.
+        // When streamOn is true, this is a partial update of an ongoing stream; the final
+        // message arrives with streamOn=false and contains the complete content.
+        if (msg.streamOn)
+            return null;
+        // DM blocklist filter.
+        if (msg.channel_type === ChannelType.DM && this.isBlockedBot(msg.from_uid)) {
+            return null;
+        }
+        // G14: DM from anything that looks like a bot — silently drop unless
+        // explicitly whitelisted. Prevents bot↔bot reply loops.
+        if (msg.channel_type === ChannelType.DM &&
+            this.looksLikeBot(msg.from_uid) &&
+            !this.isAllowedBot(msg.from_uid)) {
+            return null;
+        }
+        // Group: drop messages from other bots (blocklisted or self) entirely.
+        if (this.isGroupLike(msg.channel_type) && this.isBlockedBot(msg.from_uid)) {
+            return null;
+        }
+        // G14: Group messages from bot-looking uids — only respond if explicitly
+        // @-mentioned. The mention gate below already enforces this, but bots in
+        // the blocklist (above) get hard-dropped without even checking mentions.
+        // Group mention gate — skip unless mentioned OR in mention-free group (G12).
+        // #115: cron-fired synthetic messages bypass the @mention requirement — they
+        // were created (owner-gated) and bound to this session; there's no human to
+        // @-mention the bot at fire time. Rate limiting below still applies.
+        if (this.isGroupLike(msg.channel_type) && !this.isMentioned(msg) && !this.isCronFire(msg)) {
+            // G12: Check if this group is in the mention-free list
+            const isMentionFree = this.config.mentionFreeGroups?.includes(msg.channel_id ?? '') ?? false;
+            if (!isMentionFree) {
+                return null;
+            }
+            // Multi-bot loop guard: in a mention-free group there is no @-mention gate
+            // to stop one bot from replying to another bot's plain-text message. Drop
+            // messages from known/bot-looking uids (unless explicitly whitelisted) so
+            // two bots in the same mention-free room cannot enter an unbounded reply
+            // loop. An @-mention still goes through (handled by the branch above).
+            if (this.looksLikeBot(msg.from_uid) && !this.isAllowedBot(msg.from_uid)) {
+                return null;
+            }
+        }
+        // Skip system events (group join/leave, etc.) — no user-facing reply needed.
+        if (msg.payload.event)
+            return null;
+        // Rate limit check BEFORE non-text check — prevents DM spam of non-text
+        // messages from bypassing rate limiting entirely.
+        // G20 fix: peek all three buckets without consuming; only consume on full
+        // pass. On block, attach notified state to the actual blocking bucket so
+        // the debounce reply doesn't spam when a different bucket has tokens.
+        // #115: cron fires skip the rate limit — a scheduler-fired task is an
+        // operator-scheduled action (already bounded by the cron interval), not
+        // user spam. Without this a fire that lands while the owner's bucket is
+        // exhausted would be silently dropped while its nextRun has already advanced.
+        if (!this.isCronFire(msg)) {
+            const blocker = this.checkAllRateLimits(key, msg.from_uid);
+            if (blocker) {
+                if (!blocker.notified) {
+                    blocker.notified = true;
+                    await this.replySafe(msg, '请稍后再试');
+                }
+                return {
+                    sessionKey: key,
+                    shouldProcess: false,
+                    message: msg,
+                    rejectionReason: 'rate_limited',
+                };
+            }
+        }
+        // G1: All payload types are now resolved by inbound.resolveContent in
+        // handleMessage. The router only filters rate limits, size, and bot
+        // loops — type-specific handling lives in the pipeline.
+        // Q10: Reject messages exceeding content length limit (text only — media
+        // URLs are bounded by their own size and rendered via resolveContent).
+        const content = msg.payload.content ?? '';
+        if (msg.payload.type === MessageType.Text &&
+            Buffer.byteLength(content, 'utf-8') > MAX_CONTENT_BYTES) {
+            await this.replySafe(msg, '消息过长，请缩短后重试');
+            return {
+                sessionKey: key,
+                shouldProcess: false,
+                message: msg,
+                rejectionReason: 'oversized',
+            };
+        }
+        // G13: Strip leading @botname from group TEXT messages for cleaner LLM input.
+        // For non-text payloads (images, files, etc.) cleanContent stays undefined
+        // so the pipeline falls back to the resolveContent rendering instead of an
+        // empty string.
+        let cleanContent;
+        if (msg.payload.type === MessageType.Text) {
+            cleanContent = content;
+            if (this.isGroupLike(msg.channel_type)) {
+                const mention = msg.payload.mention;
+                // Path 1: entities-based removal (precise offset/length).
+                if (mention?.entities && Array.isArray(mention.entities)) {
+                    const botEntity = mention.entities.find((e) => e.uid === this.robotId && e.offset === 0);
+                    if (botEntity && typeof botEntity.length === 'number') {
+                        cleanContent = content.substring(botEntity.length).trimStart();
+                    }
+                }
+                // Path 2: regex fallback — only when the bot was explicitly @mentioned.
+                // In mention-free groups (G12) where the bot wasn't @'d, do NOT touch
+                // the message — a leading @ is addressed to someone else.
+                if (cleanContent === content && this.isMentioned(msg)) {
+                    cleanContent = content.replace(/^@\S+\s*/, '').trimStart();
+                }
+                // If stripping emptied the content, keep original.
+                if (!cleanContent)
+                    cleanContent = content;
+            }
+        }
+        return { sessionKey: key, shouldProcess: true, message: msg, cleanContent };
+    }
+    /**
+     * G20 fix: Check all three rate limits (global, per-session, per-user) in
+     * one pass. Refills all three buckets, then either consumes 1 token from
+     * each (when all pass) or returns the blocking bucket (when any fails).
+     *
+     * Returns null on success (tokens consumed), or the blocking bucket on
+     * failure (no tokens consumed). The caller uses the blocking bucket's
+     * `notified` flag to debounce the "请稍后再试" reply per-bucket, so a user
+     * blocked by per-user limit doesn't get spammed when their per-session
+     * bucket still has tokens.
+     */
+    checkAllRateLimits(key, uid) {
+        this.cleanStaleBuckets();
+        const now = Date.now();
+        const maxPerMinute = this.config.rateLimit.maxPerMinute;
+        const globalMax = maxPerMinute * GLOBAL_RATE_MULTIPLIER;
+        const globalBucket = this.getOrCreateGlobalBucket(now, globalMax);
+        // Per-participant session bucket: key by session AND uid. For a group the
+        // sessionKey is the channel_id (shared), so keying the rate bucket by
+        // sessionKey alone would collapse the WHOLE room into one maxPerMinute quota
+        // (the 6th message/min from ANY member blocked). Including uid restores a
+        // per-member per-channel quota — matching the pre-shared-session behavior —
+        // while the global + per-user buckets still bound abuse. For a DM the
+        // sessionKey already embeds the peer, so this is just per-peer. Joined with a
+        // newline (never present in a uid/key) so distinct pairs can't alias.
+        const sessionBucketKey = `${key}\n${uid}`;
+        const sessionBucket = this.getOrCreateBucket(this.tokenBuckets, sessionBucketKey, now, maxPerMinute);
+        const userBucket = this.getOrCreateBucket(this.userBuckets, uid, now, maxPerMinute);
+        this.refillBucket(globalBucket, now, globalMax);
+        this.refillBucket(sessionBucket, now, maxPerMinute);
+        this.refillBucket(userBucket, now, maxPerMinute);
+        // Check in priority order: global → per-user → per-session.
+        // Per-user before per-session so a user blocked across groups gets a
+        // consistent debounce target instead of one per session bucket.
+        if (globalBucket.tokens < 1)
+            return globalBucket;
+        if (userBucket.tokens < 1)
+            return userBucket;
+        if (sessionBucket.tokens < 1)
+            return sessionBucket;
+        // All pass — consume one token from each, and clear notified flags so
+        // future blocks get a fresh debounce window.
+        globalBucket.tokens -= 1;
+        sessionBucket.tokens -= 1;
+        userBucket.tokens -= 1;
+        globalBucket.notified = false;
+        sessionBucket.notified = false;
+        userBucket.notified = false;
+        return null;
+    }
+    getOrCreateBucket(map, key, now, capacity) {
+        let bucket = map.get(key);
+        if (!bucket) {
+            bucket = { tokens: capacity, lastRefill: now, notified: false };
+            map.set(key, bucket);
+        }
+        return bucket;
+    }
+    getOrCreateGlobalBucket(now, capacity) {
+        if (!this.globalBucket) {
+            this.globalBucket = { tokens: capacity, lastRefill: now, notified: false };
+        }
+        return this.globalBucket;
+    }
+    refillBucket(bucket, now, capacity) {
+        const elapsed = now - bucket.lastRefill;
+        const refill = (elapsed / 60_000) * capacity;
+        bucket.tokens = Math.min(capacity, bucket.tokens + refill);
+        bucket.lastRefill = now;
+    }
+    /** Remove token buckets that haven't been used in 5 minutes. */
+    cleanStaleBuckets() {
+        const now = Date.now();
+        for (const [key, bucket] of this.tokenBuckets) {
+            if (now - bucket.lastRefill > BUCKET_STALE_MS) {
+                this.tokenBuckets.delete(key);
+            }
+        }
+        for (const [uid, bucket] of this.userBuckets) {
+            if (now - bucket.lastRefill > BUCKET_STALE_MS) {
+                this.userBuckets.delete(uid);
+            }
+        }
+    }
+    async replySafe(msg, content) {
+        if (!msg.channel_id || msg.channel_type === undefined)
+            return;
+        try {
+            await sendMessage({
+                apiUrl: this.config.apiUrl,
+                botToken: this.config.botToken,
+                channelId: msg.channel_id,
+                channelType: msg.channel_type,
+                content,
+            });
+        }
+        catch (err) {
+            console.error(`session-router: reply failed: ${String(err)}`);
+        }
+    }
+}
+//# sourceMappingURL=session-router.js.map

package/dist/session-router.js.map

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

package/dist/session-store.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Session Store — SQLite persistence via better-sqlite3 + thin adapter.
+ */
+import type { DbAdapter } from './db-adapter.js';
+export interface Session {
+    id: string;
+    channelId: string;
+    channelType: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export declare class SessionStore {
+    private readonly adapter;
+    private selectSession;
+    private insertSession;
+    private touchSession;
+    private insertMessage;
+    private selectRecentMessages;
+    private deleteExpired;
+    private deleteSessionStmt;
+    private upsertResetBarrier;
+    private selectResetBarrier;
+    private upsertSdkSession;
+    private selectSdkSession;
+    private deleteSdkSession;
+    private deleteExpiredSdkSessions;
+    /** Tracks the last message_seq at which the bot replied, per group session key. */
+    private lastBotReplySeq;
+    constructor(adapter: DbAdapter);
+    init(): void;
+    getOrCreate(id: string, channelId: string, channelType: number): Session;
+    appendUser(sessionId: string, content: string, messageSeq?: number, fromName?: string): void;
+    appendAssistant(sessionId: string, content: string, messageSeq?: number, botName?: string): void;
+    private append;
+    /**
+     * Render one history turn with speaker attribution. Group sessions are shared
+     * across members, so every turn names its sender — `[user <name>]:` and
+     * `[assistant <botName>]:`. The name is sanitized at write time (see append())
+     * so it cannot forge turn labels; the `?? role` coalesce only guards rows from
+     * before this column existed.
+     *
+     * SECURITY: the message CONTENT is also user-controlled and travels into the
+     * shared `[Conversation history]` block. A body whose line starts with
+     * `[assistant ...]:` / `[user ...]:` would forge an extra turn that, in shared
+     * group mode, every member then reads as real conversation (cross-user context
+     * poisoning — the same threat the from_name strip closes, but via content and
+     * easier to exploit since no display name is needed). So we neutralize any
+     * line-leading role label in the content here, at render time. This is the one
+     * coherent policy: turn labels can ONLY originate from this renderer, never
+     * from a user-controlled name or body.
+     */
+    private renderTurn;
+    buildHistoryPrefix(sessionId: string, limit: number): string;
+    cleanExpired(): number;
+    deleteSession(sessionId: string): void;
+    /**
+     * v0.3 /reset: record a barrier so cold-start backfill never resurrects
+     * history at or before `resetSeq`. Persisted independently of the session row
+     * (survives deleteSession + restart). Monotonic — a later reset raises the
+     * barrier, an out-of-order/older seq is ignored.
+     *
+     * `resetSeq` is the message_seq of the /reset command itself; everything up to
+     * and including it is considered intentionally discarded.
+     */
+    setResetBarrier(sessionId: string, resetSeq: number): void;
+    /** Return the reset barrier seq for a session, or undefined if never reset. */
+    getResetBarrier(sessionId: string): number | undefined;
+    /**
+     * v0.3 persistent sessions: record the SDK session UUID for a sessionKey so a
+     * later turn can resume it. Upserts (latest wins).
+     */
+    setSdkSessionId(sessionId: string, sdkSessionId: string): void;
+    /** Return the stored SDK session UUID for a sessionKey, or undefined. */
+    getSdkSessionId(sessionId: string): string | undefined;
+    /** Forget the SDK session mapping (e.g. on /reset or a resume failure). */
+    clearSdkSessionId(sessionId: string): void;
+    close(): void;
+    /** Record the message_seq at which the bot last replied for a session. */
+    setLastBotReplySeq(sessionId: string, seq: number): void;
+    /** Get the message_seq at which the bot last replied for a session. */
+    getLastBotReplySeq(sessionId: string): number | undefined;
+    /**
+     * Build history prefix with answered/new segmentation (G10).
+     * Messages with message_seq <= lastBotReplySeq are labeled [answered history],
+     * messages after are labeled [new messages]. Falls back to flat history if
+     * no lastBotReplySeq tracked or no seq data available.
+     */
+    buildSegmentedHistoryPrefix(sessionId: string, limit: number): string;
+}