@kbediako/codex-orchestrator 0.1.38 → 0.2.1

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

@@ -0,0 +1,22 @@
+import { createControlServerBootstrapLifecycle } from './controlServerBootstrapLifecycle.js';
+import { createControlTelegramBridgeLifecycle } from './controlTelegramBridgeLifecycle.js';
+import { createControlTelegramBridgeOversightFacadeFactory } from './controlTelegramBridgeOversightFacadeFactory.js';
+export function createControlTelegramBridgeBootstrapLifecycle(context) {
+    const telegramBridgeLifecycle = createControlTelegramBridgeLifecycle({
+        runDir: context.paths.runDir,
+        createOversightFacade: createControlTelegramBridgeOversightFacadeFactory({
+            requestContextShared: context.requestContextShared,
+            getExpiryLifecycle: () => context.getExpiryLifecycle(),
+            emitDispatchPilotAuditEvents: context.emitDispatchPilotAuditEvents
+        })
+    });
+    return createControlServerBootstrapLifecycle({
+        paths: {
+            controlAuthPath: context.paths.controlAuthPath,
+            controlEndpointPath: context.paths.controlEndpointPath
+        },
+        persistControl: context.persistControl,
+        startExpiryLifecycle: context.startExpiryLifecycle,
+        telegramBridgeLifecycle
+    });
+}

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

