codeclaw 0.2.3 → 0.2.5

package/README.md

@@ -48,10 +48,12 @@ No server. No Docker. No config files. Just one process bridging Telegram to you
 - **Keep-alive** — OS-level sleep prevention (macOS `caffeinate`, Linux `systemd-inhibit`)
 - **Directory browser** — switch working directory interactively via `/switch` with inline navigation
 - **Image input** — send photos to the bot for visual context (screenshots, diagrams)
+- **Artifact return** — agent can write screenshots/files to a per-turn manifest and codeclaw uploads them back to Telegram
 - **Quick replies** — auto-detects yes/no questions and numbered options, shows inline buttons
 - **Long output** — responses exceeding Telegram limits are split with a full `.md` file attachment
 - **Thinking display** — shows agent thinking/reasoning process in collapsible blocks
 - **Token tracking** — per-turn and cumulative input/output/cached token counts
+- **Provider usage** — `/status` shows recent Codex/Claude usage windows and reset timing when local telemetry is available
 - **Access control** — restrict by chat/user ID whitelist
 - **Startup notice** — sends online status to all known chats on startup
 - **Full access / safe mode** — let the agent run freely, or require confirmation before destructive actions
@@ -144,8 +146,9 @@ Once running, these commands are available in Telegram:
 | `/sessions` | List, switch, or create sessions (paginated inline keyboard) |
 | `/agents` | List installed agents, switch between them |
 | `/switch` | Browse and change working directory (interactive file browser) |
-| `/status` | Bot status: uptime, memory, agent, session, token usage |
+| `/status` | Bot status: uptime, memory, agent, session, provider usage, token usage |
 | `/host` | Host machine info: CPU, memory, disk, top processes |
+| `/restart` | Restart with latest version via `npx --yes codeclaw@latest` |
 | `/start` | Welcome message with command list |
 
 > In private chats, just send text directly — no command prefix needed. Any unrecognized `/command` is forwarded to the agent as a prompt.
