@foxden-app/foxclaw 0.2.0

package/dist/telegram/media.js

@@ -0,0 +1,180 @@
+import path from 'node:path';
+export const TELEGRAM_INBOX_DIR = '.telegram-inbox';
+export const TELEGRAM_BOT_API_DOWNLOAD_LIMIT_BYTES = 20 * 1024 * 1024;
+const FALLBACK_EXTENSION_BY_KIND = {
+    photo: '.jpg',
+    document: '',
+    audio: '.mp3',
+    voice: '.ogg',
+    video: '.mp4',
+    animation: '.mp4',
+    sticker: '.webp',
+    videoNote: '.mp4',
+};
+const MIME_EXTENSION_MAP = {
+    'application/gzip': '.gz',
+    'application/json': '.json',
+    'application/pdf': '.pdf',
+    'application/zip': '.zip',
+    'audio/mpeg': '.mp3',
+    'audio/mp4': '.m4a',
+    'audio/ogg': '.ogg',
+    'audio/wav': '.wav',
+    'image/gif': '.gif',
+    'image/jpeg': '.jpg',
+    'image/png': '.png',
+    'image/webp': '.webp',
+    'text/csv': '.csv',
+    'text/html': '.html',
+    'text/markdown': '.md',
+    'text/plain': '.txt',
+    'video/mp4': '.mp4',
+    'video/quicktime': '.mov',
+};
+export function isNativeImageAttachment(attachment) {
+    if (attachment.kind === 'photo') {
+        return true;
+    }
+    if (attachment.kind === 'sticker') {
+        return !attachment.isAnimated && !attachment.isVideo;
+    }
+    if (attachment.kind !== 'document') {
+        return false;
+    }
+    const lowerMime = attachment.mimeType?.toLowerCase() ?? '';
+    if (lowerMime === 'image/jpeg' || lowerMime === 'image/png' || lowerMime === 'image/webp' || lowerMime === 'image/gif') {
+        return true;
+    }
+    const extension = extensionFromName(attachment.fileName);
+    return extension === '.jpg' || extension === '.jpeg' || extension === '.png' || extension === '.webp' || extension === '.gif';
+}
+export function planAttachmentStoragePath(cwd, threadId, attachment, remoteFilePath, now = new Date()) {
+    const dateSegment = now.toISOString().slice(0, 10);
+    const threadSegment = sanitizePathSegment(threadId);
+    const timestamp = now.toISOString().slice(0, 19).replace(/[-:]/g, '').replace('T', '-');
+    const resolvedFileName = resolveAttachmentFileName(attachment, remoteFilePath);
+    const uniquePrefix = `${timestamp}-${sanitizePathSegment(attachment.fileUniqueId).slice(0, 16)}`;
+    const joinedName = truncateFileName(`${uniquePrefix}-${resolvedFileName}`, 160);
+    const relativePath = path.join(TELEGRAM_INBOX_DIR, dateSegment, threadSegment, joinedName);
+    return {
+        fileName: resolvedFileName,
+        localPath: path.resolve(cwd, relativePath),
+        relativePath,
+    };
+}
+export function buildAttachmentPrompt(userText, attachments) {
+    const normalizedText = userText.trim();
+    const lines = [];
+    if (normalizedText) {
+        lines.push(normalizedText, '');
+    }
+    else {
+        lines.push('User sent Telegram attachments without a caption.', '');
+    }
+    lines.push('Telegram attachments:');
+    attachments.forEach((attachment, index) => {
+        lines.push(`${index + 1}. ${describeAttachment(attachment)}`);
+        lines.push(`   filename: ${attachment.fileName}`);
+        lines.push(`   path: ${attachment.localPath}`);
+        if (attachment.mimeType)
+            lines.push(`   mime: ${attachment.mimeType}`);
+        if (attachment.fileSize !== null)
+            lines.push(`   size_bytes: ${attachment.fileSize}`);
+        if (attachment.width !== null && attachment.height !== null) {
+            lines.push(`   dimensions: ${attachment.width}x${attachment.height}`);
+        }
+        if (attachment.durationSeconds !== null) {
+            lines.push(`   duration_seconds: ${attachment.durationSeconds}`);
+        }
+        if (attachment.nativeImage) {
+            lines.push('   attached_as: localImage');
+        }
+    });
+    lines.push('', 'Use the local file paths above when you inspect these attachments.');
+    return lines.join('\n');
+}
+export function summarizeTelegramInput(text, attachments) {
+    const lines = [];
+    const normalizedText = text.trim();
+    if (normalizedText) {
+        lines.push(normalizedText);
+    }
+    if (attachments.length > 0) {
+        lines.push(`[attachments: ${attachments.map((attachment) => `${attachment.kind}:${attachment.fileName ?? attachment.fileUniqueId}`).join(', ')}]`);
+    }
+    return truncateSummary(lines.join(' '), 500);
+}
+function resolveAttachmentFileName(attachment, remoteFilePath) {
+    const providedName = attachment.fileName ? path.basename(attachment.fileName) : '';
+    const remoteName = remoteFilePath ? path.basename(remoteFilePath) : '';
+    const baseCandidate = providedName || remoteName || `${attachment.kind}-${attachment.fileUniqueId}`;
+    const sanitizedBase = sanitizeFileName(baseCandidate);
+    const extension = extensionFromName(sanitizedBase)
+        || extensionFromName(remoteName)
+        || extensionFromMimeType(attachment.mimeType)
+        || fallbackExtensionByKind(attachment.kind);
+    if (!extension) {
+        return sanitizedBase;
+    }
+    const withoutExtension = sanitizedBase.slice(0, sanitizedBase.length - extensionFromName(sanitizedBase).length) || `${attachment.kind}-${attachment.fileUniqueId}`;
+    return truncateFileName(`${withoutExtension}${extension}`, 120);
+}
+function describeAttachment(attachment) {
+    switch (attachment.kind) {
+        case 'photo':
+            return 'photo';
+        case 'document':
+            return 'document';
+        case 'audio':
+            return 'audio file';
+        case 'voice':
+            return 'voice message';
+        case 'video':
+            return 'video';
+        case 'animation':
+            return 'animation';
+        case 'sticker':
+            return attachment.isAnimated || attachment.isVideo ? 'animated sticker' : 'sticker';
+        case 'videoNote':
+            return 'video note';
+    }
+}
+function sanitizeFileName(fileName) {
+    const trimmed = fileName.trim().replace(/[\\/]+/g, '-');
+    const sanitized = trimmed
+        .replace(/[^\w.\-()+@]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^\.+/, '')
+        .replace(/^-+/, '')
+        .replace(/[.-]+$/, '');
+    return sanitized || 'attachment';
+}
+function sanitizePathSegment(value) {
+    return value.replace(/[^\w.-]+/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '') || 'thread';
+}
+function extensionFromMimeType(mimeType) {
+    if (!mimeType)
+        return '';
+    return MIME_EXTENSION_MAP[mimeType.toLowerCase()] ?? '';
+}
+function extensionFromName(fileName) {
+    if (!fileName)
+        return '';
+    const extension = path.extname(fileName).toLowerCase();
+    return extension === '.' ? '' : extension;
+}
+function truncateFileName(fileName, maxLength) {
+    if (fileName.length <= maxLength)
+        return fileName;
+    const extension = extensionFromName(fileName);
+    const base = extension ? fileName.slice(0, -extension.length) : fileName;
+    return `${base.slice(0, Math.max(1, maxLength - extension.length))}${extension}`;
+}
+function truncateSummary(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return `${text.slice(0, maxLength - 3)}...`;
+}
+function fallbackExtensionByKind(kind) {
+    return FALLBACK_EXTENSION_BY_KIND[kind] ?? '';
+}