@@ -0,0 +1,67 @@
+import { logger } from '../../logger.js';
+import { startTelegramOversightBridge } from './telegramOversightBridge.js';
+export function createControlTelegramBridgeLifecycle(options) {
+    return new ControlTelegramBridgeLifecycleRuntime(options);
+}
+class ControlTelegramBridgeLifecycleRuntime {
+    runDir;
+    createOversightFacade;
+    startTelegramBridgeImpl;
+    telegramBridge = null;
+    unsubscribeTelegramBridge = null;
+    lifecycleOperation = Promise.resolve();
+    constructor(options) {
+        this.runDir = options.runDir;
+        this.createOversightFacade = options.createOversightFacade;
+        this.startTelegramBridgeImpl = options.startTelegramBridgeImpl ?? startTelegramOversightBridge;
+    }
+    async start(options) {
+        await this.enqueueLifecycleOperation(async () => {
+            await this.closeActiveBridge();
+            const oversightFacade = this.createOversightFacade();
+            const bridge = await this.startTelegramBridgeImpl({
+                runDir: this.runDir,
+                readAdapter: oversightFacade,
+                baseUrl: options.baseUrl,
+                controlToken: options.controlToken
+            });
+            if (!bridge) {
+                return;
+            }
+            await this.attachTelegramBridge(bridge, oversightFacade);
+        });
+    }
+    async close() {
+        await this.enqueueLifecycleOperation(async () => {
+            await this.closeActiveBridge();
+        });
+    }
+    enqueueLifecycleOperation(operation) {
+        const nextOperation = this.lifecycleOperation.then(operation, operation);
+        this.lifecycleOperation = nextOperation.then(() => undefined, () => undefined);
+        return nextOperation;
+    }
+    async closeActiveBridge() {
+        this.unsubscribeTelegramBridge?.();
+        this.unsubscribeTelegramBridge = null;
+        const bridge = this.telegramBridge;
+        this.telegramBridge = null;
+        if (bridge) {
+            await bridge.close().catch((error) => {
+                logger.warn(`Failed to close Telegram oversight bridge: ${error?.message ?? String(error)}`);
+            });
+        }
+    }
+    async attachTelegramBridge(bridge, oversightFacade) {
+        try {
+            this.unsubscribeTelegramBridge = oversightFacade.subscribe((input) => bridge.notifyProjectionDelta(input));
+            this.telegramBridge = bridge;
+        }
+        catch (error) {
+            await bridge.close().catch((closeError) => {
+                logger.warn(`Failed to close Telegram oversight bridge: ${closeError?.message ?? String(closeError)}`);
+            });
+            throw error;
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+import { createControlOversightFacade } from './controlOversightFacade.js';
+export function createControlTelegramBridgeOversightFacadeFactory(context) {
+    return () => createControlOversightFacade({
+        ...context.requestContextShared,
+        expiryLifecycle: context.getExpiryLifecycle(),
+        emitDispatchPilotAuditEvents: context.emitDispatchPilotAuditEvents
+    });
+}

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

@@ -0,0 +1,49 @@
+import { randomBytes } from 'node:crypto';
+export function createControlTelegramCommandController(input) {
+    return {
+        async dispatchMutatingCommand({ command, updateId, chatId, user }) {
+            switch (command) {
+                case '/pause':
+                case '/resume':
+                    return applyControlCommand(command.slice(1), {
+                        updateId,
+                        chatId,
+                        user,
+                        mutationsEnabled: input.mutationsEnabled,
+                        controlActionClient: input.controlActionClient
+                    });
+                default:
+                    return null;
+            }
+        }
+    };
+}
+async function applyControlCommand(action, input) {
+    if (!input.mutationsEnabled) {
+        return `${capitalize(action)} is disabled for this Telegram bridge.`;
+    }
+    const nonce = `telegram:${input.chatId}:${input.updateId}:${action}:${randomBytes(4).toString('hex')}`;
+    const nonceExpiresAt = new Date(Date.now() + 60 * 1000).toISOString();
+    const actorId = input.user?.id ? `telegram.user.${input.user.id}` : `telegram.chat.${input.chatId}`;
+    const body = {
+        action,
+        requested_by: 'telegram',
+        request_id: `telegram-${action}-${input.updateId}`,
+        intent_id: `telegram-${action}-${input.updateId}`,
+        reason: `telegram_command_${action}`,
+        transport: 'telegram',
+        actor_id: actorId,
+        actor_source: 'telegram.bot.polling',
+        transport_principal: `telegram:chat:${input.chatId}`,
+        transport_nonce: nonce,
+        transport_nonce_expires_at: nonceExpiresAt
+    };
+    const payload = await input.controlActionClient.postAction(body);
+    if (payload.error) {
+        return `${capitalize(action)} failed: ${payload.error}`;
+    }
+    return `${capitalize(action)} requested. Control decision: ${payload.traceability?.decision ?? 'applied'}${typeof payload.control_seq === 'number' ? ` (seq ${payload.control_seq})` : ''}.`;
+}
+function capitalize(value) {
+    return value.length === 0 ? value : `${value[0].toUpperCase()}${value.slice(1)}`;
+}

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

@@ -0,0 +1,40 @@
+import { buildControlInternalContext } from './controlRequestContext.js';
+import { readDispatchExtension } from './observabilitySurface.js';
+export async function readControlTelegramDispatch(context) {
+    const internalContext = buildControlInternalContext(context);
+    const runtimeSnapshot = internalContext.runtime.snapshot();
+    const result = await readDispatchExtension({
+        readDispatchEvaluation: () => runtimeSnapshot.readDispatchEvaluation()
+    });
+    await context.emitDispatchPilotAuditEvents(internalContext, {
+        surface: 'telegram_dispatch',
+        evaluation: result.evaluation,
+        issueIdentifier: result.issueIdentifier
+    });
+    return buildTelegramOversightDispatchPayload(result);
+}
+function buildTelegramOversightDispatchPayload(result) {
+    if (result.kind === 'ok') {
+        const payload = result.payload;
+        return {
+            dispatch_pilot: payload.dispatch_pilot && typeof payload.dispatch_pilot === 'object'
+                ? payload.dispatch_pilot
+                : result.evaluation.summary,
+            recommendation: payload.recommendation && typeof payload.recommendation === 'object'
+                ? payload.recommendation
+                : null
+        };
+    }
+    const dispatchPilot = result.details.dispatch_pilot && typeof result.details.dispatch_pilot === 'object'
+        ? result.details.dispatch_pilot
+        : result.evaluation.summary;
+    return {
+        dispatch_pilot: dispatchPilot,
+        error: {
+            code: result.failure.code,
+            details: {
+                dispatch_pilot: dispatchPilot
+            }
+        }
+    };
+}

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

@@ -0,0 +1,89 @@
+import { logger } from '../../logger.js';
+const DEFAULT_POLL_TIMEOUT_SECONDS = 20;
+export function createControlTelegramPollingController(input) {
+    let activeController = null;
+    return {
+        abort() {
+            activeController?.abort();
+            activeController = null;
+        },
+        async run(runtime) {
+            while (!runtime.isClosed()) {
+                try {
+                    const updates = await fetchUpdates({
+                        pollIntervalMs: input.pollIntervalMs,
+                        telegramClient: input.telegramClient,
+                        offset: runtime.readNextUpdateId(),
+                        setActiveController: (controller) => {
+                            activeController = controller;
+                        },
+                        clearActiveController: (controller) => {
+                            if (activeController === controller) {
+                                activeController = null;
+                            }
+                        }
+                    });
+                    if (updates.length > 0) {
+                        await handleUpdates({
+                            updates,
+                            readNextUpdateId: runtime.readNextUpdateId,
+                            persistNextUpdateId: runtime.persistNextUpdateId,
+                            readBotUsername: runtime.readBotUsername,
+                            updateHandler: input.updateHandler
+                        });
+                    }
+                }
+                catch (error) {
+                    if (runtime.isClosed() || isAbortError(error)) {
+                        break;
+                    }
+                    logger.warn(`[telegram-oversight] polling failed: ${error?.message ?? String(error)}`);
+                }
+                if (runtime.isClosed()) {
+                    break;
+                }
+                await delay(input.pollIntervalMs);
+            }
+        }
+    };
+}
+async function fetchUpdates(input) {
+    const controller = new AbortController();
+    input.setActiveController(controller);
+    try {
+        const timeout = Math.max(DEFAULT_POLL_TIMEOUT_SECONDS, Math.ceil((input.pollIntervalMs + 500) / 1_000));
+        return input.telegramClient.getUpdates({
+            offset: input.offset,
+            timeoutSeconds: timeout,
+            signal: controller.signal
+        });
+    }
+    finally {
+        input.clearActiveController(controller);
+    }
+}
+async function handleUpdates(input) {
+    const initialNextUpdateId = input.readNextUpdateId();
+    let nextUpdateId = initialNextUpdateId;
+    for (const update of input.updates) {
+        nextUpdateId = Math.max(nextUpdateId, update.update_id + 1);
+        try {
+            await input.updateHandler.handleUpdate({
+                update,
+                botUsername: input.readBotUsername()
+            });
+        }
+        catch (error) {
+            logger.warn(`[telegram-oversight] failed to handle update ${update.update_id}: ${error?.message ?? String(error)}`);
+        }
+    }
+    if (nextUpdateId !== initialNextUpdateId) {
+        await input.persistNextUpdateId(nextUpdateId, new Date().toISOString());
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}

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

@@ -0,0 +1,29 @@
+import { computeTelegramProjectionStateTransition } from './controlTelegramPushState.js';
+export function createControlTelegramProjectionNotificationController(input) {
+    return {
+        async notifyProjectionDelta({ pushState, eventSeq }) {
+            const nowMs = input.nowMs?.() ?? Date.now();
+            const projection = await input.renderProjectionDeltaMessage();
+            const transition = computeTelegramProjectionStateTransition({
+                pushState,
+                projectionHash: projection.projectionHash,
+                eventSeq,
+                nowMs,
+                pushCooldownMs: input.pushCooldownMs
+            });
+            if (transition.kind !== 'send') {
+                return {
+                    delivery: transition.kind,
+                    statePatch: transition.statePatch
+                };
+            }
+            for (const chatId of input.allowedChatIds) {
+                await input.sendMessage(chatId, projection.text);
+            }
+            return {
+                delivery: 'send',
+                statePatch: transition.statePatch
+            };
+        }
+    };
+}

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

@@ -0,0 +1,63 @@
+export function createDefaultTelegramOversightState() {
+    return {
+        next_update_id: 0,
+        updated_at: new Date(0).toISOString(),
+        push: {
+            last_sent_projection_hash: null,
+            last_sent_at: null,
+            last_event_seq: null,
+            pending_projection_hash: null,
+            pending_projection_observed_at: null
+        }
+    };
+}
+export function computeTelegramProjectionStateTransition(input) {
+    const nextEventSeq = typeof input.eventSeq === 'number' && Number.isFinite(input.eventSeq)
+        ? Math.floor(input.eventSeq)
+        : input.pushState.last_event_seq;
+    const nowIso = new Date(input.nowMs).toISOString();
+    if (!input.projectionHash || input.projectionHash === input.pushState.last_sent_projection_hash) {
+        return {
+            kind: 'skip',
+            statePatch: {
+                updated_at: nowIso,
+                push: {
+                    ...input.pushState,
+                    last_event_seq: nextEventSeq,
+                    pending_projection_hash: null,
+                    pending_projection_observed_at: null
+                }
+            }
+        };
+    }
+    const lastSentAtMs = input.pushState.last_sent_at ? Date.parse(input.pushState.last_sent_at) : Number.NaN;
+    if (Number.isFinite(lastSentAtMs) && input.nowMs - lastSentAtMs < input.pushCooldownMs) {
+        return {
+            kind: 'pending',
+            statePatch: {
+                updated_at: nowIso,
+                push: {
+                    ...input.pushState,
+                    last_event_seq: nextEventSeq,
+                    pending_projection_hash: input.projectionHash,
+                    pending_projection_observed_at: input.projectionHash === input.pushState.pending_projection_hash
+                        ? input.pushState.pending_projection_observed_at ?? nowIso
+                        : nowIso
+                }
+            }
+        };
+    }
+    return {
+        kind: 'send',
+        statePatch: {
+            updated_at: nowIso,
+            push: {
+                last_sent_projection_hash: input.projectionHash,
+                last_sent_at: nowIso,
+                last_event_seq: nextEventSeq,
+                pending_projection_hash: null,
+                pending_projection_observed_at: null
+            }
+        }
+    };
+}

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

@@ -0,0 +1,13 @@
+import { createControlQuestionChildResolutionAdapter } from './controlQuestionChildResolution.js';
+import { buildControlInternalContext } from './controlRequestContext.js';
+import { runQuestionReadSequence } from './questionReadSequence.js';
+export async function readControlTelegramQuestions(context) {
+    const internalContext = buildControlInternalContext(context);
+    const questionChildResolutionAdapter = createControlQuestionChildResolutionAdapter(internalContext);
+    const result = await runQuestionReadSequence({
+        listQuestions: () => internalContext.questionQueue.list(),
+        expireQuestions: () => internalContext.expiryLifecycle?.expireQuestions(questionChildResolutionAdapter) ?? Promise.resolve()
+    });
+    questionChildResolutionAdapter.queueQuestionResolutions(result.retryCandidates);
+    return { questions: result.questions };
+}

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

@@ -0,0 +1,216 @@
+import { createHash } from 'node:crypto';
+import { buildSelectedRunQuestionSummaryPayload, buildSelectedRunRuntimeFingerprintInput } from './observabilityReadModel.js';
+export function createControlTelegramReadController(input) {
+    return {
+        async dispatchReadCommand(command) {
+            switch (command) {
+                case '/start':
+                    return 'CO oversight is connected. Use /help for commands.';
+                case '/help':
+                    return buildHelpMessage(input.mutationsEnabled);
+                case '/status':
+                    return renderStatus(input.readAdapter);
+                case '/issue':
+                    return renderIssue(input.readAdapter);
+                case '/dispatch':
+                    return renderDispatch(input.readAdapter);
+                case '/questions':
+                    return renderQuestions(input.readAdapter);
+                default:
+                    return null;
+            }
+        },
+        async renderProjectionDeltaMessage() {
+            const snapshot = await input.readAdapter.readSelectedRun();
+            return {
+                projectionHash: buildProjectionHash(snapshot),
+                text: buildStatusMessage(snapshot)
+            };
+        }
+    };
+}
+async function renderStatus(readAdapter) {
+    return buildStatusMessage(await readAdapter.readSelectedRun());
+}
+async function renderIssue(readAdapter) {
+    const snapshot = await readAdapter.readSelectedRun();
+    const selected = snapshot.selected ?? null;
+    if (!selected?.issueIdentifier) {
+        return 'No issue identifier is available for the current run.';
+    }
+    const trackedLinear = selected.tracked?.linear ?? snapshot.tracked?.linear ?? null;
+    const latestEvent = selected.latestEvent ?? null;
+    const displayStatus = selected.displayStatus ?? 'unknown';
+    const questionSummary = buildSelectedRunQuestionSummaryPayload(selected.questionSummary);
+    return [
+        `Issue ${selected.issueIdentifier}`,
+        formatStateLine(displayStatus, selected.rawStatus ?? null, 'Status'),
+        selected.statusReason ? `Reason: ${selected.statusReason}` : null,
+        trackedLinear?.identifier
+            ? `Linear: ${trackedLinear.identifier}${trackedLinear.title ? ` - ${truncateLine(trackedLinear.title, 120)}` : ''}`
+            : null,
+        trackedLinear?.state ? `Linear state: ${trackedLinear.state}` : null,
+        trackedLinear?.url ? `Linear URL: ${trackedLinear.url}` : null,
+        latestEvent?.event ? `Latest event: ${latestEvent.event}` : null,
+        latestEvent?.message
+            ? `Latest summary: ${truncateLine(latestEvent.message, 180)}`
+            : selected.summary
+                ? `Latest summary: ${truncateLine(selected.summary, 180)}`
+                : null,
+        formatQuestionSummary(questionSummary),
+        formatDispatchSummary(snapshot.dispatchPilot ?? null)
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+async function renderDispatch(readAdapter) {
+    const payload = await readAdapter.readDispatch();
+    const dispatchPilot = payload.dispatch_pilot ?? payload.error?.details?.dispatch_pilot ?? null;
+    const trackedIssue = payload.recommendation?.tracked_issue ?? null;
+    return [
+        'Dispatch advisory',
+        formatDispatchSummary(dispatchPilot),
+        payload.recommendation?.summary ? `Summary: ${truncateLine(payload.recommendation.summary, 180)}` : null,
+        payload.recommendation?.rationale ? `Rationale: ${truncateLine(payload.recommendation.rationale, 180)}` : null,
+        payload.recommendation?.confidence !== undefined && payload.recommendation?.confidence !== null
+            ? `Confidence: ${payload.recommendation.confidence}`
+            : null,
+        trackedIssue?.identifier
+            ? `Tracked issue: ${trackedIssue.identifier}${trackedIssue.title ? ` - ${truncateLine(trackedIssue.title, 120)}` : ''}`
+            : null,
+        trackedIssue?.url ? `Tracked URL: ${trackedIssue.url}` : null,
+        payload.error?.code ? `Status: ${payload.error.code}` : null
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+async function renderQuestions(readAdapter) {
+    const payload = await readAdapter.readQuestions();
+    const queued = (payload.questions ?? []).filter((question) => question.status === 'queued');
+    if (queued.length === 0) {
+        return 'No queued questions.';
+    }
+    return [
+        `Queued questions: ${queued.length}`,
+        ...queued.slice(0, 3).map((question) => {
+            const urgency = question.urgency ? ` [${question.urgency}]` : '';
+            return `${question.question_id ?? 'question'}${urgency}: ${truncateLine(question.prompt ?? '', 140)}`;
+        })
+    ].join('\n');
+}
+function buildStatusMessage(snapshot) {
+    const selected = snapshot.selected ?? null;
+    const dispatch = snapshot.dispatchPilot ?? null;
+    const trackedLinear = selected?.tracked?.linear ?? snapshot.tracked?.linear ?? null;
+    const providerIntake = snapshot.providerIntake ?? null;
+    if (!selected) {
+        return [
+            'CO status',
+            'No active running projection.',
+            formatProviderIntakeSummary(providerIntake),
+            trackedLinear?.identifier
+                ? `Linear: ${trackedLinear.identifier}${trackedLinear.title ? ` - ${truncateLine(trackedLinear.title, 120)}` : ''}`
+                : null,
+            trackedLinear?.state ? `Linear state: ${trackedLinear.state}` : null,
+            formatDispatchSummary(dispatch)
+        ]
+            .filter(Boolean)
+            .join('\n');
+    }
+    const issueIdentifier = selected.issueIdentifier ?? 'n/a';
+    const sessionId = selected.runId ?? null;
+    const displayStatus = selected.displayStatus ?? 'unknown';
+    const rawStatus = selected.rawStatus ?? null;
+    const statusReason = selected.statusReason ?? null;
+    const latestEvent = selected.latestEvent ?? null;
+    const questionSummary = buildSelectedRunQuestionSummaryPayload(selected.questionSummary);
+    const summary = latestEvent?.message ?? selected.summary ?? null;
+    return [
+        'CO status',
+        `Issue: ${issueIdentifier}`,
+        formatStateLine(displayStatus, rawStatus),
+        statusReason ? `Reason: ${statusReason}` : null,
+        formatProviderIntakeSummary(providerIntake),
+        sessionId ? `Session: ${sessionId}` : null,
+        latestEvent?.event ? `Last event: ${latestEvent.event}` : null,
+        summary ? `Summary: ${truncateLine(summary, 180)}` : null,
+        formatQuestionSummary(questionSummary),
+        trackedLinear?.identifier
+            ? `Linear: ${trackedLinear.identifier}${trackedLinear.title ? ` - ${truncateLine(trackedLinear.title, 120)}` : ''}`
+            : null,
+        trackedLinear?.state ? `Linear state: ${trackedLinear.state}` : null,
+        formatDispatchSummary(dispatch)
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+function buildHelpMessage(mutationsEnabled) {
+    return [
+        'Commands:',
+        '/start',
+        '/help',
+        '/status',
+        '/issue',
+        '/dispatch',
+        '/questions',
+        mutationsEnabled ? '/pause' : '/pause (disabled)',
+        mutationsEnabled ? '/resume' : '/resume (disabled)'
+    ].join('\n');
+}
+function formatDispatchSummary(dispatchPilot) {
+    if (!dispatchPilot) {
+        return null;
+    }
+    const status = dispatchPilot.status ?? 'unknown';
+    const sourceStatus = dispatchPilot.source_status ?? 'unknown';
+    const reason = dispatchPilot.reason ? ` (${dispatchPilot.reason})` : '';
+    return `Dispatch: ${status}/${sourceStatus}${reason}`;
+}
+function formatProviderIntakeSummary(providerIntake) {
+    if (!providerIntake) {
+        return null;
+    }
+    const claim = providerIntake.selected_claim;
+    const runId = claim.run_id ? ` -> ${claim.run_id}` : '';
+    const reason = claim.reason ? ` (${claim.reason})` : '';
+    if (providerIntake.summary_scope === 'selected_claim') {
+        return `Intake: selected claim ${claim.issue_identifier} of ${providerIntake.active_claim_count} active / ${providerIntake.running_claim_count} running -> ${claim.task_id}${runId}${reason}`;
+    }
+    return `Intake: ${claim.state} ${claim.issue_identifier} -> ${claim.task_id}${runId}${reason}`;
+}
+function formatStateLine(displayStatus, rawStatus, label = 'State') {
+    const normalizedDisplay = displayStatus && displayStatus.trim().length > 0 ? displayStatus.trim() : 'unknown';
+    const normalizedRaw = rawStatus && rawStatus.trim().length > 0 ? rawStatus.trim() : null;
+    if (!normalizedRaw || normalizedRaw === normalizedDisplay) {
+        return `${label}: ${normalizedDisplay}`;
+    }
+    return `${label}: ${normalizedDisplay} (raw ${normalizedRaw})`;
+}
+function formatQuestionSummary(summary) {
+    if (!summary || typeof summary.queued_count !== 'number' || summary.queued_count <= 0) {
+        return null;
+    }
+    const latestQuestion = summary.latest_question ?? null;
+    const latestPrompt = latestQuestion?.prompt && latestQuestion.prompt.trim().length > 0
+        ? truncateLine(latestQuestion.prompt, 120)
+        : null;
+    const urgency = latestQuestion?.urgency && latestQuestion.urgency.trim().length > 0 ? ` [${latestQuestion.urgency}]` : '';
+    if (latestQuestion?.question_id) {
+        return `Queued questions: ${summary.queued_count} (latest ${latestQuestion.question_id}${urgency}${latestPrompt ? `: ${latestPrompt}` : ''})`;
+    }
+    return `Queued questions: ${summary.queued_count}`;
+}
+function truncateLine(value, maxLength) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, Math.max(maxLength - 3, 1))}...`;
+}
+function buildProjectionHash(snapshot) {
+    const fingerprint = buildSelectedRunRuntimeFingerprintInput(snapshot);
+    if (!fingerprint) {
+        return null;
+    }
+    return createHash('sha256').update(JSON.stringify(fingerprint)).digest('hex');
+}

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

@@ -0,0 +1,63 @@
+import { logger } from '../../logger.js';
+export function createControlTelegramUpdateHandler(input) {
+    return {
+        async handleUpdate({ update, botUsername }) {
+            const message = update.message;
+            if (!message?.chat) {
+                return;
+            }
+            const chatId = String(message.chat.id);
+            if (!input.allowedChatIds.has(chatId)) {
+                logger.warn(`[telegram-oversight] ignoring unauthorized chat ${chatId}`);
+                return;
+            }
+            const rawText = typeof message.text === 'string' ? message.text.trim() : '';
+            if (!rawText.startsWith('/')) {
+                await input.sendMessage(chatId, 'Use /help for available commands.');
+                return;
+            }
+            const command = normalizeTelegramCommand(rawText, botUsername ?? null);
+            const response = await dispatchCommand({
+                command,
+                updateId: update.update_id,
+                chatId,
+                user: message.from ?? null,
+                readController: input.readController,
+                commandController: input.commandController
+            });
+            await input.sendMessage(chatId, response);
+        }
+    };
+}
+async function dispatchCommand(input) {
+    const readResponse = await input.readController.dispatchReadCommand(input.command);
+    if (readResponse !== null) {
+        return readResponse;
+    }
+    const mutatingResponse = await input.commandController.dispatchMutatingCommand({
+        command: input.command,
+        updateId: input.updateId,
+        chatId: input.chatId,
+        user: input.user
+    });
+    if (mutatingResponse !== null) {
+        return mutatingResponse;
+    }
+    return 'Unknown command. Use /help for commands.';
+}
+function normalizeTelegramCommand(input, botUsername) {
+    const token = input.trim().split(/\s+/, 1)[0] ?? '';
+    const normalized = token.toLowerCase();
+    if (!normalized.startsWith('/')) {
+        return normalized;
+    }
+    const atIndex = normalized.indexOf('@');
+    if (atIndex === -1) {
+        return normalized;
+    }
+    const suffix = normalized.slice(atIndex + 1);
+    if (!botUsername || suffix === botUsername.toLowerCase()) {
+        return normalized.slice(0, atIndex);
+    }
+    return normalized;
+}