@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/dist/orchestrator/src/cli/control/telegramOversightApiClient.js

@@ -0,0 +1,48 @@
+const TELEGRAM_API_ROOT = 'https://api.telegram.org';
+export function createTelegramOversightApiClient(options) {
+    const telegramUrl = (method) => `${TELEGRAM_API_ROOT}/bot${options.botToken}/${method}`;
+    const callTelegram = async (method) => {
+        const response = await options.fetchImpl(telegramUrl(method));
+        const payload = (await response.json());
+        if (!response.ok || !payload.ok || payload.result === undefined) {
+            throw new Error(payload.description ?? `telegram_${method}_failed_${response.status}`);
+        }
+        return payload.result;
+    };
+    return {
+        getMe() {
+            return callTelegram('getMe');
+        },
+        async getUpdates(input) {
+            const query = new URLSearchParams({
+                offset: String(input.offset),
+                timeout: String(input.timeoutSeconds),
+                allowed_updates: JSON.stringify(['message'])
+            });
+            const response = await options.fetchImpl(telegramUrl(`getUpdates?${query.toString()}`), {
+                signal: input.signal
+            });
+            const payload = (await response.json());
+            if (!response.ok || !payload.ok) {
+                throw new Error(payload.description ?? `telegram_get_updates_failed_${response.status}`);
+            }
+            return Array.isArray(payload.result) ? payload.result : [];
+        },
+        async sendMessage(chatId, text) {
+            const response = await options.fetchImpl(telegramUrl('sendMessage'), {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    chat_id: chatId,
+                    text
+                })
+            });
+            const payload = (await response.json());
+            if (!response.ok || !payload.ok) {
+                throw new Error(payload.description ?? `telegram_send_message_failed_${response.status}`);
+            }
+        }
+    };
+}

package/dist/orchestrator/src/cli/control/telegramOversightBridge.js

