@mininglamp-oss/cc-channel-octo 1.0.1

package/dist/gateway.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Gateway — WS lifecycle management + bot registration + token refresh.
+ */
+import type { Config } from './config.js';
+import type { BotMessage } from './octo/types.js';
+export type MessageHandler = (msg: BotMessage) => void;
+export declare class OctoGateway {
+    private readonly config;
+    private readonly options;
+    private socket;
+    private robotId;
+    private registration;
+    private _ownerUid;
+    private heartbeatTimer;
+    private lockFilePath;
+    /** Random per-process token written into the lock so ownership survives PID
+     *  reuse: release only removes a lock that still carries OUR nonce. */
+    private readonly lockNonce;
+    private onMessage;
+    /** When true, new messages are silently dropped (shutdown draining). */
+    private _draining;
+    private isRefreshing;
+    private lastRefreshTime;
+    private readonly REFRESH_COOLDOWN_MS;
+    private heartbeatFailCount;
+    private readonly MAX_HEARTBEAT_FAILURES;
+    /** True while a heartbeat request is in flight — prevents overlapping ticks. */
+    private heartbeatInFlight;
+    /** Bumped on each startHeartbeat() so an orphaned tick from a prior run can't
+     *  mutate the new counter (see the generation guard in the tick). */
+    private heartbeatGen;
+    constructor(config: Config, options?: {
+        handleSignals?: boolean;
+    });
+    get botId(): string;
+    /** G18: owner_uid returned by registerBot. Empty string until start() succeeds. */
+    get ownerUid(): string;
+    /** Set the message handler. Called for every incoming BotMessage. */
+    setMessageHandler(handler: MessageHandler): void;
+    /**
+     * Start the gateway: register → connect WS → heartbeat. Convenience wrapper
+     * that does registration and connection in one call (single-bot path + tests).
+     * Multi-bot startup calls register() and connect() separately so no socket
+     * begins ACKing messages before its message handler is installed.
+     */
+    start(): Promise<void>;
+    /**
+     * Phase 1 of startup: acquire the lock and register the bot over REST. This
+     * populates botId/ownerUid but does NOT open the WebSocket, so no messages can
+     * arrive yet. Safe to call before the message handler is wired.
+     */
+    register(): Promise<void>;
+    /**
+     * Phase 2 of startup: open the WebSocket and start the heartbeat. Call only
+     * AFTER setMessageHandler() so inbound messages are dispatched, not ACK'd and
+     * dropped. Registers signal handlers unless handleSignals is false.
+     */
+    connect(): void;
+    /**
+     * Start the REST-backed runtime services: the heartbeat / token-refresh loop
+     * and (unless handleSignals is false) the SIGINT/SIGTERM shutdown handlers.
+     * Called by connect() after the socket is opened. Multi-bot mode passes
+     * handleSignals=false so the orchestrator owns a single combined shutdown.
+     */
+    startServices(): void;
+    /** Whether the gateway is draining (rejecting new messages). */
+    get draining(): boolean;
+    /**
+     * Gracefully stop: set draining → wait for in-flight handlers →
+     * stop heartbeat → disconnect WS → release lock.
+     *
+     * @param activeHandlers - Set of in-flight handler promises to drain.
+     *   Supplied by the orchestrator (index.ts) that tracks them.
+     * @param drainTimeoutMs - Max time (ms) to wait for in-flight handlers
+     *   before force-proceeding. Default 10000.
+     */
+    stop(activeHandlers?: Set<Promise<void>>, drainTimeoutMs?: number): Promise<void>;
+    private acquireLock;
+    /** Read the PID field of the existing lock, or null if unreadable. */
+    private readLockPid;
+    /**
+     * If the existing lock's holder is provably gone, remove it and return true so
+     * the caller can retry the atomic create. Returns false if the holder is alive
+     * (or the lock vanished — caller's retry will race fairly).
+     */
+    private reclaimIfStale;
+    private releaseLock;
+    private createSocket;
+    private handleMessage;
+    private attemptTokenRefresh;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private onShutdown;
+    /**
+     * Set a shutdown callback. Called on SIGINT/SIGTERM before process.exit.
+     * The orchestrator (index.ts) wires this to drain handlers + close store.
+     */
+    setShutdownCallback(fn: () => Promise<void>): void;
+    private setupShutdownHandlers;
+}