@@ -177,9 +180,9 @@ cli.ts → bot-telegram.ts → bot.ts → code-agent.ts
 ```
 
 - **bot.ts** — channel-agnostic business logic, state, streaming bridge
-- **bot-telegram.ts** — Telegram-specific rendering, keyboards, callbacks
-- **channel-telegram.ts** — pure Telegram API transport (polling, sending, file download)
-- **code-agent.ts** — AI agent abstraction (spawn CLI, parse JSONL stream)
+- **bot-telegram.ts** — Telegram-specific rendering, keyboards, callbacks, artifact upload flow
+- **channel-telegram.ts** — pure Telegram API transport (polling, sending, file download/upload routing)
+- **code-agent.ts** — AI agent abstraction (spawn CLI, parse JSONL stream, inspect local usage telemetry)
 
 Adding a new IM channel means creating `channel-xxx.ts` + `bot-xxx.ts` without touching shared logic.
 
@@ -229,10 +232,12 @@ claude / codex CLI
 - **系统保活** — 操作系统级防休眠（macOS `caffeinate`、Linux `systemd-inhibit`）
 - **目录浏览器** — 通过 `/switch` 交互式切换工作目录，内联导航
 - **图片输入** — 向机器人发送图片提供视觉上下文（截图、设计图）
+- **产物回传** — Agent 可按每轮 manifest 写出截图/文件，codeclaw 会自动回传到 Telegram
 - **快捷回复** — 自动检测是/否问题和编号选项，显示内联按钮
 - **长文本处理** — 超出 Telegram 限制的回复自动拆分，并附带完整 `.md` 文件
 - **思考展示** — 在可折叠区块中显示 Agent 的思考/推理过程
 - **Token 统计** — 每轮和累计的输入/输出/缓存 token 计数
+- **Provider 用量** — `/status` 可展示最近的 Codex/Claude 用量窗口和重置时间（本地遥测可用时）
 - **访问控制** — 按聊天/用户 ID 白名单限制
 - **启动通知** — 启动时向所有已知聊天发送在线状态
 - **完全访问 / 安全模式** — 让 AI 自由运行，或限制危险操作需确认
@@ -325,8 +330,9 @@ TELEGRAM_BOT_TOKEN=xxx CODEX_MODEL=o3 npx codeclaw -a codex
 | `/sessions` | 列出、切换或创建会话（分页内联键盘） |
 | `/agents` | 列出已安装的 Agent，切换使用 |
 | `/switch` | 浏览和切换工作目录（交互式文件浏览器） |
-| `/status` | 机器人状态：运行时间、内存、Agent、会话、Token 用量 |
+| `/status` | 机器人状态：运行时间、内存、Agent、会话、Provider 用量、Token 用量 |
 | `/host` | 宿主机信息：CPU、内存、磁盘、进程排行 |
+| `/restart` | 通过 `npx --yes codeclaw@latest` 拉取最新版本并重启 |
 | `/start` | 欢迎消息和命令列表 |
 
 > 在私聊中直接发送文字即可，无需命令前缀。未识别的 `/命令` 会作为 prompt 转发给 Agent。

package/dist/bot-telegram.js

@@ -87,6 +87,155 @@ function detectQuickReplies(text) {
         return numbered.map(m => `${m[1]}. ${m[2].trim().slice(0, 30)}`);
     return [];
 }
+function isNpxBinary(bin) {
+    return path.basename(bin, path.extname(bin)).toLowerCase() === 'npx';
+}
+function ensureNonInteractiveRestartArgs(bin, args) {
+    if (!isNpxBinary(bin))
+        return args;
+    if (args.includes('--yes') || args.includes('-y'))
+        return args;
+    return ['--yes', ...args];
+}
+const ARTIFACT_MANIFEST = 'manifest.json';
+const ARTIFACT_ROOT = path.join(os.tmpdir(), 'codeclaw-artifacts');
+const ARTIFACT_MAX_FILES = 8;
+const ARTIFACT_MAX_BYTES = 20 * 1024 * 1024;
+const ARTIFACT_PHOTO_EXTS = new Set(['.jpg', '.jpeg', '.png', '.webp']);
+function isPhotoFilename(filename) {
+    return ARTIFACT_PHOTO_EXTS.has(path.extname(filename).toLowerCase());
+}
+export function collectArtifacts(dirPath, manifestPath, log) {
+    const _log = log || (() => { });
+    if (!fs.existsSync(manifestPath))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    }
+    catch (e) {
+        _log(`artifact manifest parse error: ${e}`);
+        return [];
+    }
+    const entries = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.files) ? parsed.files : [];
+    if (!entries.length)
+        return [];
+    const realDir = fs.realpathSync(dirPath);
+    const artifacts = [];
+    for (const entry of entries.slice(0, ARTIFACT_MAX_FILES)) {
+        const rawPath = typeof entry?.path === 'string' ? entry.path
+            : typeof entry?.name === 'string' ? entry.name
+                : '';
+        const relPath = rawPath.trim();
+        if (!relPath || path.isAbsolute(relPath)) {
+            _log(`artifact skipped: invalid path "${rawPath}"`);
+            continue;
+        }
+        const resolved = path.resolve(dirPath, relPath);
+        const relative = path.relative(dirPath, resolved);
+        if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+            _log(`artifact skipped: outside turn dir "${relPath}"`);
+            continue;
+        }
+        if (!fs.existsSync(resolved)) {
+            _log(`artifact skipped: missing file "${relPath}"`);
+            continue;
+        }
+        const realFile = fs.realpathSync(resolved);
+        const realRelative = path.relative(realDir, realFile);
+        if (realRelative.startsWith('..') || path.isAbsolute(realRelative)) {
+            _log(`artifact skipped: symlink outside turn dir "${relPath}"`);
+            continue;
+        }
+        const stat = fs.statSync(realFile);
+        if (!stat.isFile()) {
+            _log(`artifact skipped: not a file "${relPath}"`);
+            continue;
+        }
+        if (stat.size > ARTIFACT_MAX_BYTES) {
+            _log(`artifact skipped: too large "${relPath}" (${stat.size} bytes)`);
+            continue;
+        }
+        const filename = path.basename(realFile);
+        const requestedKind = typeof entry?.kind === 'string' ? entry.kind.toLowerCase()
+            : typeof entry?.type === 'string' ? entry.type.toLowerCase()
+                : '';
+        let kind = requestedKind === 'document' ? 'document'
+            : requestedKind === 'photo' ? 'photo'
+                : isPhotoFilename(filename) ? 'photo' : 'document';
+        if (kind === 'photo' && !isPhotoFilename(filename))
+            kind = 'document';
+        const caption = typeof entry?.caption === 'string' ? entry.caption.trim().slice(0, 1024) || undefined : undefined;
+        artifacts.push({ filePath: realFile, filename, kind, caption });
+    }
+    return artifacts;
+}
+export function buildArtifactPrompt(prompt, artifactDir, manifestPath) {
+    const base = prompt.trim() || 'Please help with this request.';
+    return [
+        base,
+        '',
+        '[Telegram Artifact Return]',
+        'If you create screenshots, images, logs, or other files that should be sent back to the Telegram user, write them only inside this directory:',
+        artifactDir,
+        '',
+        `When you want a file returned, also write this JSON manifest: ${manifestPath}`,
+        'Format:',
+        '{"files":[{"path":"screenshot.png","kind":"photo","caption":"optional caption"}]}',
+        'Rules:',
+        '- Use relative paths in "path". Never use absolute paths.',
+        '- Use "photo" for png/jpg/jpeg/webp images. Use "document" for everything else.',
+        '- Omit the manifest entirely if there is nothing to send back.',
+    ].join('\n');
+}
+function humanizeUsageStatus(status) {
+    return (status || '').replace(/_/g, ' ').trim();
+}
+function usageRemainingSeconds(capturedAt, resetAfterSeconds) {
+    if (resetAfterSeconds == null)
+        return null;
+    const capturedAtMs = capturedAt ? Date.parse(capturedAt) : Number.NaN;
+    if (Number.isFinite(capturedAtMs)) {
+        return Math.round((capturedAtMs + resetAfterSeconds * 1000 - Date.now()) / 1000);
+    }
+    return resetAfterSeconds;
+}
+function formatProviderUsageLines(usage) {
+    const lines = ['', '<b>Provider Usage</b>'];
+    if (!usage.ok) {
+        lines.push(`  Unavailable: ${escapeHtml(usage.error || 'No recent usage data found.')}`);
+        return lines;
+    }
+    if (usage.capturedAt) {
+        const capturedAtMs = Date.parse(usage.capturedAt);
+        if (Number.isFinite(capturedAtMs)) {
+            lines.push(`  Updated: ${fmtUptime(Math.max(0, Date.now() - capturedAtMs))} ago`);
+        }
+    }
+    if (!usage.windows.length) {
+        const status = humanizeUsageStatus(usage.status);
+        lines.push(`  ${escapeHtml(status || 'No window data')}`);
+        return lines;
+    }
+    for (const window of usage.windows) {
+        const parts = [];
+        if (window.usedPercent != null && window.remainingPercent != null) {
+            parts.push(`${window.usedPercent}% used / ${window.remainingPercent}% left`);
+        }
+        else if (window.usedPercent != null) {
+            parts.push(`${window.usedPercent}% used`);
+        }
+        const status = humanizeUsageStatus(window.status);
+        if (status)
+            parts.push(status);
+        const remainingSeconds = usageRemainingSeconds(usage.capturedAt, window.resetAfterSeconds);
+        if (remainingSeconds != null) {
+            parts.push(remainingSeconds > 0 ? `resets in ${fmtUptime(remainingSeconds * 1000)}` : 'reset passed');
+        }
+        lines.push(`  ${escapeHtml(window.label)}: ${escapeHtml(parts.join(' | ') || 'No details')}`);
+    }
+    return lines;
+}
 // ---------------------------------------------------------------------------
 // Directory browser (Telegram callback_data 64-byte limit)
 // ---------------------------------------------------------------------------
@@ -252,7 +401,7 @@ export class TelegramBot extends Bot {
         if (d.running) {
             lines.push(`<b>Running:</b> ${fmtUptime(Date.now() - d.running.startedAt)} - ${escapeHtml(d.running.prompt.slice(0, 50))}`);
         }
-        lines.push('', '<b>Usage</b>', `  Turns: ${d.stats.totalTurns}`);
+        lines.push(...formatProviderUsageLines(d.usage), '', '<b>Bot Usage</b>', `  Turns: ${d.stats.totalTurns}`);
         if (d.stats.totalInputTokens || d.stats.totalOutputTokens) {
             lines.push(`  In: ${fmtTokens(d.stats.totalInputTokens)}  Out: ${fmtTokens(d.stats.totalOutputTokens)}`);
             if (d.stats.totalCachedTokens)
@@ -311,7 +460,7 @@ export class TelegramBot extends Bot {
             return;
         }
         await ctx.reply(`<b>Restarting codeclaw...</b>\n\n` +
-            `Pulling latest version via <code>npx codeclaw@latest</code>.\n` +
+            `Pulling latest version via <code>npx --yes codeclaw@latest</code>.\n` +
             `The bot will be back shortly.`, { parseMode: 'HTML' });
         this.performRestart();
     }
@@ -320,14 +469,23 @@ export class TelegramBot extends Bot {
         this.log('restart: disconnecting...');
         this.channel.disconnect();
         this.stopKeepAlive();
-        const restartCmd = process.env.CODECLAW_RESTART_CMD || 'npx codeclaw@latest';
-        const [bin, ...baseArgs] = shellSplit(restartCmd);
+        const restartCmd = process.env.CODECLAW_RESTART_CMD || 'npx --yes codeclaw@latest';
+        const [bin, ...rawArgs] = shellSplit(restartCmd);
+        const baseArgs = ensureNonInteractiveRestartArgs(bin, rawArgs);
         const allArgs = [...baseArgs, ...process.argv.slice(2)];
         this.log(`restart: spawning \`${bin} ${allArgs.join(' ')}\``);