@@ -0,0 +1,180 @@
+import { logger } from '../../logger.js';
+import { createControlTelegramCommandController } from './controlTelegramCommandController.js';
+import { createControlTelegramReadController } from './controlTelegramReadController.js';
+import { createControlTelegramProjectionNotificationController } from './controlTelegramProjectionNotificationController.js';
+import { createControlTelegramPollingController } from './controlTelegramPollingController.js';
+import { createControlTelegramUpdateHandler } from './controlTelegramUpdateHandler.js';
+import { createDefaultTelegramOversightState, } from './controlTelegramPushState.js';
+import { createTelegramOversightApiClient } from './telegramOversightApiClient.js';
+import { createTelegramOversightControlActionApiClient } from './telegramOversightControlActionApiClient.js';
+import { createTelegramOversightBridgeRuntimeLifecycle } from './telegramOversightBridgeRuntimeLifecycle.js';
+import { createTelegramOversightBridgeProjectionDeliveryQueue } from './telegramOversightBridgeProjectionDeliveryQueue.js';
+import { advanceTelegramOversightBridgeStateNextUpdateId, applyTelegramOversightBridgeStatePatch, createTelegramOversightBridgeStateStore } from './telegramOversightBridgeStateStore.js';
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+const DEFAULT_PUSH_COOLDOWN_MS = 30_000;
+export async function startTelegramOversightBridge(options) {
+    const config = resolveTelegramOversightBridgeConfig(options.env ?? process.env);
+    if (!config) {
+        return null;
+    }
+    const bridge = new TelegramOversightBridgeRuntime({
+        config,
+        runDir: options.runDir,
+        readAdapter: options.readAdapter,
+        baseUrl: options.baseUrl,
+        controlToken: options.controlToken,
+        fetchImpl: options.fetchImpl ?? fetch
+    });
+    await bridge.start();
+    return bridge;
+}
+class TelegramOversightBridgeRuntime {
+    config;
+    readController;
+    stateStore;
+    telegramClient;
+    commandController;
+    updateHandler;
+    pollingController;
+    projectionNotificationController;
+    runtimeLifecycle;
+    projectionDeliveryQueue;
+    state = createDefaultTelegramOversightState();
+    constructor(options) {
+        this.config = options.config;
+        this.readController = createControlTelegramReadController({
+            readAdapter: options.readAdapter,
+            mutationsEnabled: options.config.mutationsEnabled
+        });
+        this.stateStore = createTelegramOversightBridgeStateStore(options.runDir);
+        this.telegramClient = createTelegramOversightApiClient({
+            botToken: options.config.botToken,
+            fetchImpl: options.fetchImpl
+        });
+        const controlActionClient = createTelegramOversightControlActionApiClient({
+            baseUrl: options.baseUrl,
+            controlToken: options.controlToken,
+            fetchImpl: options.fetchImpl
+        });
+        this.commandController = createControlTelegramCommandController({
+            mutationsEnabled: options.config.mutationsEnabled,
+            controlActionClient
+        });
+        this.updateHandler = createControlTelegramUpdateHandler({
+            allowedChatIds: options.config.allowedChatIds,
+            readController: this.readController,
+            commandController: this.commandController,
+            sendMessage: (chatId, text) => this.telegramClient.sendMessage(chatId, text)
+        });
+        this.pollingController = createControlTelegramPollingController({
+            pollIntervalMs: options.config.pollIntervalMs,
+            telegramClient: this.telegramClient,
+            updateHandler: this.updateHandler
+        });
+        this.projectionNotificationController = createControlTelegramProjectionNotificationController({
+            allowedChatIds: options.config.allowedChatIds,
+            pushCooldownMs: options.config.pushCooldownMs,
+            renderProjectionDeltaMessage: () => this.readController.renderProjectionDeltaMessage(),
+            sendMessage: (chatId, text) => this.telegramClient.sendMessage(chatId, text)
+        });
+        let readRuntimeClosed = null;
+        this.projectionDeliveryQueue = createTelegramOversightBridgeProjectionDeliveryQueue({
+            pushEnabled: this.config.pushEnabled,
+            isClosed: () => readRuntimeClosed?.() ?? false,
+            readPushState: () => this.state.push,
+            notifyProjectionDelta: ({ pushState, eventSeq }) => this.projectionNotificationController.notifyProjectionDelta({
+                pushState,
+                eventSeq
+            }),
+            applyStatePatchAndSave: async (statePatch) => {
+                this.state = applyTelegramOversightBridgeStatePatch(this.state, statePatch);
+                await this.stateStore.saveState(this.state);
+            },
+            logDeliveryFailure: (error) => {
+                logger.warn(`[telegram-oversight] push notification failed: ${error?.message ?? String(error)}`);
+            }
+        });
+        this.runtimeLifecycle = createTelegramOversightBridgeRuntimeLifecycle({
+            loadState: () => this.stateStore.loadState(),
+            setState: (state) => {
+                this.state = state;
+            },
+            getBotIdentity: () => this.telegramClient.getMe(),
+            runPolling: (runtime) => this.pollingController.run({
+                isClosed: runtime.isClosed,
+                readNextUpdateId: () => this.state.next_update_id,
+                persistNextUpdateId: (nextUpdateId, observedAt) => this.persistNextUpdateId(nextUpdateId, observedAt),
+                readBotUsername: runtime.readBotUsername
+            }),
+            abortPolling: () => this.pollingController.abort(),
+            flushNotifications: async () => {
+                await this.projectionDeliveryQueue.flushNotifications();
+            },
+            logEnabled: (botUsername) => {
+                logger.info(`[telegram-oversight] enabled for ${Array.from(this.config.allowedChatIds).length} chat(s) as @${botUsername ?? 'bot'}`);
+            }
+        });
+        readRuntimeClosed = () => this.runtimeLifecycle.isClosed();
+    }
+    async start() {
+        await this.runtimeLifecycle.start();
+    }
+    async close() {
+        await this.runtimeLifecycle.close();
+    }
+    async notifyProjectionDelta(input = {}) {
+        await this.projectionDeliveryQueue.notifyProjectionDelta(input);
+    }
+    async persistNextUpdateId(nextUpdateId, observedAt) {
+        this.state = advanceTelegramOversightBridgeStateNextUpdateId(this.state, nextUpdateId, observedAt);
+        await this.stateStore.saveState(this.state);
+    }
+}
+function resolveTelegramOversightBridgeConfig(env) {
+    if (!parseBooleanEnv(env.CO_TELEGRAM_POLLING_ENABLED)) {
+        return null;
+    }
+    const botToken = env.CO_TELEGRAM_BOT_TOKEN?.trim();
+    if (!botToken) {
+        return null;
+    }
+    const allowedChatIds = parseCsvSet(env.CO_TELEGRAM_ALLOWED_CHAT_IDS);
+    if (allowedChatIds.size === 0) {
+        return null;
+    }
+    return {
+        botToken,
+        allowedChatIds,
+        mutationsEnabled: parseBooleanEnv(env.CO_TELEGRAM_ENABLE_MUTATIONS),
+        pollIntervalMs: parsePositiveIntegerEnv(env.CO_TELEGRAM_POLL_INTERVAL_MS, DEFAULT_POLL_INTERVAL_MS),
+        pushEnabled: parseBooleanEnv(env.CO_TELEGRAM_PUSH_ENABLED),
+        pushCooldownMs: parsePositiveIntegerEnv(env.CO_TELEGRAM_PUSH_INTERVAL_MS, DEFAULT_PUSH_COOLDOWN_MS)
+    };
+}
+function parseCsvSet(value) {
+    if (!value) {
+        return new Set();
+    }
+    const entries = value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return new Set(entries);
+}
+function parseBooleanEnv(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+}
+function parsePositiveIntegerEnv(value, fallback) {
+    if (!value) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return fallback;
+    }
+    return parsed;
+}