package/dist/telegram/rendering.d.ts

@@ -0,0 +1,10 @@
+export type TelegramConversationKind = 'private_chat' | 'private_topic' | 'group_chat' | 'group_topic';
+export type TelegramRendererKind = 'draft_stream' | 'segmented_stream';
+export interface TelegramRenderRoute {
+    conversationKind: TelegramConversationKind;
+    preferredRenderer: TelegramRendererKind;
+    currentRenderer: TelegramRendererKind;
+    supportsDraftStreaming: boolean;
+    usesMessageThread: boolean;
+}
+export declare function resolveTelegramRenderRoute(chatType: string, topicId: number | null): TelegramRenderRoute;

package/dist/telegram/rendering.js

@@ -0,0 +1,21 @@
+export function resolveTelegramRenderRoute(chatType, topicId) {
+    const conversationKind = resolveTelegramConversationKind(chatType, topicId);
+    const supportsDraftStreaming = chatType === 'private';
+    const preferredRenderer = 'segmented_stream';
+    return {
+        conversationKind,
+        // Telegram draft updates are available in private chats, but segmented live messages
+        // are the more stable default because they do not overwrite visible partial output.
+        preferredRenderer,
+        currentRenderer: preferredRenderer,
+        supportsDraftStreaming,
+        usesMessageThread: topicId !== null,
+    };
+}
+function resolveTelegramConversationKind(chatType, topicId) {
+    const isPrivate = chatType === 'private';
+    if (isPrivate) {
+        return topicId === null ? 'private_chat' : 'private_topic';
+    }
+    return topicId === null ? 'group_chat' : 'group_topic';
+}

