glad-web 1.0.43 → 1.0.45

package/README.md

@@ -34,6 +34,8 @@ Glad was created to enable **vibe coding** on mobile devices. By bringing variou
 
 Our design philosophy is **Easy to use, Stable, and Restrained**. Glad focuses strictly on the essentials:
 - **Session management:** Run multiple sessions from a single dashboard with per-session working directories.
+- **Responsive workspace:** Use a resizable session sidebar on wide screens and focused lobby/chat pages on mobile, with light and dark themes.
+- **File attachments:** Upload images or arbitrary local files from the composer; Glad stores them privately for the active session and cleans them up automatically.
 - **Local usage dashboard:** Select a week or month, compare per-model and daily token totals, and inspect model-stacked token and cost charts through the bundled read-only `ccusage` engine. Costs use `ccusage` estimates and are shown only for GPT models used by Codex.
 - **High-fidelity terminal interaction:** A mobile-friendly terminal experience with touch shortcuts.
 - **Extreme performance history viewing:** Fast and responsive text history.

package/README.zh-CN.md

@@ -34,6 +34,8 @@ Glad 的初衷是开发一款完全运行在本地的、足够简单的，且登
 
 我们的设计哲学是：**易用、稳定、克制**。只提供最核心且体验优秀的功能：
 - **Session 管理**：在一个面板中管理多个会话，每个会话可单独指定工作目录。
+- **响应式工作区**：宽屏提供可调宽度的会话侧边栏，手机使用大厅与对话双页面，并支持亮色、暗色主题。
+- **文件附件**：可从输入区上传图片或普通文件；附件仅保存于当前会话的私有临时目录，并会自动清理。
 - **本地用量看板**：通过内置的只读 `ccusage` 引擎选择某周或某月，查看按模型汇总及每日 token，并用按模型堆叠的柱状图比较 token 和费用；费用完全采用 `ccusage` 估算，且只对 Codex 使用的 GPT 模型显示。
 - **高还原度的 terminal 交互**：专为手机优化的终端体验与快捷按键。
 - **极致性能的历史查看**：快速流畅的终端历史记录浏览。

package/lib/claude/structured-session.js

@@ -211,22 +211,27 @@ class ClaudeStructuredSession extends EventEmitter {
     return true;
   }
 