package/dist/orchestrator/src/cli/control/telegramOversightBridgeProjectionDeliveryQueue.js

@@ -0,0 +1,25 @@
+export function createTelegramOversightBridgeProjectionDeliveryQueue(input) {
+    let notificationQueue = Promise.resolve();
+    return {
+        async notifyProjectionDelta(request = {}) {
+            if (!input.pushEnabled || input.isClosed()) {
+                return;
+            }
+            notificationQueue = notificationQueue
+                .then(async () => {
+                const result = await input.notifyProjectionDelta({
+                    pushState: input.readPushState(),
+                    eventSeq: request.eventSeq
+                });
+                await input.applyStatePatchAndSave(result.statePatch);
+            })
+                .catch((error) => {
+                input.logDeliveryFailure(error);
+            });
+            await notificationQueue;
+        },
+        async flushNotifications() {
+            await notificationQueue;
+        }
+    };
+}

package/dist/orchestrator/src/cli/control/telegramOversightBridgeRuntimeLifecycle.js

@@ -0,0 +1,45 @@
+const DEFAULT_CLOSE_POLL_GRACE_MS = 1_000;
+export function createTelegramOversightBridgeRuntimeLifecycle(input) {
+    let closed = false;
+    let loopPromise = null;
+    let botIdentity = null;
+    const closePollGraceMs = Math.max(0, input.closePollGraceMs ?? DEFAULT_CLOSE_POLL_GRACE_MS);
+    return {
+        async start() {
+            input.setState(await input.loadState());
+            botIdentity = await input.getBotIdentity();
+            input.logEnabled(botIdentity.username ?? null);
+            loopPromise = input.runPolling({
+                isClosed: () => closed,
+                readBotUsername: () => botIdentity?.username ?? null
+            });
+        },
+        async close() {
+            closed = true;
+            input.abortPolling();
+            if (loopPromise) {
+                const activeLoopPromise = loopPromise;
+                loopPromise = null;
+                await Promise.race([
+                    activeLoopPromise.catch(() => undefined),
+                    delay(closePollGraceMs)
+                ]);
+            }
+            try {
+                await input.flushNotifications();
+            }
+            catch {
+                // Ignore queued notification errors during shutdown.
+            }
+        },
+        isClosed() {
+            return closed;
+        },
+    };
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}

package/dist/orchestrator/src/cli/control/telegramOversightBridgeStateStore.js