package/dist/telegram/scope.d.ts

@@ -0,0 +1,6 @@
+export interface TelegramScope {
+    chatId: string;
+    topicId: number | null;
+}
+export declare function createTelegramScopeId(chatId: string, topicId: number | null): string;
+export declare function parseTelegramScopeId(scopeId: string): TelegramScope;

package/dist/telegram/scope.js

@@ -0,0 +1,24 @@
+const ROOT_TOPIC_KEY = 'root';
+const SCOPE_SEPARATOR = '::';
+export function createTelegramScopeId(chatId, topicId) {
+    return `${chatId}${SCOPE_SEPARATOR}${topicId ?? ROOT_TOPIC_KEY}`;
+}
+export function parseTelegramScopeId(scopeId) {
+    const separatorIndex = scopeId.lastIndexOf(SCOPE_SEPARATOR);
+    if (separatorIndex === -1) {
+        return { chatId: scopeId, topicId: null };
+    }
+    const chatId = scopeId.slice(0, separatorIndex);
+    const topicPart = scopeId.slice(separatorIndex + SCOPE_SEPARATOR.length);
+    if (!chatId) {
+        throw new Error(`Invalid Telegram scope id: ${scopeId}`);
+    }
+    if (topicPart === ROOT_TOPIC_KEY || topicPart === '') {
+        return { chatId, topicId: null };
+    }
+    const topicId = Number.parseInt(topicPart, 10);
+    if (!Number.isFinite(topicId)) {
+        throw new Error(`Invalid Telegram topic id in scope: ${scopeId}`);
+    }
+    return { chatId, topicId };
+}

package/dist/telegram/text.d.ts

@@ -0,0 +1,7 @@
+export declare const TELEGRAM_MESSAGE_LIMIT = 4000;
+export declare const TELEGRAM_STREAM_MESSAGE_LIMIT = 1200;
+export declare const TELEGRAM_DRAFT_LIMIT = 4000;
+export declare function sanitizeTelegramPreview(text: string): string;
+export declare function chunkTelegramMessage(text: string, limit?: number, fallbackText?: string): string[];
+export declare function chunkTelegramStreamMessage(text: string, limit?: number): string[];
+export declare function clipTelegramDraftMessage(text: string, fallbackText?: string): string;

package/dist/telegram/text.js

