@foxden-app/foxclaw 0.12.0 → 0.13.0

package/dist/core/backend_ui.d.ts

@@ -0,0 +1,28 @@
+import type { AppLocale } from '../types.js';
+import type { ChannelTextEvent, ChannelCallbackEvent } from '../core/channel_events.js';
+import type { ChannelInlineKeyboard } from '../core/channel_port.js';
+import type { BackendDescriptor } from './engine_spi.js';
+/** Operations a backend panel can request without depending on the orchestrator implementation. */
+export interface BackendUiHost {
+    sendMessage(scopeId: string, text: string, keyboard?: ChannelInlineKeyboard): Promise<number>;
+    editMessage(scopeId: string, messageId: number, text: string, keyboard?: ChannelInlineKeyboard): Promise<void>;
+    scheduleStalePanelDeletion(scopeId: string, messageId: number): void;
+    hasActiveTurn(scopeId: string): boolean;
+    syncCurrentBackendSettings(scopeId: string): void;
+    getBackendDescriptorForScope(scopeId: string): BackendDescriptor;
+}
+export interface EngineCustomUiHook {
+    renderSetupMenu?(scopeId: string, locale: AppLocale, messageId?: number): Promise<boolean>;
+    renderModelsMenu?(scopeId: string, locale: AppLocale, messageId?: number): Promise<boolean>;
+    renderCustomStatus?(scopeId: string, locale: AppLocale): Promise<string | null>;
+    renderCustomSetupRows?(scopeId: string, locale: AppLocale): Promise<ChannelInlineKeyboard>;
+    handleCustomCallback?(scopeId: string, data: string, locale: AppLocale, messageId?: number, event?: ChannelCallbackEvent): Promise<boolean>;
+    handleCustomCommand?(scopeId: string, command: string, args: string, locale: AppLocale, event?: ChannelTextEvent): Promise<boolean>;
+    handleCustomInbound?(event: ChannelTextEvent, locale: AppLocale): Promise<boolean>;
+}
+export interface BackendUi extends EngineCustomUiHook {
+    /** Recognize owned buttons even after the user switches to another backend (e.g. pending approvals). */
+    ownsCallback?(data: string): boolean;
+    getPendingApprovals?(): number;
+    stop?(): Promise<void>;
+}

package/dist/core/backend_ui.js

@@ -0,0 +1 @@
+export {};

package/dist/core/channel_events.d.ts

@@ -0,0 +1,48 @@
+import type { InboundAttachment } from './attachment_types.js';
+export interface ChannelMessageEntity {
+    type: string;
+    offset: number;
+    length: number;
+    user?: {
+        id: number;
+    };
+}
+export interface ChannelTextEvent {
+    chatId: string;
+    topicId: number | null;
+    scopeId: string;
+    chatType: string;
+    userId: string;
+    text: string;
+    messageId: number;
+    mediaGroupId?: string | null;
+    attachments: InboundAttachment[];
+    entities: ChannelMessageEntity[];
+    replyToBot: boolean;
+    languageCode?: string;
+}
+export interface ChannelCallbackEvent {
+    chatId: string;
+    topicId: number | null;
+    scopeId: string;
+    userId: string;
+    data: string;
+    callbackQueryId: string;
+    messageId: number;
+    languageCode?: string;
+}
+/** A transport-correlated stop; generation identifiers never select a task in another scope. */
+export interface ChannelStopEvent {
+    scopeId: string;
+    taskId: string;
+}
+export type ChannelInbound = {
+    kind: 'text';
+    event: ChannelTextEvent;
+} | {
+    kind: 'callback';
+    event: ChannelCallbackEvent;
+} | {
+    kind: 'stop';
+    event: ChannelStopEvent;
+};

package/dist/core/channel_events.js

@@ -0,0 +1 @@
+export {};

package/dist/core/channel_port.d.ts