@@ -0,0 +1,77 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeJsonAtomic } from '../utils/fs.js';
+import { createDefaultTelegramOversightState } from './controlTelegramPushState.js';
+const TELEGRAM_STATE_FILE = 'telegram-oversight-state.json';
+export function createTelegramOversightBridgeStateStore(runDir) {
+    const statePath = join(runDir, TELEGRAM_STATE_FILE);
+    return {
+        loadState: async () => readTelegramOversightState(statePath),
+        saveState: async (state) => writeJsonAtomic(statePath, state)
+    };
+}
+export function advanceTelegramOversightBridgeStateNextUpdateId(state, nextUpdateId, observedAt) {
+    return {
+        ...state,
+        next_update_id: nextUpdateId,
+        updated_at: pickLatestTimestamp(state.updated_at, observedAt)
+    };
+}
+export function applyTelegramOversightBridgeStatePatch(state, patch) {
+    return {
+        ...state,
+        updated_at: pickLatestTimestamp(state.updated_at, patch.updated_at),
+        push: patch.push
+    };
+}
+async function readTelegramOversightState(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        const parsedPush = isRecord(parsed.push) ? parsed.push : null;
+        const nextUpdateId = typeof parsed.next_update_id === 'number' && Number.isInteger(parsed.next_update_id) && parsed.next_update_id >= 0
+            ? parsed.next_update_id
+            : 0;
+        return {
+            next_update_id: nextUpdateId,
+            updated_at: typeof parsed.updated_at === 'string' && parsed.updated_at.trim().length > 0
+                ? parsed.updated_at
+                : new Date(0).toISOString(),
+            push: {
+                last_sent_projection_hash: parsedPush ? readStringValue(parsedPush, 'last_sent_projection_hash') ?? null : null,
+                last_sent_at: parsedPush ? readStringValue(parsedPush, 'last_sent_at') ?? null : null,
+                last_event_seq: parsedPush && typeof parsedPush.last_event_seq === 'number' && Number.isInteger(parsedPush.last_event_seq)
+                    ? parsedPush.last_event_seq
+                    : null,
+                pending_projection_hash: parsedPush ? readStringValue(parsedPush, 'pending_projection_hash') ?? null : null,
+                pending_projection_observed_at: parsedPush ? readStringValue(parsedPush, 'pending_projection_observed_at') ?? null : null
+            }
+        };
+    }
+    catch {
+        return createDefaultTelegramOversightState();
+    }
+}
+function pickLatestTimestamp(currentIso, candidateIso) {
+    const currentMs = Date.parse(currentIso);
+    const candidateMs = Date.parse(candidateIso);
+    if (!Number.isFinite(currentMs)) {
+        return candidateIso;
+    }
+    if (!Number.isFinite(candidateMs)) {
+        return currentIso;
+    }
+    return candidateMs >= currentMs ? candidateIso : currentIso;
+}
+function readStringValue(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/orchestrator/src/cli/control/telegramOversightControlActionApiClient.js

@@ -0,0 +1,45 @@
+export function createTelegramOversightControlActionApiClient(input) {
+    return {
+        postAction: async (body) => readControlActionResponse(await input.fetchImpl(new URL('/control/action', input.baseUrl), {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${input.controlToken}`,
+                'x-csrf-token': input.controlToken,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(body)
+        }))
+    };
+}
+async function readControlActionResponse(response) {
+    const payload = (await response.json());
+    if (!response.ok) {
+        throw new Error(resolveErrorMessage(payload));
+    }
+    return payload;
+}
+function resolveErrorMessage(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return 'request_failed';
+    }
+    const record = payload;
+    if (typeof record.error === 'string' && record.error.trim().length > 0) {
+        return record.error.trim();
+    }
+    const error = record.error;
+    if (error && typeof error === 'object' && !Array.isArray(error)) {
+        const errorRecord = error;
+        const code = typeof errorRecord.code === 'string' ? errorRecord.code : null;
+        const message = typeof errorRecord.message === 'string' ? errorRecord.message : null;
+        if (code && message) {
+            return `${code}: ${message}`;
+        }
+        if (code) {
+            return code;
+        }
+        if (message) {
+            return message;
+        }
+    }
+    return 'request_failed';
+}