@@ -0,0 +1,47 @@
+export const TELEGRAM_MESSAGE_LIMIT = 4000;
+export const TELEGRAM_STREAM_MESSAGE_LIMIT = 1200;
+export const TELEGRAM_DRAFT_LIMIT = 4000;
+export function sanitizeTelegramPreview(text) {
+    if (!text.trim())
+        return 'Working...';
+    return text.length > TELEGRAM_MESSAGE_LIMIT
+        ? `${text.slice(0, TELEGRAM_MESSAGE_LIMIT - 3)}...`
+        : text;
+}
+export function chunkTelegramMessage(text, limit = TELEGRAM_MESSAGE_LIMIT, 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 chunkTelegramStreamMessage(text, limit = TELEGRAM_STREAM_MESSAGE_LIMIT) {
+    return chunkTelegramMessage(text, limit, '');
+}
+export function clipTelegramDraftMessage(text, fallbackText = 'Thinking...') {
+    const source = text.trim() ? text : fallbackText;
+    if (source.length <= TELEGRAM_DRAFT_LIMIT) {
+        return source;
+    }
+    return `${source.slice(0, TELEGRAM_DRAFT_LIMIT - 1)}…`;
+}

package/dist/types.d.ts

@@ -0,0 +1,343 @@
+/** Session row: `chatId` holds the bridge scope id (e.g. `telegram:…`). */
+export interface ThreadBinding {
+    chatId: string;
+    threadId: string;
+    cwd: string | null;
+    updatedAt: number;
+}
+export type AppLocale = 'en' | 'zh';
+export type ApprovalPolicyValue = 'on-request' | 'on-failure' | 'never' | 'untrusted';
+export type SandboxModeValue = 'read-only' | 'workspace-write' | 'danger-full-access';
+export type AccessPresetValue = 'read-only' | 'default' | 'full-access';
+export type CollaborationModeValue = 'default' | 'plan';
+export type ActiveTurnMessageMode = 'steer' | 'queue';
+export type ReasoningEffortValue = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+export type ThreadStatusKind = 'active' | 'idle' | 'notLoaded' | 'systemError';
+export interface ChatSessionSettings {
+    /** Bridge scope id (e.g. `telegram:…`). */
+    chatId: string;
+    model: string | null;
+    reasoningEffort: ReasoningEffortValue | null;
+    locale: AppLocale | null;
+    accessPreset: AccessPresetValue | null;
+    collaborationMode: CollaborationModeValue | null;
+    serviceTier: string | null;
+    activeTurnMessageMode: ActiveTurnMessageMode | null;
+    updatedAt: number;
+}
+export interface CachedThread {
+    index: number;
+    threadId: string;
+    name: string | null;
+    preview: string;
+    cwd: string | null;
+    modelProvider: string | null;
+    status: ThreadStatusKind;
+    archived: boolean;
+    updatedAt: number;
+}
+export interface AppThread {
+    threadId: string;
+    name: string | null;
+    preview: string;
+    cwd: string | null;
+    modelProvider: string | null;
+    source: string | null;
+    path: string | null;
+    status: ThreadStatusKind;
+    updatedAt: number;
+}
+export interface AppTurnItemSnapshot {
+    itemId: string;
+    type: string;
+    phase: string | null;
+    text: string | null;
+    command: string | null;
+    status: string | null;
+    aggregatedOutput: string | null;
+}
+export interface AppTurnSnapshot {
+    turnId: string;
+    status: string;
+    error: string | null;
+    items: AppTurnItemSnapshot[];
+    itemsView?: string | null;
+    startedAt?: number | null;
+    completedAt?: number | null;
+    durationMs?: number | null;
+}
+export interface AppThreadSnapshot extends AppThread {
+    activeFlags: string[];
+    turns: AppTurnSnapshot[];
+}
+export interface ThreadSessionState {
+    thread: AppThread;
+    model: string;
+    modelProvider: string;
+    reasoningEffort: ReasoningEffortValue | null;
+    cwd: string;
+}
+export interface CodexAccountInfo {
+    type: string;
+    email: string | null;
+    planType: string | null;
+    requiresOpenaiAuth: boolean;
+}
+export interface CodexRateLimitWindow {
+    usedPercent: number;
+    windowDurationMins: number | null;
+    resetsAt: number | null;
+}
+export interface CodexCreditsSnapshot {
+    hasCredits: boolean;
+    unlimited: boolean;
+    balance: string | null;
+}
+export interface CodexRateLimitSnapshot {
+    limitId: string | null;
+    limitName: string | null;
+    primary: CodexRateLimitWindow | null;
+    secondary: CodexRateLimitWindow | null;
+    credits: CodexCreditsSnapshot | null;
+    planType: string | null;
+    rateLimitReachedType: string | null;
+}
+export interface CodexAccountRateLimits {
+    rateLimits: CodexRateLimitSnapshot | null;
+    rateLimitsByLimitId: Record<string, CodexRateLimitSnapshot> | null;
+}
+export interface CodexLoginDeviceCode {
+    type: 'chatgptDeviceCode';
+    loginId: string;
+    verificationUrl: string;
+    userCode: string;
+}
+export interface CodexSkillMetadata {
+    name: string;
+    description: string;
+    shortDescription: string | null;
+    path: string;
+    scope: string;
+    enabled: boolean;
+    displayName: string | null;
+    defaultPrompt: string | null;
+}
+export interface CodexSkillsListEntry {
+    cwd: string;
+    skills: CodexSkillMetadata[];
+    errors: string[];
+}
+export interface CodexMcpServerStatus {
+    name: string;
+    authStatus: string;
+    toolNames: string[];
+    resourceUris: string[];
+    resourceTemplateUris: string[];
+}
+export interface CodexMcpResourceContent {
+    type: string;
+    text: string | null;
+    blob: string | null;
+    mimeType: string | null;
+    uri: string | null;
+}
+export interface CodexHookMetadata {
+    key: string;
+    eventName: string;
+    handlerType: string;
+    enabled: boolean;
+    trustStatus: string;
+    sourcePath: string;
+    pluginId: string | null;
+    command: string | null;
+    statusMessage: string | null;
+}
+export interface CodexHooksListEntry {
+    cwd: string;
+    hooks: CodexHookMetadata[];
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+    warnings: string[];
+}
+export interface CodexPluginSummary {
+    id: string;
+    name: string;
+    enabled: boolean;
+    installed: boolean;
+    source: string;
+    availability: string;
+    authPolicy: string;
+    installPolicy: string;
+    keywords: string[];
+}
+export interface CodexPluginMarketplace {
+    name: string;
+    displayName: string | null;
+    path: string | null;
+    plugins: CodexPluginSummary[];
+}
+export interface CodexPluginSkillSummary {
+    name: string;
+    description: string;
+    shortDescription: string | null;
+    enabled: boolean;
+    path: string | null;
+}
+export interface CodexPluginDetail {
+    marketplaceName: string;
+    marketplacePath: string | null;
+    summary: CodexPluginSummary;
+    description: string | null;
+    skills: CodexPluginSkillSummary[];
+    hooks: Array<{
+        key: string;
+        eventName: string;
+    }>;
+    apps: Array<{
+        id: string;
+        name: string;
+        description: string | null;
+        needsAuth: boolean;
+    }>;
+    mcpServers: string[];
+}
+export interface CodexAppInfo {
+    id: string;
+    name: string;
+    description: string | null;
+    isEnabled: boolean;
+    isAccessible: boolean;
+    installUrl: string | null;
+    distributionChannel: string | null;
+    pluginDisplayNames: string[];
+}
+export interface CodexExperimentalFeature {
+    name: string;
+    displayName: string | null;
+    enabled: boolean;
+    defaultEnabled: boolean;
+    stage: string;
+    description: string | null;
+}
+export interface CodexConfigRequirements {
+    allowedApprovalPolicies: string[] | null;
+    allowedSandboxModes: string[] | null;
+    allowedWebSearchModes: string[] | null;
+    enforceResidency: string | null;
+    featureRequirements: Record<string, boolean> | null;
+}
+export interface CodexModelProviderCapabilities {
+    webSearch: boolean;
+    imageGeneration: boolean;
+    namespaceTools: boolean;
+}
+export type ThreadGoalStatusValue = 'active' | 'paused' | 'budgetLimited' | 'complete';
+export interface CodexThreadGoal {
+    threadId: string;
+    objective: string;
+    status: ThreadGoalStatusValue;
+    tokenBudget: number | null;
+    tokensUsed: number;
+    timeUsedSeconds: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface CodexFuzzyFileResult {
+    root: string;
+    path: string;
+    matchType: string;
+    fileName: string;
+    score: number;
+}
+export type ReviewTarget = {
+    type: 'uncommittedChanges';
+} | {
+    type: 'baseBranch';
+    branch: string;
+} | {
+    type: 'commit';
+    sha: string;
+    title: string | null;
+} | {
+    type: 'custom';
+    instructions: string;
+};
+export interface CodexEffectiveConfig {
+    model: string | null;
+    modelReasoningEffort: ReasoningEffortValue | null;
+    planModeReasoningEffort: ReasoningEffortValue | null;
+    developerInstructions: string | null;
+}
+export interface CodexCollaborationModePreset {
+    name: string;
+    mode: CollaborationModeValue | null;
+    model: string | null;
+    reasoningEffort: ReasoningEffortValue | null;
+}
+export interface CodexCollaborationMode {
+    mode: CollaborationModeValue;
+    settings: {
+        model: string;
+        reasoning_effort: ReasoningEffortValue | null;
+        developer_instructions: string | null;
+    };
+}
+export interface ModelInfo {
+    id: string;
+    model: string;
+    displayName: string;
+    description: string;
+    isDefault: boolean;
+    supportedReasoningEfforts: ReasoningEffortValue[];
+    defaultReasoningEffort: ReasoningEffortValue;
+    serviceTiers: ModelServiceTier[];
+}
+export interface ModelServiceTier {
+    id: string;
+    name: string;
+    description: string;
+}
+export type ApprovalKind = 'command' | 'fileChange' | 'permissions';
+export interface PendingApprovalRecord {
+    localId: string;
+    serverRequestId: string;
+    kind: ApprovalKind;
+    /** Bridge scope id (e.g. `telegram:…`). */
+    chatId: string;
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    approvalId: string | null;
+    reason: string | null;
+    command: string | null;
+    cwd: string | null;
+    payloadJson: string | null;
+    messageId: number | null;
+    createdAt: number;
+    resolvedAt: number | null;
+}
+export interface RuntimeStatus {
+    running: boolean;
+    connected: boolean;
+    userAgent: string | null;
+    codexAppServer?: {
+        pid: number | null;
+        port: number | null;
+        running: boolean;
+        managed: boolean;
+    };
+    botUsername: string | null;
+    currentBindings: number;
+    pendingApprovals: number;
+    pendingUserInputs: number;
+    activeTurns: number;
+    lastError: string | null;
+    updatedAt: string;
+    /** Which messaging transports are expected active in this process. */
+    channels?: {
+        telegram: boolean;
+        weixin: boolean;
+    };
+}

package/dist/types.js

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