@@ -1,15 +1,59 @@
-/**
- * Opaque outbound message handle for the active UI surface (Telegram message id, Weixin id, etc.).
- */
-export type ChannelMessageRef = number | string;
+import type { AppConfig } from '../config.js';
+import type { AppLocale } from '../types.js';
+import type { ChannelTextEvent, ChannelCallbackEvent, ChannelInbound } from './channel_events.js';
+import type { ParsedCommand } from '../controller/commands.js';
+import type { AttachmentDownloader } from './attachments.js';
+/** Bridge-local handles; a transport maps these to its native message identifiers. */
+export type ChannelMessageRef = number;
 export type ChannelInlineKeyboard = Array<Array<{
     text: string;
     callback_data: string;
 }>>;
-/**
- * Future: channel-agnostic outbound surface. Telegram uses {@link TelegramMessagingPort} today.
- */
-export interface ChannelPort {
+export type InboundAddressing = {
+    kind: 'ignore';
+} | {
+    kind: 'prompt';
+    text: string;
+} | {
+    kind: 'command';
+    command: ParsedCommand;
+};
+/** Presentation and file transport contract. Native addressing and interaction live in channels. */
+export interface ChannelPort extends AttachmentDownloader {
+    readonly capabilities?: {
+        editableMessages: boolean;
+        inlineActions: boolean;
+        maxMessageLength: number;
+    };
+    resolveIncoming?(event: ChannelTextEvent, config: AppConfig, username?: string | null): InboundAddressing;
+    setScopeCommands?(scopeId: string, commands: Array<{
+        command: string;
+        description: string;
+    }>): Promise<void>;
+    beginTaskPreview?(scopeId: string, taskId: string, text: string, reuseMessageId?: number): Promise<number>;
+    updateTaskPreview?(scopeId: string, taskId: string, messageId: number, html: string): Promise<number>;
+    endTaskPreview?(scopeId: string, taskId: string): Promise<void>;
+    resolveAction?(event: ChannelTextEvent): ChannelCallbackEvent | null;
+    editPlain(scopeId: string, messageId: ChannelMessageRef, text: string, keyboard?: ChannelInlineKeyboard): Promise<void>;
     sendPlain(scopeId: string, text: string, keyboard?: ChannelInlineKeyboard): Promise<ChannelMessageRef>;
     sendHtml(scopeId: string, text: string, keyboard?: ChannelInlineKeyboard): Promise<ChannelMessageRef>;
+    sendRichMarkdown(scopeId: string, text: string, keyboard?: ChannelInlineKeyboard): Promise<ChannelMessageRef>;
+    editRichMarkdown(scopeId: string, messageId: ChannelMessageRef, text: string, keyboard?: ChannelInlineKeyboard): Promise<void>;
+    deleteMessage(scopeId: string, messageId: ChannelMessageRef): Promise<void>;
+    sendTypingInScope(scopeId: string): Promise<void>;
+    answerCallback(callbackId: string, text: string): Promise<void>;
+}
+export interface ChannelGateway {
+    setInboundConsumer?(consumer: (id: string, inbound: ChannelInbound) => Promise<void>): () => void;
+    readonly username?: string | null;
+    on(event: 'text', listener: (event: ChannelTextEvent) => void): unknown;
+    on(event: 'callback', listener: (event: ChannelCallbackEvent) => void): unknown;
+    off?(event: 'text' | 'callback', listener: (...args: any[]) => void): unknown;
+    start(): Promise<void>;
+    stop(): void | Promise<void>;
+}
+export interface ChannelCommand {
+    command: string;
+    description: string;
 }
+export type ChannelCommandProvider = (locale: AppLocale) => ChannelCommand[];

package/dist/core/engine_spi.d.ts

@@ -1,21 +1,24 @@
-import type { StagedTelegramAttachment } from '../telegram/media.js';
-import type { AppLocale } from '../types.js';
+import type { StagedAttachment } from './attachment_types.js';
+import type { AppLocale, AccessPresetValue } from '../types.js';
+import type { BackendUi, BackendUiHost } from './backend_ui.js';
 export interface EngineModel {
     id: string;
     name: string;
     description?: string | undefined;
     isDefault?: boolean | undefined;
+    supportedReasoningEfforts?: string[] | undefined;
 }
 export interface EngineTurnRequest {
     scopeId: string;
     prompt: string;
-    stagedAttachments?: StagedTelegramAttachment[] | undefined;
+    stagedAttachments?: StagedAttachment[] | undefined;
     threadId: string | null;
     cwd: string;
     model: string;
     effort?: string | null | undefined;
     serviceTier?: string | null | undefined;
     locale: AppLocale;
+    accessPreset?: AccessPresetValue | undefined;
 }
 export interface EngineToolEvent {
     name: string;
@@ -40,7 +43,8 @@ export interface EngineTurnResult {
 }
 export interface EngineTurnExecution {
     turnId?: string | undefined;
-    cancel(): void;
+    /** A returned promise resolves after the native backend has released the turn. */
+    cancel(): void | Promise<void>;
     waitForResult(): Promise<EngineTurnResult | null>;
     on(event: 'delta', listener: (text: string) => void): void;
     on(event: 'tool', listener: (tool: EngineToolEvent) => void): void;
@@ -74,4 +78,15 @@ export interface BackendDescriptor {
     details?: string | undefined;
     isDefault?: boolean | undefined;
     onSelect?: (scopeId: string) => Promise<void>;
+    defaults?: {
+        reasoningEffort: string | null;
+        supportedReasoningEfforts: readonly string[];
+        boost: boolean;
+        tokenUsage: boolean;
+    };
+    commands?: (locale: AppLocale) => Array<{
+        command: string;
+        description: string;
+    }>;
+    createUi?: (host: BackendUiHost) => BackendUi;
 }

package/dist/core/listener_scope.d.ts

@@ -0,0 +1,11 @@
+interface EventSource {
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    off?(event: string, listener: (...args: any[]) => void): unknown;
+}
+/** Ownership of subscriptions is separate from ownership of the shared transport. */
+export declare class ListenerScope {
+    private readonly cleanup;
+    listen(source: EventSource, event: string, listener: (...args: any[]) => void): void;
+    clear(): void;
+}
+export {};

package/dist/core/listener_scope.js

@@ -0,0 +1,10 @@
+/** Ownership of subscriptions is separate from ownership of the shared transport. */
+export class ListenerScope {
+    cleanup = [];
+    listen(source, event, listener) {
+        source.on(event, listener);
+        this.cleanup.push(() => source.off?.(event, listener));
+    }
+    clear() { for (const stop of this.cleanup.splice(0).reverse())
+        stop(); }
+}

package/dist/core/message_text.d.ts

@@ -0,0 +1,2 @@
+export declare function chunkMessage(text: string, limit?: number, fallbackText?: string): string[];
+export declare function escapeHtml(text: string): string;

package/dist/core/message_text.js

@@ -0,0 +1,28 @@
+export function chunkMessage(text, limit = 4000, fallbackText = 'Completed.') {
+    const source = text.trim() ? text : fallbackText;
+    if (!source) {
+        return [];
+    }
+    if (source.length <= limit) {
+        return [source];
+    }
+    const chunks = [];
+    let start = 0;
+    while (start < source.length) {
+        const remaining = source.length - start;
+        if (remaining <= limit) {
+            chunks.push(source.slice(start));
+            break;
+        }
+        const tentativeEnd = start + limit;
+        const window = source.slice(start, tentativeEnd);
+        const splitAt = Math.max(window.lastIndexOf('\n\n'), window.lastIndexOf('\n'));
+        const end = splitAt >= Math.floor(limit / 2)
+            ? start + splitAt + 1
+            : tentativeEnd;
+        chunks.push(source.slice(start, end));
+        start = end;
+    }
+    return chunks.filter(chunk => chunk.length > 0);
+}
+export function escapeHtml(text) { return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;'); }

package/dist/core/network_errors.d.ts

@@ -0,0 +1 @@
+export declare function isTransientNetworkError(err: unknown): boolean;

package/dist/core/network_errors.js

@@ -0,0 +1,23 @@
+export function isTransientNetworkError(err) {
+    if (!err)
+        return false;
+    const msg = String(err.message || err).toLowerCase();
+    return (msg.includes('client network socket disconnected') ||
+        msg.includes('econnreset') ||
+        msg.includes('etimedout') ||
+        msg.includes('eai_again') ||
+        msg.includes('enotfound') ||
+        msg.includes('econnrefused') ||
+        msg.includes('socket hang up') ||
+        msg.includes('timed out') ||
+        msg.includes('timeout') ||
+        msg.includes('network socket disconnected') ||
+        msg.includes('network error') ||
+        msg.includes('fetch failed') ||
+        msg.includes('und_err_') ||
+        msg.includes('read tcp') ||
+        msg.includes('connection timed out') ||
+        msg.includes('broken pipe') ||
+        msg.includes('ehostunreach') ||
+        msg.includes('enetunreach'));
+}

package/dist/core/orchestrator.d.ts

@@ -2,9 +2,10 @@ import type { AppConfig } from '../config.js';
 import type { BridgeStore } from '../store/database.js';
 import type { Logger } from '../logger.js';
 import type { AppLocale } from '../types.js';
-import type { TelegramGateway, TelegramTextEvent, TelegramCallbackEvent } from '../telegram/gateway.js';
-import type { TelegramMessagingPort, InlineKeyboard } from '../channels/telegram/telegram_messaging_port.js';
-import { TurnQueueManager } from './turn_queue.js';
+import type { ChannelGateway, ChannelPort, ChannelInlineKeyboard } from './channel_port.js';
+import type { ChannelTextEvent, ChannelCallbackEvent } from './channel_events.js';
+import type { EngineCustomUiHook } from './backend_ui.js';
+export type { EngineCustomUiHook } from './backend_ui.js';
 import type { IEngineAdapter, EngineTurnExecution, BackendDescriptor } from './engine_spi.js';
 export declare const STREAM_THROTTLE_MS = 700;
 export declare const TYPING_INTERVAL_MS = 4000;
@@ -23,25 +24,24 @@ export interface UnifiedActiveTurn {
     currentTool?: string | null;
     suppressQueueDrain?: boolean;
     startTime: number;
-}
-export interface EngineCustomUiHook {
-    renderSetupMenu?(scopeId: string, locale: AppLocale, messageId?: number): Promise<boolean>;
-    renderModelsMenu?(scopeId: string, locale: AppLocale, messageId?: number): Promise<boolean>;
-    renderCustomStatus?(scopeId: string, locale: AppLocale): Promise<string | null>;
-    renderCustomSetupRows?(scopeId: string, locale: AppLocale): Promise<InlineKeyboard>;
-    handleCustomCallback?(scopeId: string, data: string, locale: AppLocale, messageId?: number, event?: TelegramCallbackEvent): Promise<boolean>;
-    handleCustomCommand?(scopeId: string, command: string, args: string, locale: AppLocale, event?: TelegramTextEvent): Promise<boolean>;
-    handleCustomInbound?(event: TelegramTextEvent, locale: AppLocale): Promise<boolean>;
+    previewKey: string;
+    queueId?: string | undefined;
+    taskId: string;
+    settling?: boolean;
 }
 export declare class UnifiedChannelOrchestrator {
     readonly config: AppConfig;
     readonly store: BridgeStore;
     readonly logger: Logger;
-    readonly bot: TelegramGateway;
-    readonly messaging: TelegramMessagingPort;
-    readonly queueManager: TurnQueueManager;
+    readonly bot: ChannelGateway;
+    readonly messaging: ChannelPort;
     readonly customUi?: EngineCustomUiHook | undefined;
     private readonly backends;
+    private readonly scopeOperations;
+    private readonly messageOperations;
+    private readonly settlements;
+    private stopped;
+    private readonly serviceUi?;
     private readonly defaultBackendId;
     private readonly activeTurns;
     private readonly stalePanelDeleteTimers;
@@ -53,15 +53,16 @@ export declare class UnifiedChannelOrchestrator {
         config: AppConfig;
         store: BridgeStore;
         logger: Logger;
-        bot: TelegramGateway;
+        bot: ChannelGateway;
         adapter?: IEngineAdapter;
         adapters?: Map<string, IEngineAdapter> | IEngineAdapter[];
         backends?: BackendDescriptor[];
         backendProvider?: (() => Promise<BackendDescriptor[]> | BackendDescriptor[]) | undefined;
         defaultBackendId?: string;
         ownsScope?: (scopeId: string) => boolean;
-        messaging: TelegramMessagingPort;
+        messaging: ChannelPort;
         customUi?: EngineCustomUiHook | undefined;
+        serviceUi?: EngineCustomUiHook | undefined;
     });
     getAdapterForScope(scopeId: string): IEngineAdapter;
     getBackendDescriptorForScope(scopeId: string): BackendDescriptor;
@@ -77,32 +78,60 @@ export declare class UnifiedChannelOrchestrator {
         restoredThreadId: string | null;
         cwd: string | null;
     }>;
+    private switchBackendNow;
+    private removeInboundConsumer;
+    private readonly intakeOperations;
+    private receiveInbound;
+    private readonly inboundListeners;
     registerInboundHandlers(): void;
-    dispatchInboundLikeTelegramText(event: TelegramTextEvent): void;
+    dispatchInboundLikeTelegramText(event: ChannelTextEvent): void;
     start(): Promise<void>;
+    private recoveryEvent;
+    private showRecovery;
+    private restoreDurableTasks;
+    private resolveDeliveredTask;
+    private handleRecovery;
+    stopTask(scopeId: string, taskId: string): Promise<boolean>;
+    private cancelActiveTurn;
     stop(): Promise<void>;
+    isIdleForServiceUpdate(): boolean;
+    getPendingApprovals(): number;
     getActiveTurnsCount(): number;
+    ownsScopeId(scopeId: string): boolean;
+    hasExecutingTasks(): boolean;
     hasActiveTurn(scopeId: string): boolean;
-    sendMessage(scopeId: string, text: string, keyboard?: InlineKeyboard): Promise<number>;
-    editMessage(scopeId: string, messageId: number, text: string, keyboard?: InlineKeyboard): Promise<void>;
+    sendMessage(scopeId: string, text: string, keyboard?: ChannelInlineKeyboard): Promise<number>;
+    editMessage(scopeId: string, messageId: number, text: string, keyboard?: ChannelInlineKeyboard): Promise<void>;
+    private trackSettlement;
+    private deliverTaskChunks;
     private safeDeliverChunks;
     private safeDeliverMessage;
-    handleText(event: TelegramTextEvent): Promise<void>;
-    handleCallback(event: TelegramCallbackEvent): Promise<void>;
-    startPromptTurn(event: TelegramTextEvent, prompt: string, locale: AppLocale, options?: {
+    handleText(event: ChannelTextEvent): Promise<void>;
+    handleCallback(event: ChannelCallbackEvent): Promise<void>;
+    private captureTask;
+    private recoveryBlocksScope;
+    startPromptTurn(event: ChannelTextEvent, prompt: string, locale: AppLocale, options?: {
         reuseMessageId?: number | undefined;
         forcedThreadId?: string | undefined;
+        taskId?: string | undefined;
     }): Promise<void>;
+    private startPromptTurnNow;
+    private cancelQueuedWork;
     private enqueuePromptTurn;
     private drainNextQueuedTurn;
     private executeTurn;
+    private supportedEfforts;
     private handleEffortCommand;
     private handleBoostCommand;
     private handleActiveCommand;
     private handleQueueCommand;
+    private handleQueueCommandNow;
     private handleSteerCommand;
+    private handleSteerCommandNow;
     handleInterrupt(scopeId: string, locale: AppLocale): Promise<void>;
-    handleNewSession(scopeId: string, locale: AppLocale, targetCwdInput?: string): Promise<void>;
+    private handleInterruptNow;
+    handleNewSession(scopeId: string, locale: AppLocale, cwdArg?: string): Promise<void>;
+    private handleNewSessionNow;
     sendStatus(scopeId: string, locale: AppLocale): Promise<void>;
     sendSetupMenu(scopeId: string, locale: AppLocale, editMessageId?: number): Promise<void>;
     sendModelsMenu(scopeId: string, locale: AppLocale, editMessageId?: number): Promise<void>;