+        // Collect all known chat IDs so the new process can send startup notices
+        const knownIds = new Set(this.allowedChatIds);
+        for (const cid of this.channel.knownChats)
+            knownIds.add(cid);
         const child = spawn(bin, allArgs, {
             stdio: 'inherit',
             detached: true,
-            env: process.env,
+            env: {
+                ...process.env,
+                npm_config_yes: process.env.npm_config_yes || 'true',
+                ...(knownIds.size ? { TELEGRAM_ALLOWED_CHAT_IDS: [...knownIds].join(',') } : {}),
+            },
         });
         child.unref();
         this.log(`restart: new process spawned (PID ${child.pid}), exiting...`);
@@ -339,7 +497,8 @@ export class TelegramBot extends Bot {
         if (!text && !msg.files.length)
             return;
         const cs = this.chat(ctx.chatId);
-        const prompt = buildPrompt(text, msg.files);
+        const artifactTurn = this.createArtifactTurn(ctx.chatId);
+        const prompt = buildArtifactPrompt(buildPrompt(text, msg.files), artifactTurn.dir, artifactTurn.manifestPath);
         this.log(`[handleMessage] chat=${ctx.chatId} agent=${cs.agent} session=${cs.sessionId || '(new)'} prompt="${prompt.slice(0, 100)}" files=${msg.files.length}`);
         const phId = await ctx.reply(`<code>${escapeHtml(cs.agent)} | thinking ...</code>`, { parseMode: 'HTML' });
         if (!phId) {
@@ -382,14 +541,44 @@ export class TelegramBot extends Bot {
                 editCount++;
             };
             const result = await this.runStream(prompt, cs, msg.files, onText);
+            const artifacts = this.collectArtifacts(artifactTurn.dir, artifactTurn.manifestPath);
             this.log(`[handleMessage] done agent=${cs.agent} ok=${result.ok} session=${result.sessionId || '?'} elapsed=${result.elapsedS.toFixed(1)}s edits=${editCount} ` +
                 `tokens=in:${fmtTokens(result.inputTokens)}/cached:${fmtTokens(result.cachedInputTokens)}/out:${fmtTokens(result.outputTokens)}`);
             this.log(`[handleMessage] response preview: "${result.message.slice(0, 150)}"`);
-            await this.sendFinalReply(ctx, phId, cs.agent, result);
+            const finalMsgId = await this.sendFinalReply(ctx, phId, cs.agent, result);
+            await this.sendArtifacts(ctx, finalMsgId ?? phId, artifacts);
             this.log(`[handleMessage] final reply sent to chat=${ctx.chatId}`);
         }
         finally {
             this.activeTasks.delete(ctx.chatId);
+            this.cleanupArtifactTurn(artifactTurn.dir);
+        }
+    }
+    createArtifactTurn(chatId) {
+        const turnId = `${chatId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const dir = path.join(ARTIFACT_ROOT, String(chatId), turnId);
+        fs.mkdirSync(dir, { recursive: true });
+        return { dir, manifestPath: path.join(dir, ARTIFACT_MANIFEST) };
+    }
+    cleanupArtifactTurn(dirPath) {
+        fs.rmSync(dirPath, { recursive: true, force: true });
+    }
+    collectArtifacts(dirPath, manifestPath) {
+        return collectArtifacts(dirPath, manifestPath, msg => this.log(msg));
+    }
+    async sendArtifacts(ctx, replyTo, artifacts) {
+        for (const artifact of artifacts) {
+            try {
+                await this.channel.sendFile(ctx.chatId, artifact.filePath, {
+                    caption: artifact.caption,
+                    replyTo,
+                    asPhoto: artifact.kind === 'photo',
+                });
+            }
+            catch (e) {
+                this.log(`artifact upload failed for ${artifact.filename}: ${e}`);
+                await this.channel.send(ctx.chatId, `Artifact upload failed: <code>${escapeHtml(artifact.filename)}</code>`, { parseMode: 'HTML', replyTo }).catch(() => { });
+            }
         }
     }
     async sendFinalReply(ctx, phId, agent, result) {
@@ -458,12 +647,13 @@ export class TelegramBot extends Bot {
         }
         const bodyHtml = mdToTgHtml(result.message);
         const fullHtml = `${statusHtml}${thinkingHtml}${bodyHtml}\n\n${meta}${tokenBlock}`;
+        let finalMsgId = phId;
         if (fullHtml.length <= 3900) {
             try {
                 await this.channel.editMessage(ctx.chatId, phId, fullHtml, { parseMode: 'HTML', keyboard });
             }
             catch {
-                await this.channel.send(ctx.chatId, fullHtml, { parseMode: 'HTML', replyTo: ctx.messageId, keyboard });
+                finalMsgId = await this.channel.send(ctx.chatId, fullHtml, { parseMode: 'HTML', replyTo: ctx.messageId, keyboard });
             }
         }
         else {
@@ -475,13 +665,14 @@ export class TelegramBot extends Bot {
                 await this.channel.editMessage(ctx.chatId, phId, previewHtml, { parseMode: 'HTML', keyboard });
             }
             catch {
-                await this.channel.send(ctx.chatId, previewHtml, { parseMode: 'HTML', replyTo: ctx.messageId, keyboard });
+                finalMsgId = await this.channel.send(ctx.chatId, previewHtml, { parseMode: 'HTML', replyTo: ctx.messageId, keyboard });
             }
             const thinkingMd = result.thinking
                 ? `> **${thinkLabel(agent)}**\n${result.thinking.split('\n').map(l => `> ${l}`).join('\n')}\n\n---\n\n`
                 : '';
-            await this.channel.sendDocument(ctx.chatId, thinkingMd + result.message, `response_${phId}.md`, { caption: `Full response (${result.message.length} chars)`, replyTo: phId });
+            await this.channel.sendDocument(ctx.chatId, thinkingMd + result.message, `response_${phId}.md`, { caption: `Full response (${result.message.length} chars)`, replyTo: finalMsgId ?? phId });
         }
+        return finalMsgId;
     }
     // ---- callbacks ------------------------------------------------------------
     async handleCallback(data, ctx) {

package/dist/bot.js

@@ -7,8 +7,8 @@ import os from 'node:os';
 import fs from 'node:fs';
 import path from 'node:path';
 import { execSync, spawn } from 'node:child_process';
-import { doStream, getSessions, listAgents, } from './code-agent.js';
-export const VERSION = '0.2.3';
+import { doStream, getSessions, getUsage, listAgents, } from './code-agent.js';
+export const VERSION = '0.2.5';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -194,6 +194,7 @@ export class Bot {
             memRss: mem.rss, memHeap: mem.heapUsed, pid: process.pid,
             workdir: this.workdir, agent: cs.agent, model: this.modelForAgent(cs.agent), sessionId: cs.sessionId,
             running: this.activeTasks.get(chatId) ?? null, stats: this.stats,
+            usage: getUsage({ agent: cs.agent, model: this.modelForAgent(cs.agent) }),
         };
     }
     getHostData() {
@@ -234,9 +235,10 @@ export class Bot {
         else if (cs.agent === 'codex') {
             this.log(`[runStream] codex config: model=${this.codexModel} reasoning=${this.codexReasoningEffort} fullAccess=${this.codexFullAccess} extraArgs=[${this.codexExtraArgs.join(' ')}]`);
         }
+        const snapshotSessionId = cs.sessionId;
         const opts = {
             agent: cs.agent, prompt, workdir: this.workdir, timeout: this.runTimeout,
-            sessionId: cs.sessionId, model: null, thinkingEffort: this.codexReasoningEffort, onText,
+            sessionId: snapshotSessionId, model: null, thinkingEffort: this.codexReasoningEffort, onText,
             attachments: attachments.length ? attachments : undefined,
             codexModel: this.codexModel, codexFullAccess: this.codexFullAccess,
             codexExtraArgs: this.codexExtraArgs.length ? this.codexExtraArgs : undefined,
@@ -251,7 +253,8 @@ export class Bot {
             this.stats.totalOutputTokens += result.outputTokens;
         if (result.cachedInputTokens)
             this.stats.totalCachedTokens += result.cachedInputTokens;
-        if (result.sessionId)
+        // Only update sessionId if it hasn't been changed externally (e.g. user switched session during run)
+        if (result.sessionId && cs.sessionId === snapshotSessionId)
             cs.sessionId = result.sessionId;
         this.log(`[runStream] completed turn=${this.stats.totalTurns} cumulative: in=${fmtTokens(this.stats.totalInputTokens)} out=${fmtTokens(this.stats.totalOutputTokens)} cached=${fmtTokens(this.stats.totalCachedTokens)}`);
         return result;

package/dist/channel-telegram.js

@@ -56,6 +56,17 @@ import path from 'node:path';
 import { Channel, splitText, sleep } from './channel-base.js';
 export { TelegramChannel };
 const TG_MAX = 4096;
+const PHOTO_EXTS = new Set(['.jpg', '.jpeg', '.png', '.webp']);
+function mimeTypeForFilename(filename) {
+    switch (path.extname(filename).toLowerCase()) {
+        case '.png': return 'image/png';
+        case '.webp': return 'image/webp';
+        case '.jpg':
+        case '.jpeg':
+        default:
+            return 'image/jpeg';
+    }
+}
 // ---------------------------------------------------------------------------
 // TelegramChannel
 // ---------------------------------------------------------------------------
@@ -203,12 +214,14 @@ class TelegramChannel extends Channel {
         const boundary = `----codeclaw${hash}`;
         const parts = [];
         const add = (s) => parts.push(Buffer.from(s, 'utf-8'));
+        const filename = opts.filename || 'photo.jpg';
+        const mimeType = opts.mimeType || mimeTypeForFilename(filename);
         add(`--${boundary}\r\nContent-Disposition: form-data; name="chat_id"\r\n\r\n${chatId}\r\n`);
-        if (opts.replyTo)
+        if (opts.replyTo != null)
             add(`--${boundary}\r\nContent-Disposition: form-data; name="reply_to_message_id"\r\n\r\n${opts.replyTo}\r\n`);
         if (opts.caption)
             add(`--${boundary}\r\nContent-Disposition: form-data; name="caption"\r\n\r\n${opts.caption.slice(0, 1024)}\r\n`);
-        add(`--${boundary}\r\nContent-Disposition: form-data; name="photo"; filename="photo.jpg"\r\nContent-Type: image/jpeg\r\n\r\n`);
+        add(`--${boundary}\r\nContent-Disposition: form-data; name="photo"; filename="${filename}"\r\nContent-Type: ${mimeType}\r\n\r\n`);
         parts.push(photo);
         add(`\r\n--${boundary}--\r\n`);
         try {
@@ -251,6 +264,20 @@ class TelegramChannel extends Channel {
             throw e;
         }
     }
+    async sendFile(chatId, filePath, opts = {}) {
+        const content = fs.readFileSync(filePath);
+        const filename = path.basename(filePath);
+        const wantsPhoto = opts.asPhoto ?? PHOTO_EXTS.has(path.extname(filename).toLowerCase());
+        if (wantsPhoto) {
+            return this.sendPhoto(chatId, content, {
+                caption: opts.caption,
+                replyTo: opts.replyTo,
+                filename,
+                mimeType: mimeTypeForFilename(filename),
+            });
+        }
+        return this.sendDocument(chatId, content, filename, { caption: opts.caption, replyTo: opts.replyTo });
+    }
     /** Set bottom menu commands and ensure the menu button is visible.
      *  Automatically applies to all known chats (from incoming updates). */
     async setMenu(commands) {

package/dist/code-agent.js

@@ -485,3 +485,299 @@ export function listAgents() {
         ],
     };
 }
+function toIsoFromEpochSeconds(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    return new Date(n * 1000).toISOString();
+}
+function roundPercent(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return null;
+    return Math.max(0, Math.min(100, Math.round(n * 10) / 10));
+}
+function labelFromWindowMinutes(value, fallback) {
+    const minutes = Number(value);
+    if (!Number.isFinite(minutes) || minutes <= 0)
+        return fallback;
+    if (minutes === 300)
+        return '5h';
+    if (minutes === 10080)
+        return '7d';
+    if (minutes % 1440 === 0)
+        return `${minutes / 1440}d`;
+    if (minutes % 60 === 0)
+        return `${minutes / 60}h`;
+    return `${minutes}m`;
+}
+function usageWindowFromRateLimit(fallback, limit) {
+    if (!limit || typeof limit !== 'object')
+        return null;
+    const usedPercent = roundPercent(limit.used_percent);
+    const remainingPercent = usedPercent == null ? null : Math.max(0, Math.round((100 - usedPercent) * 10) / 10);
+    const resetAt = toIsoFromEpochSeconds(limit.reset_at ?? limit.resets_at);
+    let resetAfterSeconds = null;
+    const directResetAfter = Number(limit.reset_after_seconds);
+    if (Number.isFinite(directResetAfter) && directResetAfter >= 0) {
+        resetAfterSeconds = Math.round(directResetAfter);
+    }
+    else if (resetAt) {
+        const resetAtMs = Date.parse(resetAt);
+        if (Number.isFinite(resetAtMs)) {
+            resetAfterSeconds = Math.max(0, Math.round((resetAtMs - Date.now()) / 1000));
+        }
+    }
+    return {
+        label: labelFromWindowMinutes(limit.window_minutes, fallback),
+        usedPercent,
+        remainingPercent,
+        resetAt,
+        resetAfterSeconds,
+        status: typeof limit.status === 'string' ? limit.status : null,
+    };
+}
+function parseJsonTail(raw) {
+    const start = raw.indexOf('{');
+    if (start < 0)
+        return null;
+    try {
+        return JSON.parse(raw.slice(start));
+    }
+    catch {
+        return null;
+    }
+}
+function modelFamily(model) {
+    const lower = model?.toLowerCase() || '';
+    if (!lower)
+        return null;
+    if (lower.includes('opus'))
+        return 'opus';
+    if (lower.includes('sonnet'))
+        return 'sonnet';
+    return null;
+}
+function emptyUsage(agent, error) {
+    return {
+        ok: false,
+        agent,
+        source: null,
+        capturedAt: null,
+        status: null,
+        windows: [],
+        error,
+    };
+}
+function getCodexStateDbPath(home) {
+    const root = path.join(home, '.codex');
+    if (!fs.existsSync(root))
+        return null;
+    try {
+        const files = fs.readdirSync(root)
+            .filter(name => /^state.*\.sqlite$/i.test(name))
+            .map(name => ({ name, full: path.join(root, name), mtime: fs.statSync(path.join(root, name)).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime);
+        return files[0]?.full || null;
+    }
+    catch {
+        return null;
+    }
+}
+function codexUsageFromRateLimits(rateLimits, capturedAt, source) {
+    if (!rateLimits || typeof rateLimits !== 'object')
+        return null;
+    const windows = [
+        usageWindowFromRateLimit('Primary', rateLimits.primary),
+        usageWindowFromRateLimit('Secondary', rateLimits.secondary),
+    ].filter((v) => !!v);
+    if (!windows.length)
+        return null;
+    let status = null;
+    if (rateLimits.limit_reached === true)
+        status = 'limit_reached';
+    else if (rateLimits.allowed === true)
+        status = 'allowed';
+    return {
+        ok: true,
+        agent: 'codex',
+        source,
+        capturedAt,
+        status,
+        windows,
+        error: null,
+    };
+}
+function getCodexUsageFromStateDb(home) {
+    const dbPath = getCodexStateDbPath(home);
+    if (!dbPath)
+        return null;
+    try {
+        const query = "SELECT ts || '|' || message FROM logs WHERE message LIKE '%codex.rate_limits%' ORDER BY ts DESC LIMIT 1;";
+        const out = execSync(`sqlite3 -noheader ${Q(dbPath)} ${Q(query)}`, { encoding: 'utf-8', timeout: 3000 }).trim();
+        if (!out)
+            return null;
+        const sep = out.indexOf('|');
+        const rawTs = sep >= 0 ? out.slice(0, sep) : '';
+        const rawMessage = sep >= 0 ? out.slice(sep + 1) : out;
+        const payload = parseJsonTail(rawMessage);
+        const capturedAt = toIsoFromEpochSeconds(rawTs);
+        return codexUsageFromRateLimits(payload?.rate_limits, capturedAt, 'state-db');
+    }
+    catch {
+        return null;
+    }
+}
+function getCodexUsageFromSessions(home) {
+    const sessionsRoot = path.join(home, '.codex', 'sessions');
+    if (!fs.existsSync(sessionsRoot))
+        return null;
+    const all = [];
+    try {
+        for (const year of fs.readdirSync(sessionsRoot)) {
+            const yp = path.join(sessionsRoot, year);
+            if (!fs.statSync(yp).isDirectory())
+                continue;
+            for (const month of fs.readdirSync(yp)) {
+                const mp = path.join(yp, month);
+                if (!fs.statSync(mp).isDirectory())
+                    continue;
+                for (const day of fs.readdirSync(mp)) {
+                    const dp = path.join(mp, day);
+                    if (!fs.statSync(dp).isDirectory())
+                        continue;
+                    for (const f of fs.readdirSync(dp)) {
+                        if (!f.endsWith('.jsonl'))
+                            continue;
+                        const full = path.join(dp, f);
+                        all.push({ path: full, mtime: fs.statSync(full).mtimeMs });
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    all.sort((a, b) => b.mtime - a.mtime);
+    for (const entry of all.slice(0, 30)) {
+        try {
+            const lines = fs.readFileSync(entry.path, 'utf-8').trim().split('\n');
+            for (let i = lines.length - 1; i >= 0 && i >= lines.length - 200; i--) {
+                const raw = lines[i];
+                if (!raw || raw[0] !== '{' || !raw.includes('rate_limits'))
+                    continue;
+                let ev;
+                try {
+                    ev = JSON.parse(raw);
+                }
+                catch {
+                    continue;
+                }
+                const result = codexUsageFromRateLimits(ev?.payload?.rate_limits, typeof ev?.timestamp === 'string' ? ev.timestamp : null, 'session-history');
+                if (result)
+                    return result;
+            }
+        }
+        catch {
+            // ignore malformed or unreadable session files
+        }
+    }
+    return null;
+}
+function getClaudeUsageFromTelemetry(home, model) {
+    const telemetryRoot = path.join(home, '.claude', 'telemetry');
+    if (!fs.existsSync(telemetryRoot))
+        return null;
+    const preferredFamily = modelFamily(model);
+    let bestAny = null;
+    let bestMatch = null;
+    try {
+        const files = fs.readdirSync(telemetryRoot)
+            .filter(name => name.endsWith('.json'))
+            .map(name => ({ full: path.join(telemetryRoot, name), mtime: fs.statSync(path.join(telemetryRoot, name)).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime)
+            .slice(0, 50);
+        for (const file of files) {
+            const lines = fs.readFileSync(file.full, 'utf-8').trim().split('\n');
+            for (let i = lines.length - 1; i >= 0; i--) {
+                const raw = lines[i];
+                if (!raw || raw[0] !== '{' || !raw.includes('tengu_claudeai_limits_status_changed'))
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    continue;
+                }
+                const data = parsed?.event_data;
+                if (data?.event_name !== 'tengu_claudeai_limits_status_changed')
+                    continue;
+                const capturedAtMs = Date.parse(data.client_timestamp || '');
+                if (!Number.isFinite(capturedAtMs))
+                    continue;
+                let meta = data.additional_metadata;
+                if (typeof meta === 'string') {
+                    try {
+                        meta = JSON.parse(meta);
+                    }
+                    catch {
+                        meta = null;
+                    }
+                }
+                const hoursTillReset = Number(meta?.hoursTillReset);
+                const candidate = {
+                    capturedAtMs,
+                    capturedAt: new Date(capturedAtMs).toISOString(),
+                    status: typeof meta?.status === 'string' ? meta.status : null,
+                    hoursTillReset: Number.isFinite(hoursTillReset) ? hoursTillReset : null,
+                    model: typeof data.model === 'string' ? data.model : null,
+                };
+                if (!bestAny || candidate.capturedAtMs > bestAny.capturedAtMs)
+                    bestAny = candidate;
+                if (preferredFamily && candidate.model?.toLowerCase().includes(preferredFamily)) {
+                    if (!bestMatch || candidate.capturedAtMs > bestMatch.capturedAtMs)
+                        bestMatch = candidate;
+                }
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    const chosen = bestMatch || bestAny;
+    if (!chosen)
+        return null;
+    const resetAfterSeconds = chosen.hoursTillReset == null ? null : Math.max(0, Math.round(chosen.hoursTillReset * 3600));
+    const resetAt = resetAfterSeconds == null ? null : new Date(chosen.capturedAtMs + resetAfterSeconds * 1000).toISOString();
+    const windows = [{
+            label: 'Current',
+            usedPercent: null,
+            remainingPercent: null,
+            resetAt,
+            resetAfterSeconds,
+            status: chosen.status,
+        }];
+    return {
+        ok: true,
+        agent: 'claude',
+        source: 'telemetry',
+        capturedAt: chosen.capturedAt,
+        status: chosen.status,
+        windows,
+        error: null,
+    };
+}
+export function getUsage(opts) {
+    const home = process.env.HOME || '';
+    if (!home)
+        return emptyUsage(opts.agent, 'HOME is not set.');
+    if (opts.agent === 'codex') {
+        return getCodexUsageFromStateDb(home)
+            || getCodexUsageFromSessions(home)
+            || emptyUsage('codex', 'No recent Codex usage data found.');
+    }
+    return getClaudeUsageFromTelemetry(home, opts.model)
+        || emptyUsage('claude', 'No recent Claude usage data found.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeclaw",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "The best IM-driven remote coding experience. Bridge AI coding agents to any IM.",
   "type": "module",
   "bin": {