package/dist/gateway.js

@@ -0,0 +1,420 @@
+/**
+ * Gateway — WS lifecycle management + bot registration + token refresh.
+ */
+import { WKSocket } from './octo/socket.js';
+import { registerBot, sendHeartbeat } from './octo/api.js';
+import { isAllowedWsUrl } from './url-policy.js';
+import { existsSync, writeFileSync, unlinkSync, readFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+// Read version from package.json at load time (Q31: no hardcoded version).
+const _require = createRequire(import.meta.url);
+const PKG_VERSION = _require('../package.json').version;
+export class OctoGateway {
+    config;
+    options;
+    socket = null;
+    robotId = '';
+    // Stored registration result from register(); consumed by connect().
+    registration = null;
+    // G18: owner_uid from registerBot; used by SessionRouter for future permission model.
+    _ownerUid = '';
+    heartbeatTimer = null;
+    lockFilePath;
+    /** Random per-process token written into the lock so ownership survives PID
+     *  reuse: release only removes a lock that still carries OUR nonce. */
+    lockNonce = randomUUID();
+    onMessage = null;
+    /** When true, new messages are silently dropped (shutdown draining). */
+    _draining = false;
+    // Token refresh state
+    isRefreshing = false;
+    lastRefreshTime = 0;
+    REFRESH_COOLDOWN_MS = 60_000;
+    // Heartbeat failure tracking
+    heartbeatFailCount = 0;
+    MAX_HEARTBEAT_FAILURES = 3;
+    /** True while a heartbeat request is in flight — prevents overlapping ticks. */
+    heartbeatInFlight = false;
+    /** Bumped on each startHeartbeat() so an orphaned tick from a prior run can't
+     *  mutate the new counter (see the generation guard in the tick). */
+    heartbeatGen = 0;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.options = options;
+        this.lockFilePath = join(config.dataDir, 'gateway.lock');
+    }
+    get botId() {
+        return this.robotId;
+    }
+    /** G18: owner_uid returned by registerBot. Empty string until start() succeeds. */
+    get ownerUid() {
+        return this._ownerUid;
+    }
+    /** Set the message handler. Called for every incoming BotMessage. */
+    setMessageHandler(handler) {
+        this.onMessage = handler;
+    }
+    /**
+     * Start the gateway: register → connect WS → heartbeat. Convenience wrapper
+     * that does registration and connection in one call (single-bot path + tests).
+     * Multi-bot startup calls register() and connect() separately so no socket
+     * begins ACKing messages before its message handler is installed.
+     */
+    async start() {
+        await this.register();
+        this.connect();
+    }
+    /**
+     * Phase 1 of startup: acquire the lock and register the bot over REST. This
+     * populates botId/ownerUid but does NOT open the WebSocket, so no messages can
+     * arrive yet. Safe to call before the message handler is wired.
+     */
+    async register() {
+        this.acquireLock();
+        try {
+            const reg = await registerBot({
+                apiUrl: this.config.apiUrl,
+                botToken: this.config.botToken,
+                agentPlatform: 'cc-channel-octo',
+                agentVersion: PKG_VERSION,
+            });
+            this.robotId = reg.robot_id;
+            this._ownerUid = reg.owner_uid;
+            this.registration = reg;
+            console.log(`Bot registered: robot_id=${reg.robot_id}`);
+        }
+        catch (err) {
+            // registerBot failed (bad token, network) AFTER we took the lock. Release
+            // it so a partial-startup failure doesn't leave a stale lock with this
+            // live PID — otherwise the next start refuses with "Another instance is
+            // running". The multi-bot startup cleanup only tears down bots that
+            // returned a BotStack, so this failed bot must clean up its own lock here.
+            this.releaseLock();
+            throw err;
+        }
+    }
+    /**
+     * Phase 2 of startup: open the WebSocket and start the heartbeat. Call only
+     * AFTER setMessageHandler() so inbound messages are dispatched, not ACK'd and
+     * dropped. Registers signal handlers unless handleSignals is false.
+     */
+    connect() {
+        if (!this.registration) {
+            throw new Error('OctoGateway.connect() called before register()');
+        }
+        const reg = this.registration;
+        // SECURITY: the AES-CBC payload layer is unauthenticated, so transport
+        // integrity is the only tamper guarantee. Refuse a plaintext ws:// endpoint
+        // for any non-loopback host (a MITM could bit-flip ciphertext undetected).
+        // wss:// is required in production; ws://localhost is allowed for local dev.
+        if (!isAllowedWsUrl(reg.ws_url)) {
+            throw new Error(`OctoGateway.connect(): refusing insecure WebSocket URL "${reg.ws_url}" — ` +
+                `wss:// is required (ws:// permitted only for localhost). The message layer ` +
+                `is unauthenticated, so an unencrypted transport allows undetected tampering.`);
+        }
+        this.socket = this.createSocket(reg.ws_url, reg.robot_id, reg.im_token);
+        this.socket.connect();
+        this.startServices();
+    }
+    /**
+     * Start the REST-backed runtime services: the heartbeat / token-refresh loop
+     * and (unless handleSignals is false) the SIGINT/SIGTERM shutdown handlers.
+     * Called by connect() after the socket is opened. Multi-bot mode passes
+     * handleSignals=false so the orchestrator owns a single combined shutdown.
+     */
+    startServices() {
+        if (!this.registration) {
+            throw new Error('OctoGateway.startServices() called before register()');
+        }
+        this.startHeartbeat();
+        // Multi-bot: the orchestrator owns a single combined SIGINT/SIGTERM handler,
+        // so individual gateways skip registering their own (default true keeps the
+        // single-bot behavior unchanged).
+        if (this.options.handleSignals !== false) {
+            this.setupShutdownHandlers();
+        }
+    }
+    /** Whether the gateway is draining (rejecting new messages). */
+    get draining() {
+        return this._draining;
+    }
+    /**
+     * Gracefully stop: set draining → wait for in-flight handlers →
+     * stop heartbeat → disconnect WS → release lock.
+     *
+     * @param activeHandlers - Set of in-flight handler promises to drain.
+     *   Supplied by the orchestrator (index.ts) that tracks them.
+     * @param drainTimeoutMs - Max time (ms) to wait for in-flight handlers
+     *   before force-proceeding. Default 10000.
+     */
+    async stop(activeHandlers, drainTimeoutMs = 10_000) {
+        // Mark draining — new messages will be dropped by handleMessage
+        this._draining = true;
+        // Wait for in-flight message handlers to complete (with timeout)
+        if (activeHandlers && activeHandlers.size > 0) {
+            console.log(`[cc-channel-octo] Draining ${activeHandlers.size} in-flight handler(s)...`);
+            const drainPromise = Promise.allSettled([...activeHandlers]);
+            const timeout = new Promise((r) => setTimeout(r, drainTimeoutMs));
+            await Promise.race([drainPromise, timeout]);
+            if (activeHandlers.size > 0) {
+                console.warn(`[cc-channel-octo] Drain timeout, ${activeHandlers.size} handler(s) still active`);
+            }
+        }
+        this.stopHeartbeat();
+        if (this.socket) {
+            await this.socket.disconnectAndWait();
+            this.socket = null;
+        }
+        this.releaseLock();
+    }
+    // --- Lock file ---
+    acquireLock() {
+        const dir = dirname(this.lockFilePath);
+        mkdirSync(dir, { recursive: true });
+        const content = `${process.pid} ${this.lockNonce}`;
+        // Try at most twice: first attempt, then once more after reclaiming a stale
+        // lock. The create is ATOMIC (flag 'wx' = O_EXCL) so two processes racing to
+        // acquire can't both succeed — the loser gets EEXIST and is handled as "held"
+        // (or reclaims only if the holder is provably dead).
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                writeFileSync(this.lockFilePath, content, { mode: 0o600, flag: 'wx' });
+                return; // won the lock atomically
+            }
+            catch (err) {
+                const e = err;
+                if (e.code !== 'EEXIST')
+                    throw err; // unexpected fs error
+                // Lock exists — decide whether the holder is alive.
+                if (attempt > 0 || !this.reclaimIfStale()) {
+                    // Either we already reclaimed once and lost the re-create race (a
+                    // concurrent process won — it IS running), or the holder is alive.
+                    const held = this.readLockPid();
+                    throw new Error(`Another instance is running (PID ${held ?? 'unknown'}). Lock file: ${this.lockFilePath}`);
+                }
+                // reclaimIfStale() removed a dead lock — loop once to re-create.
+            }
+        }
+    }
+    /** Read the PID field of the existing lock, or null if unreadable. */
+    readLockPid() {
+        try {
+            const pid = parseInt(readFileSync(this.lockFilePath, 'utf-8').trim().split(/\s+/)[0], 10);
+            return Number.isInteger(pid) ? pid : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * If the existing lock's holder is provably gone, remove it and return true so
+     * the caller can retry the atomic create. Returns false if the holder is alive
+     * (or the lock vanished — caller's retry will race fairly).
+     */
+    reclaimIfStale() {
+        const pid = this.readLockPid();
+        if (pid === null) {
+            // Corrupt/empty/non-numeric lock (e.g. a partial write) — reclaim it.
+            try {
+                unlinkSync(this.lockFilePath);
+            }
+            catch { /* vanished — fine */ }
+            return true;
+        }
+        try {
+            process.kill(pid, 0); // signal 0 = liveness check
+            return false; // holder is alive and signalable → genuinely held
+        }
+        catch (err) {
+            const e = err;
+            if (e.code === 'EPERM') {
+                // PID exists but owned by another user — can't be our bot (one service
+                // user per dataDir), so almost certainly a reused PID. Reclaim.
+                console.warn(`Lock PID ${pid} exists but is not signalable (EPERM) — likely a reused ` +
+                    `PID; reclaiming the stale lock at ${this.lockFilePath}`);
+            }
+            else {
+                console.log(`Removing stale lock file (PID ${pid} not found)`);
+            }
+            try {
+                unlinkSync(this.lockFilePath);
+            }
+            catch { /* vanished — fine */ }
+            return true;
+        }
+    }
+    releaseLock() {
+        try {
+            if (existsSync(this.lockFilePath)) {
+                const content = readFileSync(this.lockFilePath, 'utf-8').trim();
+                // Only remove the lock if it still carries OUR nonce — so a lock another
+                // instance acquired after a PID-reuse race is never deleted by us.
+                const [, nonce] = content.split(/\s+/);
+                if (nonce === this.lockNonce) {
+                    unlinkSync(this.lockFilePath);
+                }
+            }
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    // --- Socket factory ---
+    createSocket(wsUrl, uid, token) {
+        return new WKSocket({
+            wsUrl,
+            uid,
+            token,
+            onMessage: (msg) => this.handleMessage(msg),
+            onConnected: () => {
+                console.log('WS connected');
+                this.heartbeatFailCount = 0;
+            },
+            onDisconnected: () => {
+                console.log('WS disconnected');
+            },
+            onError: (err) => {
+                console.error('WS error:', err.message);
+                if (err.message.includes('Kicked') || err.message.includes('Connect failed')) {
+                    void this.attemptTokenRefresh();
+                }
+            },
+        });
+    }
+    // --- Bot registration + WS connection ---
+    // (register() + connect() above split the two phases; see start().)
+    handleMessage(msg) {
+        if (this._draining)
+            return; // Q6: reject new messages during shutdown
+        if (msg.from_uid === this.robotId)
+            return;
+        this.onMessage?.(msg);
+    }
+    // --- Token refresh ---
+    async attemptTokenRefresh() {
+        if (this.isRefreshing)
+            return;
+        const now = Date.now();
+        if (now - this.lastRefreshTime < this.REFRESH_COOLDOWN_MS) {
+            const remaining = Math.ceil((this.REFRESH_COOLDOWN_MS - (now - this.lastRefreshTime)) / 1000);
+            console.log(`Token refresh cooldown (${remaining}s remaining)`);
+            return;
+        }
+        this.isRefreshing = true;
+        this.lastRefreshTime = now;
+        try {
+            console.log('Attempting token refresh...');
+            // Q33: Stop heartbeat during refresh to avoid empty pings
+            this.stopHeartbeat();
+            if (this.socket) {
+                await this.socket.disconnectAndWait();
+                this.socket = null;
+            }
+            const reg = await registerBot({
+                apiUrl: this.config.apiUrl,
+                botToken: this.config.botToken,
+                forceRefresh: true,
+                agentPlatform: 'cc-channel-octo',
+                agentVersion: PKG_VERSION,
+            });
+            this.robotId = reg.robot_id;
+            this._ownerUid = reg.owner_uid;
+            this.registration = reg;
+            console.log('Token refreshed, reconnecting...');
+            this.socket = this.createSocket(reg.ws_url, reg.robot_id, reg.im_token);
+            this.socket.connect();
+            this.startHeartbeat(); // Q33: Restart API heartbeat after successful refresh
+        }
+        catch (err) {
+            console.error('Token refresh failed:', String(err));
+            this.startHeartbeat(); // Q33: Restore heartbeat on failure for self-healing
+        }
+        finally {
+            this.isRefreshing = false;
+        }
+    }
+    // --- Heartbeat (API-level, 30s interval) ---
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatFailCount = 0;
+        const gen = ++this.heartbeatGen;
+        this.heartbeatTimer = setInterval(() => {
+            // Overlap guard: if the previous heartbeat hasn't settled (degraded API
+            // where a request takes ~>= the 30s interval), skip this tick instead of
+            // piling up concurrent requests and racing heartbeatFailCount.
+            if (this.heartbeatInFlight)
+                return;
+            this.heartbeatInFlight = true;
+            void (async () => {
+                try {
+                    await sendHeartbeat({
+                        apiUrl: this.config.apiUrl,
+                        botToken: this.config.botToken,
+                    });
+                    // Generation guard: a tick from a superseded startHeartbeat() (e.g.
+                    // after a token refresh re-armed the timer) must not touch the live
+                    // counter or it could spuriously reset/trip the new one.
+                    if (gen !== this.heartbeatGen)
+                        return;
+                    this.heartbeatFailCount = 0;
+                }
+                catch (err) {
+                    if (gen !== this.heartbeatGen)
+                        return;
+                    this.heartbeatFailCount++;
+                    console.error(`Heartbeat failed (${this.heartbeatFailCount}/${this.MAX_HEARTBEAT_FAILURES}):`, String(err));
+                    if (this.heartbeatFailCount >= this.MAX_HEARTBEAT_FAILURES) {
+                        console.error('Max heartbeat failures reached, triggering reconnect...');
+                        this.heartbeatFailCount = 0;
+                        void this.attemptTokenRefresh();
+                    }
+                }
+                finally {
+                    // Guard the flag reset by generation too: an orphaned tick from a
+                    // superseded startHeartbeat() must NOT clear the live generation's
+                    // in-flight flag, or the next live tick could start a 2nd concurrent
+                    // request — exactly the overlap this guard prevents. stopHeartbeat()
+                    // resets the flag when it abandons a generation.
+                    if (gen === this.heartbeatGen)
+                        this.heartbeatInFlight = false;
+                }
+            })();
+        }, 30_000);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        // Invalidate any in-flight tick so its result is ignored, and allow the next
+        // startHeartbeat to issue immediately.
+        this.heartbeatGen++;
+        this.heartbeatInFlight = false;
+    }
+    // --- Graceful shutdown ---
+    onShutdown = null;
+    /**
+     * Set a shutdown callback. Called on SIGINT/SIGTERM before process.exit.
+     * The orchestrator (index.ts) wires this to drain handlers + close store.
+     */
+    setShutdownCallback(fn) {
+        this.onShutdown = fn;
+    }
+    setupShutdownHandlers() {
+        const shutdown = async (signal) => {
+            console.log(`Received ${signal}, shutting down...`);
+            if (this.onShutdown) {
+                await this.onShutdown();
+            }
+            else {
+                await this.stop();
+            }
+            process.exit(0);
+        };
+        process.once('SIGINT', () => void shutdown('SIGINT'));
+        process.once('SIGTERM', () => void shutdown('SIGTERM'));
+    }
+}
+//# sourceMappingURL=gateway.js.map

package/dist/gateway.js.map

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

package/dist/group-config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * v1.0: GROUP.md / THREAD.md per-conversation instruction files.
+ *
+ * Operators can drop a markdown file with custom instructions for a specific
+ * group (or, later, thread) into a configured directory. Its contents are
+ * injected into the agent's system prompt as a trusted instruction block, so a
+ * group can have its own persona / rules without code changes.
+ *
+ * SECURITY — read carefully. The `[Group instructions]` block is injected into
+ * the system prompt UNSANITIZED, so its contents are trusted. That trust holds
+ * ONLY if the file is writable solely by the operator (the gateway process user).
+ *
+ * Placing `groupConfigDir` outside `cwdBase` is necessary but NOT sufficient:
+ * under the shipped defaults (`allowedTools: '*'`, `bypassPermissions`) the agent
+ * has `Bash`/`Write` and can write ABSOLUTE paths anywhere the gateway user can
+ * write — `cwdBase` is a starting dir, not a chroot. So a malicious user in one
+ * group could drive the agent to write `<groupConfigDir>/<otherGroup>.md` and
+ * inject persistent, trusted instructions into a different group.
+ *
+ * The real protection is OS-level: `groupConfigDir` and its files MUST be made
+ * non-writable by the gateway process user (e.g. root-owned, mode 0755/0644),
+ * and/or the deployment hardened (drop `Bash`, sandboxed FS, unprivileged user).
+ * As cheap defense-in-depth, loadGroupConfig() refuses to inject a file that is
+ * group- or world-writable. The group id is filename-pinned to a safe slug so a
+ * crafted id can't traverse out of the config dir.
+ */
+/** Max bytes of an instruction file we will inject (keeps the prompt bounded). */
+export declare const MAX_GROUP_CONFIG_BYTES = 16384;
+/**
+ * Load the instruction file for a group, or undefined when none applies.
+ *
+ * Looks for `<groupConfigDir>/<groupId>.md`. Returns the trimmed contents,
+ * truncated to MAX_GROUP_CONFIG_BYTES. Returns undefined when:
+ *   - groupConfigDir is not configured,
+ *   - groupId is empty or unsafe as a path segment,
+ *   - the file does not exist or is unreadable.
+ *
+ * Never throws — a misconfigured dir or unreadable file degrades to "no custom
+ * instructions" rather than failing the turn.
+ */
+export declare function loadGroupConfig(groupConfigDir: string | undefined, groupId: string): string | undefined;