-  sendUserMessage(text, attachments = []) {
+  sendUserMessage(text, attachments = [], options = {}) {
     if (!this.running) return false;
     const prompt = String(text || '').trim();
+    const agentPrompt = String(options.agentText ?? prompt).trim();
     const images = Array.isArray(attachments) ? attachments.filter(item => item?.data && item?.mediaType) : [];
-    if (!prompt && images.length === 0) return false;
+    const displayAttachments = Array.isArray(options.displayAttachments) ? options.displayAttachments : [];
+    if (!agentPrompt && images.length === 0) return false;
     this.hasUnreadCompletion = false;
-    const turn = this.beginTurn(prompt, images.map(item => ({ name: item.name, size: item.size })));
+    const turn = this.beginTurn(prompt, [
+      ...images.map(item => ({ name: item.name, size: item.size })),
+      ...displayAttachments
+    ]);
     this.setStatus('thinking');
 
     const content = images.length > 0 ? [
-      ...(prompt ? [{ type: 'text', text: prompt }] : []),
+      ...(agentPrompt ? [{ type: 'text', text: agentPrompt }] : []),
       ...images.map(item => ({
         type: 'image',
         source: { type: 'base64', media_type: item.mediaType, data: item.data }
       }))
-    ] : prompt;
+    ] : agentPrompt;
 
     const sdkMessage = {
       type: 'user',

package/lib/codex/image-store.js

@@ -35,8 +35,7 @@ class CodexImageStore {
 
   assertSession(session) {
     if (!session) throw inputError('Session not found', 404);
-    const structured = session.kind === 'claude-structured'
-      || (session.kind === 'codex-structured' && session.presentation === 'structured');
+    const structured = ['claude-structured', 'codex-structured'].includes(session.kind);
     if (!structured) {
       throw inputError('Image attachments are available only in structured chat mode');
     }

package/lib/codex/structured-session.js

@@ -3,7 +3,6 @@ const { spawn } = require('child_process');
 const net = require('net');
 const crypto = require('crypto');
 const WebSocket = require('ws');
-const PTYManager = require('../session/pty-manager');
 
 const PERMISSION_MODES = new Set(['untrusted', 'on-request', 'never']);
 const SANDBOX_MODES = new Set(['read-only', 'workspace-write', 'danger-full-access']);
@@ -282,7 +281,6 @@ class CodexStructuredSession extends EventEmitter {
     this.startTime = Date.now();
     this.running = true;
     this.status = 'idle';
-    this.presentation = 'structured';
     this.messages = [];
     this.replayingHistory = false;
     this.pendingPermissions = new Map();
@@ -326,27 +324,17 @@ class CodexStructuredSession extends EventEmitter {
     this.abortGraceMs = Number(options.abortGraceMs) > 0
       ? Number(options.abortGraceMs) : DEFAULT_ABORT_GRACE_MS;
     this.forceKillProcessTree = options.forceKillProcessTree || forceKillProcessTree;
-    this.terminalSession = null;
-    this.terminalOutput = '';
     this.hasUnreadCompletion = false;
     this.inputSeq = 0;
     this.completionReadInputSeq = 0;
     this.timedInputs = new Map();
     this.promptHistoryCache = null;
     this.deferredWarnings = null;
-    this.ptyManager = {
-      workingDir,
-      isRunning: () => this.isRunning(),
-      write: data => this.write(data),
-      kill: () => this.kill(),
-      resize: (cols, rows) => this.terminalSession?.resize(cols, rows),
-      redraw: () => false
-    };
   }
 
   toListItem() {
     return { id: this.id, name: this.name, tool: this.tool.displayName, startTime: this.startTime,
-      toolKey: this.tool.key, workingDirectory: this.workingDir, mode: this.presentation === 'terminal' ? 'terminal' : 'structured',
+      toolKey: this.tool.key, workingDirectory: this.workingDir, mode: 'structured',
       hasUnreadCompletion: Boolean(this.hasUnreadCompletion), timedInputCount: this.timedInputs.size };
   }
 
@@ -404,15 +392,12 @@ class CodexStructuredSession extends EventEmitter {
     return { permissionMode: this.permissionMode || 'default', sandboxMode: this.sandboxMode || 'default',
       effectivePermissionMode: this.effectivePermissionMode, effectiveSandboxMode: this.effectiveSandboxMode,
       model: this.model, effort: this.effort,
-      status: this.status, threadId: this.threadId, presentation: this.presentation,
+      status: this.status, threadId: this.threadId,
       aborting: this.aborting, resuming: this.resuming,
-      canAbort: this.presentation === 'structured' && (this.status !== 'idle' || this.resuming) && !this.aborting,
-      canCompact: this.presentation === 'structured' && this.status === 'idle' && !this.compacting
+      canAbort: (this.status !== 'idle' || this.resuming) && !this.aborting,
+      canCompact: this.status === 'idle' && !this.compacting
         && !this.aborting && !this.resuming && Boolean(this.threadId),
       compacting: this.compacting,
-      canSwitchToTerminal: this.presentation === 'structured' && this.status === 'idle'
-        && !this.aborting && !this.resuming && Boolean(this.threadId),
-      canSwitchToStructured: this.presentation === 'terminal',
       pendingPermissionCount: this.pendingPermissions.size, activeSubagentCount, models: this.models };
   }
 
@@ -424,15 +409,14 @@ class CodexStructuredSession extends EventEmitter {
       return item.text || '';
     }).filter(Boolean).join('\n\n');
     return { success: true, sessionId: this.id, sessionName: this.name, tool: this.tool.displayName,
-      historyMode: this.presentation === 'terminal' ? 'terminal' : 'structured', text, updatedAt: Date.now(),
+      historyMode: 'structured', text, updatedAt: Date.now(),
       truncated: false, bytes: Buffer.byteLength(text, 'utf8'), lines: text ? text.split('\n').length : 0 };
   }
 
   getCatchupOutput() {
-    if (this.presentation === 'terminal') return { source: 'codex-terminal', items: 1, data: this.terminalOutput };
     return { source: 'codex-structured', items: this.messages.length, data: '' };
   }
-  isRunning() { return this.running && (this.presentation !== 'terminal' || Boolean(this.terminalSession)); }
+  isRunning() { return this.running; }
 
   createItem(item) { return { id: crypto.randomUUID(), createdAt: Date.now(), ...item }; }
   append(item) {
@@ -502,7 +486,7 @@ class CodexStructuredSession extends EventEmitter {
           const failure = error instanceof Error ? error : new Error(String(error || 'Codex app-server transport closed'));
           this.logger.debugInfo?.(`[codex-app-server] transport failed: ${failure.message}`);
           this.needsThreadResume = Boolean(this.threadId || this.resumeTarget);
-          if (this.running && this.presentation === 'structured') {
+          if (this.running) {
             const activeTurn = Boolean(this.currentTurnId || this.status === 'running' || this.status === 'waiting_approval');
             this.clearAbortState(false);
             this.compacting = false;
@@ -526,7 +510,7 @@ class CodexStructuredSession extends EventEmitter {
             request.reject(new Error(`Codex app-server exited (${code})`));
           }
           this.pendingRequests.clear();
-          if (this.running && this.presentation === 'structured') {
+          if (this.running) {
             const activeTurn = Boolean(this.currentTurnId || this.status === 'running' || this.status === 'waiting_approval');
             this.needsThreadResume = Boolean(this.threadId);
             this.clearAbortState(false);
@@ -1132,7 +1116,6 @@ class CodexStructuredSession extends EventEmitter {
   }
 
   async showStatus() {
-    if (this.presentation !== 'structured') return false;
     await this.ensureProcess();
     const accountResult = await this.request('account/read', { refreshToken: false });
     const account = accountResult?.account || null;
@@ -1172,11 +1155,11 @@ class CodexStructuredSession extends EventEmitter {
     }
     const needsConfigDefaults = (settings.permissionMode !== undefined && !this.permissionMode)
       || (settings.sandboxMode !== undefined && !this.sandboxMode);
-    if (needsConfigDefaults && this.presentation === 'structured') {
+    if (needsConfigDefaults) {
       await this.ensureProcess();
       await this.refreshConfigDefaults();
     }
-    if (this.threadId && this.presentation === 'structured') {
+    if (this.threadId) {
       await this.ensureProcess();
       const params = { threadId: this.threadId };
       if (settings.permissionMode !== undefined) {
@@ -1219,18 +1202,22 @@ class CodexStructuredSession extends EventEmitter {
     return params;
   }
 
-  async sendUserMessage(text, attachments = [], skills = []) {
+  async sendUserMessage(text, attachments = [], skills = [], options = {}) {
     const prompt = String(text || '').trim();
+    const agentPrompt = String(options.agentText ?? prompt).trim();
     const images = (Array.isArray(attachments) ? attachments : [])
       .filter(item => item && typeof item.path === 'string' && item.path);
-    if ((!prompt && images.length === 0) || this.presentation !== 'structured'
-      || this.status !== 'idle' || this.aborting || this.resuming) return false;
+    const displayAttachments = Array.isArray(options.displayAttachments) ? options.displayAttachments : [];
+    if ((!agentPrompt && images.length === 0) || this.status !== 'idle' || this.aborting || this.resuming) return false;
     this.hasUnreadCompletion = false;
     this.promptHistoryCache = null;
     this.append({
       kind: 'user',
-      text: prompt || '📷 Image attachment',
-      attachments: images.map(item => ({ id: item.id, name: item.name || 'image' })),
+      text: prompt || (displayAttachments.length ? '📎 File attachment' : '📷 Image attachment'),
+      attachments: [
+        ...images.map(item => ({ id: item.id, name: item.name || 'image' })),
+        ...displayAttachments
+      ],
       skills: (Array.isArray(skills) ? skills : []).map(item => ({
         name: String(item?.name || ''), path: String(item?.path || '')
       })).filter(item => item.name && item.path)
@@ -1255,7 +1242,7 @@ class CodexStructuredSession extends EventEmitter {
       }
       const input = [];
       input.push(...await this.resolveSkillInputs(skills));
-      if (prompt) input.push({ type: 'text', text: prompt });
+      if (agentPrompt) input.push({ type: 'text', text: agentPrompt });
       for (const image of images) input.push({ type: 'localImage', path: image.path });
       const params = { threadId: this.threadId, input, cwd: this.workingDir, summary: 'auto' };
       if (this.hasModelOverride) params.model = this.model;
@@ -1278,7 +1265,7 @@ class CodexStructuredSession extends EventEmitter {
   }
 
   async compactContext() {
-    if (!this.threadId || this.presentation !== 'structured' || this.status !== 'idle'
+    if (!this.threadId || this.status !== 'idle'
       || this.aborting || this.resuming) return false;
     await this.ensureProcess();
     this.compacting = true;
@@ -1295,7 +1282,6 @@ class CodexStructuredSession extends EventEmitter {
   }
 
   write(data) {
-    if (this.presentation === 'terminal') return this.terminalSession?.write(data) || false;
     const text = String(data || '').replace(/\r/g, '\n');
     const prompt = text.trim();
     if (prompt) void this.sendUserMessage(prompt).catch(error => {
@@ -1330,7 +1316,7 @@ class CodexStructuredSession extends EventEmitter {
   }
 
   abort(reason = 'Aborted by user') {
-    if (this.presentation !== 'structured' || (this.status === 'idle' && !this.resuming)) return false;
+    if (this.status === 'idle' && !this.resuming) return false;
     if (this.aborting) return true;
     if (this.resuming) {
       this.aborting = true;
@@ -1417,7 +1403,7 @@ class CodexStructuredSession extends EventEmitter {
 
   resume(threadId = null) {
     const target = String(threadId || this.threadId || '').trim();
-    if (!target || this.presentation !== 'structured' || this.status !== 'idle' || this.aborting) return false;
+    if (!target || this.status !== 'idle' || this.aborting) return false;
     if (this.resumePromise) return target === this.resumeTarget ? this.resumePromise : false;
     this.resuming = true;
     this.resumeTarget = target;
@@ -1521,7 +1507,7 @@ class CodexStructuredSession extends EventEmitter {
 
   async forkFrom(threadId) {
     const sourceThreadId = String(threadId || '').trim();
-    if (!sourceThreadId || this.presentation !== 'structured' || this.status !== 'idle'
+    if (!sourceThreadId || this.status !== 'idle'
       || this.aborting || this.resuming) return false;
     await this.ensureProcess();
     const params = { threadId: sourceThreadId, cwd: this.workingDir, ephemeral: false, threadSource: null };
@@ -1542,39 +1528,6 @@ class CodexStructuredSession extends EventEmitter {
     return { threadId: this.threadId };
   }
 
-  async switchToTerminal() {
-    if (this.presentation !== 'structured' || this.status !== 'idle' || this.aborting
-      || this.resuming || !this.threadId) throw new Error('Codex must be idle before switching to Terminal.');
-    await this.disconnectProcess();
-    this.terminalOutput = '';
-    const terminal = new PTYManager(this.tool, this.workingDir, { append() {} }, { silent: true });
-    terminal.onData(data => {
-      this.terminalOutput = (this.terminalOutput + data).slice(-1024 * 1024);
-      this.emit('output', data);
-    });
-    terminal.onExit(() => { this.terminalSession = null; this.emitEvent({ type: 'state', state: this.getControlState() }); });
-    if (!terminal.start(['resume', this.threadId])) throw new Error('Failed to start Codex terminal.');
-    this.terminalSession = terminal;
-    this.presentation = 'terminal';
-    this.emitEvent({ type: 'presentation', presentation: 'terminal', state: this.getControlState() });
-    return true;
-  }
-
-  async switchToStructured() {
-    if (this.presentation !== 'terminal') throw new Error('Codex is already in chat mode.');
-    await this.ensureProcess();
-    const listed = await this.request('thread/list', { limit: 100, archived: false, cwd: this.workingDir, useStateDbOnly: true });
-    const current = (listed?.data || []).find(item => item.id === this.threadId);
-    if (current?.status?.type === 'active') throw new Error('Codex is still running in Terminal. Wait for it to finish before switching.');
-    if (this.terminalSession) {
-      this.terminalSession.kill();
-      this.terminalSession = null;
-    }
-    this.presentation = 'structured';
-    this.emitEvent({ type: 'presentation', presentation: 'structured', state: this.getControlState() });
-    return this.resume();
-  }
-
   async disconnectProcess(force = false, reason = null) {
     if (!this.process) return this.processShutdown || undefined;
     const child = this.process;
@@ -1613,8 +1566,6 @@ class CodexStructuredSession extends EventEmitter {
     this.clearAbortState(false);
     this.resuming = false;
     this.resumeTarget = null;
-    this.terminalSession?.kill();
-    this.terminalSession = null;
     await this.disconnectProcess(true);
     this.emit('exit');
   }

package/lib/commands/web.js

@@ -275,6 +275,39 @@ async function webCommand(options) {
     }
   });
 
+  app.post('/api/sessions/:id/attachments/files/chunks', express.raw({ type: () => true, limit: '1mb' }), async (req, res) => {
+    try {
+      const result = await sessionManager.appendFileChunk(req.params.id, {
+        uploadId: req.get('X-Glad-Upload-Id'),
+        chunkIndex: req.get('X-Glad-Chunk-Index'),
+        chunkTotal: req.get('X-Glad-Chunk-Total'),
+        name: req.get('X-Glad-File-Name')
+      }, req.body);
+      res.json({ success: true, ...result });
+    } catch (e) {
+      res.status(e.statusCode || 500).json({ error: e.message });
+    }
+  });
+
+  app.delete('/api/sessions/:id/attachments/files/uploads/:uploadId', async (req, res) => {
+    try {
+      const removed = await sessionManager.discardFileUpload(req.params.id, req.params.uploadId);
+      res.json({ success: true, removed });
+    } catch (e) {
+      res.status(e.statusCode || 500).json({ error: e.message });
+    }
+  });
+
+  app.delete('/api/sessions/:id/attachments/files/:attachmentId', async (req, res) => {
+    try {
+      const removed = await sessionManager.discardFileAttachment(req.params.id, req.params.attachmentId);
+      if (!removed) return res.status(404).json({ error: 'File attachment not found' });
+      res.json({ success: true });
+    } catch (e) {
+      res.status(e.statusCode || 500).json({ error: e.message });
+    }
+  });
+
   // API: Delete/Kill session
   app.delete('/api/sessions/:id', async (req, res) => {
     await sessionManager.kill(req.params.id);
@@ -335,7 +368,7 @@ async function webCommand(options) {
     if (session.kind === 'claude-structured') {
       ws.send(JSON.stringify({ type: 'claude-snapshot', snapshot: sessionManager.getClaudeSnapshot(sessionId) }));
     }
-    if (session.kind === 'codex-structured' && session.presentation === 'structured') {
+    if (session.kind === 'codex-structured') {
       ws.send(JSON.stringify({ type: 'codex-snapshot', snapshot: sessionManager.getCodexSnapshot(sessionId) }));
     }
     
@@ -347,7 +380,7 @@ async function webCommand(options) {
       && (isReconnect || (catchup && catchup.source === 'rendered-history'));
     if (ws.needsTuiRedraw) {
       ws.send(JSON.stringify({ type: 'reset' }));
-    } else if (!(session.kind === 'claude-structured' || (session.kind === 'codex-structured' && session.presentation === 'structured')) && catchup && catchup.data) {
+    } else if (!['claude-structured', 'codex-structured'].includes(session.kind) && catchup && catchup.data) {
       sessionManager.logWsCatchupOutput(sessionId, catchup);
       ws.send(JSON.stringify({ type: 'output', data: catchup.data }));
     }
@@ -358,8 +391,11 @@ async function webCommand(options) {
         if (payload.type === 'input') {
           session.write(payload.data);
         }
+        if (payload.type === 'file-input') {
+          sessionManager.sendTerminalFileInput(sessionId, payload.text || '', payload.fileAttachmentIds || []);
+        }
         if (payload.type === 'claude-input') {
-          sessionManager.sendClaudeInput(sessionId, payload.text || '', payload.attachmentIds || [])
+          sessionManager.sendClaudeInput(sessionId, payload.text || '', payload.attachmentIds || [], payload.fileAttachmentIds || [])
             .catch(error => logger.error(`Claude input error: ${error.message}`));
         }
         if (payload.type === 'claude-permission') {
@@ -378,7 +414,7 @@ async function webCommand(options) {
           sessionManager.abortClaude(sessionId);
         }
         if (payload.type === 'codex-input') {
-          sessionManager.sendCodexInput(sessionId, payload.text || '', payload.attachmentIds || [], payload.skills || [])
+          sessionManager.sendCodexInput(sessionId, payload.text || '', payload.attachmentIds || [], payload.skills || [], payload.fileAttachmentIds || [])
             .catch(error => logger.error(`Codex input error: ${error.message}`));
         }
         if (payload.type === 'codex-permission') {
@@ -398,7 +434,7 @@ async function webCommand(options) {
         }
         if (payload.type === 'codex-detail-request') {
           const codex = sessionManager.get(sessionId);
-          if (codex && codex.kind === 'codex-structured' && codex.presentation === 'structured') {
+          if (codex && codex.kind === 'codex-structured') {
             ws.send(JSON.stringify({
               type: 'codex-detail-response',
               requestId: payload.requestId || null,
@@ -475,7 +511,9 @@ async function webCommand(options) {
   const webAssets = [
     'gitgraph.js',
     'styles.css',
+    'theme.js',
     'core.js',
+    'layout.js',
     'notifications.js',
     'claude.js',
     'schedules.js',

package/lib/server/routes/providers.js

@@ -104,18 +104,6 @@ function registerProviderRoutes(app, { sessionManager }) {
     }
   });
 
-  app.post('/api/sessions/:id/codex-presentation', async (req, res) => {
-    const presentation = req.body?.presentation;
-    if (!['terminal', 'structured'].includes(presentation)) return res.status(400).json({ error: 'Invalid presentation' });
-    try {
-      const success = await sessionManager.switchCodexPresentation(req.params.id, presentation);
-      if (!success) return res.status(409).json({ error: 'Codex session cannot switch presentation now' });
-      res.json({ success: true });
-    } catch (error) {
-      res.status(409).json({ error: error.message });
-    }
-  });
-
   app.post('/api/debug/client-log', (req, res) => {
     const { sessionId, event, payload } = req.body || {};
     sessionManager.logClientDebug(sessionId, event, payload);

package/lib/session/file-attachment-store.js

@@ -0,0 +1,168 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { v4: uuidv4 } = require('uuid');
+
+const MAX_BYTES = 50 * 1024 * 1024;
+const MAX_PER_SESSION = 8;
+const MAX_CHUNKS = 128;
+const CLEANUP_DELAY_MS = 30 * 60 * 1000;
+
+function inputError(message, statusCode = 400) {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  return error;
+}
+
+function safeUploadId(value) {
+  return typeof value === 'string' && /^[a-zA-Z0-9-]{8,100}$/.test(value);
+}
+
+function safeFileName(value) {
+  let decoded = String(value || 'attachment.bin');
+  try { decoded = decodeURIComponent(decoded); } catch (_) {}
+  const base = decoded.replace(/\\/g, '/').split('/').pop() || 'attachment.bin';
+  const cleaned = base.replace(/[\u0000-\u001f\u007f<>:"|?*]/g, '_').trim().slice(0, 160);
+  return cleaned || 'attachment.bin';
+}
+
+class FileAttachmentStore {
+  constructor({ logger, root, uploadRoot } = {}) {
+    this.logger = logger || console;
+    this.root = root || path.join(os.tmpdir(), 'glad', 'session-files');
+    this.uploadRoot = uploadRoot || path.join(os.tmpdir(), 'glad', 'session-file-uploads');
+  }
+
+  assertSession(session) {
+    if (!session) throw inputError('Session not found', 404);
+    if (!session.fileAttachments || !session.fileUploads) throw inputError('File attachments are unavailable for this session');
+  }
+
+  async appendChunk(session, input = {}, bytes) {
+    this.assertSession(session);
+    if (!Buffer.isBuffer(bytes) || bytes.length === 0) throw inputError('File chunk is required');
+    const uploadId = String(input.uploadId || '');
+    const chunkIndex = Number(input.chunkIndex);
+    const chunkTotal = Number(input.chunkTotal);
+    const name = safeFileName(input.name);
+    if (!safeUploadId(uploadId)) throw inputError('Invalid file upload id');
+    if (!Number.isInteger(chunkIndex) || !Number.isInteger(chunkTotal) || chunkIndex < 0 || chunkTotal < 1 || chunkTotal > MAX_CHUNKS || chunkIndex >= chunkTotal) {
+      throw inputError('Invalid file chunk metadata');
+    }
+
+    let upload = session.fileUploads.get(uploadId);
+    if (!upload) {
+      if (chunkIndex !== 0) throw inputError('File upload must start with the first chunk');
+      const directory = path.join(this.uploadRoot, session.id);
+      await fs.promises.mkdir(directory, { recursive: true, mode: 0o700 });
+      upload = { id: uploadId, name, path: path.join(directory, `${uploadId}.part`), chunkTotal, nextChunkIndex: 0, bytes: 0 };
+      session.fileUploads.set(uploadId, upload);
+    }
+    if (upload.name !== name || upload.chunkTotal !== chunkTotal || upload.nextChunkIndex !== chunkIndex) {
+      throw inputError('File chunks arrived out of order');
+    }
+    if (upload.bytes + bytes.length > MAX_BYTES) {
+      await this.discardUpload(session, uploadId);
+      throw inputError('File must be 50 MB or smaller');
+    }
+
+    if (chunkIndex === 0) await fs.promises.writeFile(upload.path, bytes, { mode: 0o600, flag: 'wx' });
+    else await fs.promises.appendFile(upload.path, bytes, { mode: 0o600 });
+    upload.bytes += bytes.length;
+    upload.nextChunkIndex += 1;
+    if (upload.nextChunkIndex < upload.chunkTotal) {
+      return { complete: false, receivedChunks: upload.nextChunkIndex, size: upload.bytes };
+    }
+
+    const pendingAttachmentCount = Array.from(session.fileAttachments.values()).filter(item => !item.sent).length;
+    if (pendingAttachmentCount >= MAX_PER_SESSION) {
+      await this.discardUpload(session, uploadId);
+      throw inputError(`You can attach at most ${MAX_PER_SESSION} files at a time`);
+    }
+    const directory = path.join(this.root, session.id);
+    await fs.promises.mkdir(directory, { recursive: true, mode: 0o700 });
+    const attachment = {
+      id: uuidv4(),
+      name: upload.name,
+      path: path.join(directory, `${uuidv4()}-${upload.name}`),
+      size: upload.bytes,
+      createdAt: Date.now(),
+      cleanupTimer: null
+    };
+    session.fileUploads.delete(uploadId);
+    try {
+      await fs.promises.rename(upload.path, attachment.path);
+      await fs.promises.chmod(attachment.path, 0o600);
+      session.fileAttachments.set(attachment.id, attachment);
+      return { complete: true, attachment: { id: attachment.id, name: attachment.name, size: attachment.size, kind: 'file' } };
+    } catch (error) {
+      await fs.promises.rm(upload.path, { force: true });
+      throw error;
+    }
+  }
+
+  async discardUpload(session, uploadId) {
+    if (!session?.fileUploads || !safeUploadId(uploadId)) return false;
+    const upload = session.fileUploads.get(uploadId);
+    if (!upload) return false;
+    session.fileUploads.delete(uploadId);
+    await fs.promises.rm(upload.path, { force: true });
+    return true;
+  }
+
+  async discardAttachment(session, attachmentId) {
+    if (!session?.fileAttachments) return false;
+    const attachment = session.fileAttachments.get(attachmentId);
+    if (!attachment) return false;
+    clearTimeout(attachment.cleanupTimer);
+    session.fileAttachments.delete(attachmentId);
+    await fs.promises.rm(attachment.path, { force: true });
+    return true;
+  }
+
+  resolve(session, attachmentIds = []) {
+    const ids = Array.isArray(attachmentIds) ? attachmentIds : [];
+    if (!session) throw inputError('Session not found', 404);
+    if (ids.length === 0) return [];
+    this.assertSession(session);
+    if (ids.length > MAX_PER_SESSION) throw inputError(`You can attach at most ${MAX_PER_SESSION} files at a time`);
+    const uniqueIds = [...new Set(ids.map(String))];
+    if (uniqueIds.length !== ids.length) throw inputError('Duplicate file attachment');
+    return uniqueIds.map(attachmentId => {
+      const attachment = session.fileAttachments.get(attachmentId);
+      if (!attachment) throw inputError('File attachment is no longer available');
+      return attachment;
+    });
+  }
+
+  scheduleCleanup(session, attachmentIds) {
+    if (!session?.fileAttachments) return;
+    for (const attachmentId of attachmentIds) {
+      const attachment = session.fileAttachments.get(attachmentId);
+      if (!attachment) continue;
+      attachment.sent = true;
+      clearTimeout(attachment.cleanupTimer);
+      attachment.cleanupTimer = setTimeout(() => {
+        this.discardAttachment(session, attachmentId).catch(error => {
+          this.logger.debugInfo?.(`[file-attachment] cleanup failed: ${error.message}`);
+        });
+      }, CLEANUP_DELAY_MS);
+      attachment.cleanupTimer.unref?.();
+    }
+  }
+
+  clear(session) {
+    if (!session) return;
+    for (const attachment of session.fileAttachments?.values?.() || []) clearTimeout(attachment.cleanupTimer);
+    session.fileAttachments?.clear?.();
+    session.fileUploads?.clear?.();
+    fs.promises.rm(path.join(this.root, session.id), { recursive: true, force: true }).catch(error => {
+      this.logger.debugInfo?.(`[file-attachment] cleanup failed: ${error.message}`);
+    });
+    fs.promises.rm(path.join(this.uploadRoot, session.id), { recursive: true, force: true }).catch(error => {
+      this.logger.debugInfo?.(`[file-upload] cleanup failed: ${error.message}`);
+    });
+  }
+}
+
+module.exports = FileAttachmentStore;