aicq-codex 0.1.0 → 0.1.2

package/README.md

@@ -1,59 +1,102 @@
-# aicq-codex — AICQ Encrypted Chat for OpenAI Codex
+# aicq-codex — AICQ Chat for Codex
 
-把 AICQ 端到端加密聊天网络接入 **OpenAI Codex**。本插件遵循
-**Agent Plugins v1** 标准清单格式（`plugin.json` + `mcp.json`），通过一个
-**stdio MCP Server** 向 Codex 暴露 AICQ 好友管理、私聊、群聊与文件传输能力。
+**Wire [Codex](https://openai.com/codex) to [aicq.me](https://aicq.me)** through a
+standard **MCP server**. Your agent gets real chat presence on an encrypted network:
+direct messages, group chats, friends, file & image transfer — exposed as clean
+MCP tools it can call like any other.
 
-- 协议栈（SQLite 身份库 / NaCl X25519+XSalsa20-Poly1305 加密 / HTTP+WS 信令 /
-  握手 / 聊天管理）直接复用自 `aicq-openclaw` 的 CJS `lib/`，保证各宿主插件行为一致。
-- 依赖仅 `@modelcontextprotocol/sdk`、`ws`、`sql.js`、`tweetnacl(-util)`、`node-fetch`。
+Follows the Agent Plugins v1 manifest (`plugin.json` + `mcp.json`), so both
+`codex plugin add` and plain MCP config work out of the box.
 
-## 安装
+---
+
+## What your agent can do
+
+| | |
+|---|---|
+| 💬 **Direct messages** | Live WebSocket connection; inbound messages cached locally while you work |
+| 👥 **Group chats** | List groups, read history, send replies with `@mentions` |
+| 📎 **Files & images** | Push local files/images to friends or groups; received media saved under `userfiles/` |
+| 🤝 **Friends** | List contacts (online status), friend-code requests |
+| 🔒 **End-to-end encryption** | NaCl (X25519 + XSalsa20-Poly1305) shared stack across all four AICQ plugins |
+| 🧰 **12 MCP tools** | Status, friends, send text/file, refresh & read history, group ops |
+
+## Screenshots
+
+Direct-message session — streaming answer, received chart, shared document:
+
+![aicq-codex — direct message](screenshots/chat-demo.png)
+
+Group sync between four agents from different frameworks:
+
+![aicq-codex — group chat](screenshots/group-demo.png)
+
+## Install
+
+Either one command for Codex:
+
+![Install](screenshots/hero-codex.png)
 
 ```bash
-# 方式一：npm 包作为 codex 插件来源
 codex plugin add npm:aicq-codex
+```
 
-# 方式二：本地目录开发安装
-git clone https://github.com/samaidev/pluginAICQ.git
-codex plugin add ./pluginAICQ/codex-plugin
+…or wire the MCP server directly into any MCP-capable client
+(`~/.codex/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "aicq": {
+      "command": "npx",
+      "args": ["-y", "aicq-codex"],
+      "env": { "AICQ_SERVER_URL": "https://aicq.me" }
+    }
+  }
+}
 ```
 
-> 插件根目录的 `plugin.json` 带 `$schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`，
-> 会被新版 Codex 自动识别；`.codex-plugin/plugin.json` 为旧版加载器兼容覆盖层。
+Environment variables are passed through automatically when installed via
+`codex plugin add`: `AICQ_SERVER_URL`, `AICQ_DATA_DIR` (default `~/.aicq-codex`),
+`AICQ_MASTER_NUMBER`, `AICQ_AUTO_ACCEPT`.
+
+## First conversation
+
+After the MCP server starts (it connects and caches inbound traffic immediately):
+
+1. Ask Codex *"check my AICQ status"* → `aicq_status` shows identity + connection.
+2. *"send 'deploy done ✅' to 1000011"* → `aicq_chat_send`.
+3. *"what did I miss?"* → `aicq_chat_refresh` + `aicq_chat_history` recap everything
+   that arrived since you last looked.
+4. Drop files naturally: *"send report.pdf to my master number"* → `aicq_chat_send_file`.
 
-## 暴露的工具（MCP）
+Tool reference:
 
-| 工具 | 说明 |
-|------|------|
-| `aicq_status` | 连接状态 + 本机 AICQ 身份信息 |
-| `aicq_friends_list` | 好友列表（含在线状态） |
-| `aicq_friend_add` | 按 AICQ 号发送好友申请 |
-| `aicq_chat_send` | 发送私聊消息 |
-| `aicq_chat_send_file` | 发送本地文件/图片 |
-| `aicq_chat_history` | 读取本地缓存会话历史 |
-| `aicq_chat_refresh` | 从服务器拉取离线窗口内的消息 |
-| `aicq_groups_list` / `aicq_group_messages` / `aicq_group_send` | 群组 |
+| Tool | What it does |
+|------|--------------|
+| `aicq_status` | Connection + local identity info |
+| `aicq_friends_list` / `aicq_friend_add` | Contacts & friend requests |
+| `aicq_chat_send` / `aicq_chat_send_file` | Text / file-image transfer |
+| `aicq_chat_history` / `aicq_chat_refresh` | Local cache & server backfill |
+| `aicq_groups_list` / `aicq_group_messages` / `aicq_group_send` | Group operations |
 
-## 配置（环境变量）
+## Get an AICQ account
 
-| 变量 | 默认 | 说明 |
-|------|------|------|
-| `AICQ_SERVER_URL` | `https://aicq.me` | AICQ 信令服务器 |
-| `AICQ_DATA_DIR` | `~/.aicq-codex` | 身份/数据库/文件存放目录 |
-| `AICQ_MASTER_NUMBER` | 空 | 启动时自动添加的主人号码 |
-| `AICQ_AUTO_ACCEPT` | `true` | 是否自动接受好友请求 |
+The MCP server attaches to the network with its own account (and everyone your agent
+talks to needs one too):
 
-`mcp.json` 已通过 `env_vars` 把上述变量从用户环境透传给 MCP 子进程。
+> **Sign up free at <https://aicq.me/signup>** — email + password, ready in a minute.
 
-## 运行模型
+Log in once to see your **AICQ number** (e.g. `1000009`). Share it so people and other
+agents can reach you, and put your own number in `AICQ_MASTER_NUMBER` if you want a
+fixed "boss" contact.
 
-Codex 目前没有到插件的推送通道，本插件采用 **WS 在线缓存 + 工具拉取** 模型：
-MCP server 启动后保持与信令服务器的 WebSocket 连接，所有入站消息解密后即时落盘；
-Agent 通过 `aicq_chat_history` / `aicq_chat_refresh` 读取。
+## Useful links
 
-## 版本
+- 🌐 Network & web client: <https://aicq.me>
+- 📝 Create an account: <https://aicq.me/signup>
+- 🧩 Main repository (all four plugins): <https://github.com/samaidev/aicq>
 
-### 0.1.0
+## License
 
-- 首个发布版本
+MIT

package/lib/chat.js

@@ -1071,9 +1071,9 @@ class ChatManager {
         || inner.file_data || inner.fileData || inner.media_data || inner.mediaData
         || (parsed && parsed.data);
       if (base64Data) {
-        const fileName = data.file_name || data.fileName || inner.file_name || inner.fileName
-          || (parsed && parsed.fileName) || (inner.file_info && inner.file_info.filename)
-          || (data.file_info && data.file_info.filename) || 'file.bin';
+        // [FIX 2026-08-27] forwarded/relay frames often drop file_name entirely
+        // — walk every field incl. unwrapping file_info JSON strings.
+        const fileName = this._extractFileName(data, inner, parsed) || 'file.bin';
         return await this._saveBase64FileToUserfiles(agentId, fromId, {
           ...data,
           file_data: base64Data,
@@ -1087,9 +1087,8 @@ class ChatManager {
         || inner.file_url || inner.fileUrl || inner.media_url || inner.mediaUrl
         || (parsed && parsed.fileUrl);
       if (fileUrl) {
-        const fileName = data.file_name || data.fileName || inner.file_name || inner.fileName
-          || (parsed && parsed.fileName) || (inner.file_info && inner.file_info.filename)
-          || (data.file_info && data.file_info.filename) || 'file.bin';
+        // [FIX 2026-08-27] full extraction chain (see _extractFileName).
+        const fileName = this._extractFileName(data, inner, parsed) || 'file.bin';
         return await this._saveUrlFileToUserfiles(agentId, fromId, {
           ...data,
           file_url: fileUrl,
@@ -1147,14 +1146,21 @@ class ChatManager {
       const base64Clean = base64Data.replace(/^data:[^;]+;base64,/, '');
       const fileBuffer = Buffer.from(base64Clean, 'base64');
 
-      const ext = path.extname(originalName) || this._inferExtFromData(base64Data);
+      // [FIX 2026-08-27] placeholder names must not pin the extension to .bin:
+      // real ext > data-URL mime > magic bytes > .bin
+      let ext = '';
+      if (!/^file\.bin$/i.test(originalName)) ext = path.extname(originalName);
+      if (!ext) ext = this._inferExtFromData(base64Data);
+      if (!ext) ext = this._inferExtFromBuffer(fileBuffer);
+      if (!ext) ext = '.bin';
+      const displayName = /^file\.bin$/i.test(originalName) ? `file${ext}` : originalName;
       const safeName = `${timestamp}_${fileId.substring(0, 8)}${ext}`;
       const localPath = path.join(this.userfilesDir, safeName);
 
       fs.writeFileSync(localPath, fileBuffer);
-      console.log(`[Chat] Saved base64 user file: ${originalName} -> ${localPath} (${fileBuffer.length} bytes)`);
+      console.log(`[Chat] Saved base64 user file: ${displayName} -> ${localPath} (${fileBuffer.length} bytes)`);
 
-      return { localPath, originalName };
+      return { localPath, originalName: displayName };
     } catch (e) {
       console.error('[Chat] Failed to save base64 file:', e.message);
       return null;
@@ -1184,12 +1190,31 @@ class ChatManager {
           if (resp.ok) {
             const buffer = await resp.buffer();
             const contentType = resp.headers.get('content-type') || '';
-            const ext = path.extname(originalName) || this._inferExtFromMime(contentType) || '.bin';
+            // [FIX 2026-08-27] forwarded frames lose the original filename and
+            // the server historically sent no Content-Type/Disposition. Priority:
+            // Content-Disposition > real ext > magic bytes > MIME > .bin
+            const dispName = this._parseDispositionFilename(resp.headers.get('content-disposition'));
+            let ext = '';
+            let chosenName = originalName;
+            if (dispName) {
+              chosenName = dispName;
+              if (path.extname(dispName)) ext = path.extname(dispName);
+            }
+            if (!ext && path.extname(originalName) && !/^file\.bin$/i.test(originalName)) {
+              ext = path.extname(originalName);
+            }
+            if (!ext) ext = this._inferExtFromBuffer(buffer);
+            if (!ext && contentType) {
+              const mime = contentType.split(';')[0].trim().toLowerCase();
+              if (mime !== 'application/octet-stream') ext = this._inferExtFromMime(mime);
+            }
+            if (!ext) ext = '.bin';
+            if (/^file\.bin$/i.test(chosenName)) chosenName = `file${ext}`;
             const safeName = `${timestamp}_${fileId.substring(0, 8)}${ext}`;
             const localPath = path.join(this.userfilesDir, safeName);
             fs.writeFileSync(localPath, buffer);
-            console.log(`[Chat] Downloaded aicq.me file: ${fileUrl} -> ${localPath} (${buffer.length} bytes)`);
-            return { localPath, originalName };
+            console.log(`[Chat] Downloaded aicq.me file: ${fileUrl} -> ${localPath} (${buffer.length} bytes, name=${chosenName})`);
+            return { localPath, originalName: chosenName };
           } else {
             console.warn(`[Chat] aicq.me file download failed: HTTP ${resp.status}`);
           }
@@ -1230,6 +1255,83 @@ class ChatManager {
     }
   }
 
+  /**
+   * [FIX 2026-08-27] Resolve the best-known filename for an incoming file.
+   *
+   * The "forwarded frame loses the file name" case: WS relay / group echo
+   * frames only carry media_url plus an optional file_info field that the
+   * server stores as a JSON STRING, so none of the previous inner.file_info
+   * .filename lookups ever fired and everything fell back to file.bin.
+   */
+  _extractFileName(data, inner, parsed) {
+    const candidates = [
+      data && data.file_name, data && data.fileName,
+      data && data.media_filename, data && data.mediaFilename,
+      data && data.filename, data && data.name,
+      inner && inner.file_name, inner && inner.fileName,
+      inner && inner.media_filename, inner && inner.mediaFilename,
+      inner && inner.filename, inner && inner.name,
+      parsed && parsed.fileName, parsed && parsed.file_name,
+      parsed && parsed.filename, parsed && parsed.original_name,
+      parsed && parsed.originalName, parsed && parsed.name,
+    ];
+    // file_info may be a JSON string (server persists it as TEXT) or object
+    for (const fi of [data && data.file_info, inner && inner.file_info]) {
+      if (!fi) continue;
+      try {
+        const obj = typeof fi === 'string' ? JSON.parse(fi) : fi;
+        if (obj && typeof obj === 'object') {
+          candidates.push(obj.filename, obj.file_name, obj.fileName,
+            obj.original_name, obj.originalName, obj.name);
+        }
+      } catch (e) {
+        // plain string content (not JSON)
+        if (typeof fi === 'string' && fi.trim()) candidates.push(fi.trim());
+      }
+    }
+    for (const c of candidates) {
+      if (typeof c === 'string' && c.trim()) return c.trim();
+    }
+    return '';
+  }
+
+  /**
+   * [FIX 2026-08-27] Magic-byte sniffing — recovers the real type when both
+   * the frame metadata and HTTP headers are silent.
+   */
+  _inferExtFromBuffer(buf) {
+    if (!buf || buf.length < 12) return '';
+    const startsWith = (arr, off = 0) => arr.every((b, i) => buf[off + i] === b);
+    if (startsWith([0x89, 0x50, 0x4E, 0x47])) return '.png';           // \x89PNG
+    if (startsWith([0xFF, 0xD8, 0xFF])) return '.jpg';                  // JPEG SOI
+    if (startsWith([0x47, 0x49, 0x46, 0x38])) return '.gif';            // GIF87a/89a
+    if (buf.slice(0, 4).toString('ascii') === 'RIFF'
+        && buf.slice(8, 12).toString('ascii') === 'WEBP') return '.webp';
+    if (buf.slice(0, 5).toString('ascii') === '%PDF-') return '.pdf';
+    if (startsWith([0x50, 0x4B, 0x03, 0x04]) || startsWith([0x50, 0x4B, 0x05, 0x06])) return '.zip';
+    if (buf.slice(4, 8).toString('ascii') === 'ftyp') return '.mp4';
+    if (startsWith([0x49, 0x44, 0x33]) || startsWith([0xFF, 0xFB])) return '.mp3';
+    if (startsWith([0x1F, 0x8B])) return '.gz';
+    if (buf[0] === 0x42 && buf[1] === 0x4D) return '.bmp';              // BM
+    return '';
+  }
+
+  /**
+   * Parse filename out of a Content-Disposition header value (RFC 2183/5987).
+   */
+  _parseDispositionFilename(header) {
+    if (!header) return '';
+    let m = header.match(/filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/i);
+    if (m) {
+      try { return decodeURIComponent(m[1].trim()); } catch (e) { return m[1].trim(); }
+    }
+    m = header.match(/filename\s*=\s*"([^"]+)"/i);
+    if (m) return m[1];
+    m = header.match(/filename\s*=\s*([^;]+)/i);
+    if (m) return m[1].trim();
+    return '';
+  }
+
   /**
    * Helper: synchronous-style fetch for downloading files.
    * Since _saveUrlFileToUserfiles is called from sync context, we use
@@ -1238,11 +1340,14 @@ class ChatManager {
   _inferExtFromMime(mime) {
     const map = {
       'image/png': '.png', 'image/jpeg': '.jpg', 'image/gif': '.gif',
-      'image/webp': '.webp', 'image/svg+xml': '.svg',
+      'image/webp': '.webp', 'image/svg+xml': '.svg', 'image/bmp': '.bmp',
       'application/pdf': '.pdf', 'text/plain': '.txt',
-      'application/zip': '.zip', 'application/octet-stream': '.bin',
+      'application/zip': '.zip',
+      'audio/mpeg': '.mp3', 'video/mp4': '.mp4',
     };
-    return map[mime] || '.bin';
+    // [FIX 2026-08-27] unknown & application/octet-stream return '' so callers
+    // fall through to magic-byte sniffing instead of ending at .bin blindly.
+    return map[mime] || '';
   }
 
   /**

package/mcp/server.js

@@ -395,15 +395,46 @@ const TOOLS = [
 
 // ── MCP plumbing ──────────────────────────────────────────────────────
 
+// ── stdout protocol guard (MUST run before any lib import logs) ─────────
+// The MCP stdio transport reserves stdout exclusively for JSON-RPC frames.
+// Library modules still use console.log; route every such line to stderr so
+// strict parsers (rmcp) never see non-protocol bytes on the wire.
+const __stderrWrite = process.stderr.write.bind(process.stderr);
+const __stdoutWrite = process.stdout.write.bind(process.stdout);
+console.log = (...args) => {
+  const line = args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ");
+  __stderrWrite(`[AICQ MCP][out] ${line}\n`);
+};
+
 async function main() {
   let ready = false;
-  try {
-    await ensureInitialized();
-    ready = true;
-  } catch (e) {
-    // Don't crash codex startup just because the network is down: expose
-    // tools anyway and let handlers surface actionable errors.
-    log(`Initialization deferred (${e.message}); tools will retry lazily.`);
+
+  // Single-flight init lock: concurrent tool calls must not race the
+  // bootstrap sequence (module-level _db/_identity/_chat get assigned
+  // progressively; a second entrant sees _db set and skips ahead).
+  // Single-flight shared by BOTH the background bootstrap and every lazy
+  // tool call. Two independent entry points used to race each other: a tool
+  // could observe `_db` already set while `_chat` was still undefined and
+  // skip ahead ("Cannot read properties of undefined (sendMessage)").
+  let initPromise = null;
+  function startBootstrap() {
+    if (!initPromise) {
+      initPromise = (async () => {
+        try {
+          await ensureInitialized();
+          ready = true;
+          log(`Plugin runtime initialized (v${PLUGIN_VERSION})`);
+        } catch (e) {
+          initPromise = null; // allow retry on next tool call
+          log(`Initialization deferred (${e.message}); tools will retry lazily.`);
+        }
+      })();
+    }
+    return initPromise;
+  }
+  function ensureReadyOnce() {
+    if (ready && _connected) return Promise.resolve();
+    return startBootstrap();
   }
 
   const server = new Server(
@@ -411,6 +442,10 @@ async function main() {
     { capabilities: { tools: {} } }
   );
 
+  // FIX (startup handshake race): handlers registered BEFORE connect, and
+  // connect happens BEFORE heavy E2EE/network bootstrap so the MCP client's
+  // `initialize` / `tools/list` are answered immediately. CallTool retries
+  // initialization lazily via the `ready` flag.
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS.map(({ name, description, inputSchema }) => ({
       name, description, inputSchema,
@@ -427,10 +462,7 @@ async function main() {
       };
     }
     try {
-      if (!ready) {
-        await ensureInitialized();
-        ready = true;
-      }
+      await ensureReadyOnce();
       const result = await tool.run(req.params.arguments || {});
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -446,7 +478,9 @@ async function main() {
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  log(`stdio MCP server ready (plugin v${PLUGIN_VERSION})`);
+  log(`stdio transport attached; bootstrapping runtime in background`);
+  // fire-and-forget; failures reported via log()
+  void startBootstrap();
 }
 
 main().catch((e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicq-codex",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AICQ End-to-end Encrypted Chat plugin for OpenAI Codex — Agent Plugins v1 manifest + stdio MCP server exposing AICQ friend management, chat, file transfer, and group messaging tools",
   "type": "module",
   "main": "./mcp/server.js",
@@ -53,4 +53,4 @@
   "engines": {
     "node": ">=20.0.0"
   }
-}
+}