@clawchatsai/connector 0.0.86 → 0.0.87

package/server/controllers/messages.js

@@ -0,0 +1,128 @@
+import { send, sendError, parseBody } from '../util/http.js';
+import { buildContextPreamble } from '../util/context.js';
+
+export class MessageController {
+  constructor({ getActiveDb, getWorkspaces, broadcast }) {
+    this.getActiveDb = getActiveDb;
+    this.getWorkspaces = getWorkspaces;
+    this.broadcast = broadcast;
+  }
+
+  getAll(req, res, params, query) {
+    const db = this.getActiveDb();
+    if (!db.prepare('SELECT id FROM threads WHERE id = ?').get(params.id)) return sendError(res, 404, 'Thread not found');
+    const limit = Math.min(parseInt(query.limit || '100', 10), 500);
+    const before = query.before ? parseInt(query.before, 10) : null;
+    const after = query.after ? parseInt(query.after, 10) : null;
+    let sql = 'SELECT * FROM messages WHERE thread_id = ?';
+    const sqlParams = [params.id];
+    if (before) { sql += ' AND timestamp < ?'; sqlParams.push(before); }
+    if (after) { sql += ' AND timestamp > ?'; sqlParams.push(after); }
+    const total = db.prepare(sql.replace('SELECT *', 'SELECT COUNT(*) as c')).get(...sqlParams).c;
+    const rows = db.prepare(sql + ' ORDER BY timestamp DESC LIMIT ?').all(...sqlParams, limit + 1);
+    const messages = rows.slice(0, limit).reverse();
+    for (const m of messages) { if (m.metadata) { try { m.metadata = JSON.parse(m.metadata); } catch { /* ok */ } } }
+    send(res, 200, { messages, hasMore: rows.length > limit });
+  }
+
+  async create(req, res, params) {
+    const body = await parseBody(req);
+    const db = this.getActiveDb();
+    if (!db.prepare('SELECT id FROM threads WHERE id = ?').get(params.id)) return sendError(res, 404, 'Thread not found');
+    if (!body.id || !body.role || body.content === undefined || !body.timestamp) return sendError(res, 400, 'Required: id, role, content, timestamp');
+    const metadata = body.metadata ? JSON.stringify(body.metadata) : null;
+    const existing = db.prepare('SELECT id, status, metadata FROM messages WHERE id = ?').get(body.id);
+    if (existing) {
+      if (body.status && body.status !== existing.status) {
+        db.prepare('UPDATE messages SET status = ?, content = ?, metadata = ? WHERE id = ?').run(body.status, body.content, metadata || existing.metadata, body.id);
+      }
+    } else {
+      db.prepare('INSERT INTO messages (id, thread_id, role, content, status, metadata, seq, timestamp, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)').run(body.id, params.id, body.role, body.content, body.status || 'sent', metadata, body.seq || null, body.timestamp, Date.now());
+      db.prepare('UPDATE threads SET updated_at = ? WHERE id = ?').run(Date.now(), params.id);
+      if (body.role === 'user' && body.content) {
+        const thread = db.prepare('SELECT title FROM threads WHERE id = ?').get(params.id);
+        if (thread?.title === 'New chat') {
+          const title = body.content.replace(/\n.*/s, '').slice(0, 40).trim() + (body.content.length > 40 ? '...' : '');
+          if (title) {
+            db.prepare('UPDATE threads SET title = ? WHERE id = ?').run(title, params.id);
+            this.broadcast(JSON.stringify({ type: 'clawchats', event: 'thread-title-updated', threadId: params.id, workspace: this.getWorkspaces().active, title }));
+          }
+        }
+      }
+    }
+    const message = db.prepare('SELECT * FROM messages WHERE id = ?').get(body.id);
+    if (message?.metadata) { try { message.metadata = JSON.parse(message.metadata); } catch { /* ok */ } }
+    send(res, existing ? 200 : 201, { message });
+  }
+
+  delete(req, res, params) {
+    const db = this.getActiveDb();
+    if (!db.prepare('SELECT id FROM messages WHERE id = ? AND thread_id = ?').get(params.messageId, params.id)) return sendError(res, 404, 'Message not found');
+    db.prepare('DELETE FROM messages WHERE id = ?').run(params.messageId);
+    send(res, 200, { ok: true });
+  }
+
+  contextFill(req, res, params) {
+    const db = this.getActiveDb();
+    const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+    if (!thread) return sendError(res, 404, 'Thread not found');
+    send(res, 200, buildContextPreamble(db, params.id, thread.last_session_id, thread.session_key));
+  }
+
+  search(req, res, params, query) {
+    const q = query.q || '';
+    if (!q) return send(res, 200, { results: [], total: 0 });
+    const db = this.getActiveDb();
+    const page = parseInt(query.page || '1', 10);
+    const limit = Math.min(parseInt(query.limit || '20', 10), 100);
+    const offset = (page - 1) * limit;
+    try {
+      const results = db.prepare(`SELECT m.id as messageId, m.thread_id as threadId, t.title as threadTitle, m.role, snippet(messages_fts, 0, '<mark>', '</mark>', '...', 40) as content, m.timestamp FROM messages_fts JOIN messages m ON messages_fts.rowid = m.rowid JOIN threads t ON m.thread_id = t.id WHERE messages_fts MATCH ? ORDER BY rank LIMIT ? OFFSET ?`).all(q, limit, offset);
+      const total = db.prepare(`SELECT COUNT(*) as c FROM messages_fts WHERE messages_fts MATCH ?`).get(q).c;
+      send(res, 200, { results, total });
+    } catch { send(res, 200, { results: [], total: 0 }); }
+  }
+
+  export(req, res) {
+    const db = this.getActiveDb();
+    const ws = this.getWorkspaces();
+    const threads = db.prepare('SELECT * FROM threads ORDER BY updated_at DESC').all();
+    send(res, 200, {
+      workspace: ws.active,
+      exportedAt: Date.now(),
+      threads: threads.map(t => {
+        const messages = db.prepare('SELECT * FROM messages WHERE thread_id = ? ORDER BY timestamp ASC').all(t.id);
+        for (const m of messages) { if (m.metadata) { try { m.metadata = JSON.parse(m.metadata); } catch { /* ok */ } } }
+        return { ...t, messages };
+      }),
+    });
+  }
+
+  async import(req, res) {
+    const body = await parseBody(req);
+    const db = this.getActiveDb();
+    const ws = this.getWorkspaces();
+    if (!body.threads || !Array.isArray(body.threads)) return sendError(res, 400, 'Expected { threads: [...] }');
+    let threadsImported = 0, messagesImported = 0;
+    const insertThread = db.prepare('INSERT OR IGNORE INTO threads (id, session_key, title, pinned, pin_order, model, last_session_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    const insertMsg = db.prepare('INSERT OR IGNORE INTO messages (id, thread_id, role, content, status, metadata, seq, timestamp, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    db.exec('BEGIN');
+    try {
+      for (const t of body.threads) {
+        if (!t.id) continue;
+        const sessionKey = t.session_key || `agent:main:${ws.active}:chat:${t.id}`;
+        if (insertThread.run(t.id, sessionKey, t.title || 'Imported chat', t.pinned || 0, t.pin_order || 0, t.model || null, t.last_session_id || null, t.created_at || Date.now(), t.updated_at || Date.now()).changes > 0) threadsImported++;
+        for (const m of (t.messages || [])) {
+          if (!m.id || !m.role) continue;
+          const meta = m.metadata ? (typeof m.metadata === 'string' ? m.metadata : JSON.stringify(m.metadata)) : null;
+          if (insertMsg.run(m.id, t.id, m.role, m.content || '', m.status || 'sent', meta, m.seq || null, m.timestamp || Date.now(), m.created_at || Date.now()).changes > 0) messagesImported++;
+        }
+      }
+      db.exec('COMMIT');
+    } catch (e) {
+      db.exec('ROLLBACK');
+      throw e;
+    }
+    send(res, 200, { ok: true, threadsImported, messagesImported });
+  }
+}

package/server/controllers/threads.js

@@ -0,0 +1,113 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { send, sendError, parseBody, uuid } from '../util/http.js';
+import { syncThreadUnreadCount } from '../util/helpers.js';
+import { getSessionsDirForAgent } from '../config.js';
+import { cleanGatewaySession } from '../gateway-cleanup.js';
+
+export class ThreadController {
+  constructor({ getActiveDb, getWorkspaces, uploadsDir, broadcast }) {
+    this.getActiveDb = getActiveDb;
+    this.getWorkspaces = getWorkspaces;
+    this.uploadsDir = uploadsDir;
+    this.broadcast = broadcast;
+  }
+
+  getAll(req, res, params, query) {
+    const db = this.getActiveDb();
+    const page = parseInt(query.page || '1', 10);
+    const limit = Math.min(parseInt(query.limit || '50', 10), 200);
+    const offset = (page - 1) * limit;
+    const search = query.search || '';
+    let threads, total;
+    if (search) {
+      try {
+        const matchingIds = db.prepare(`SELECT DISTINCT m.thread_id FROM messages m JOIN messages_fts ON messages_fts.rowid = m.rowid WHERE messages_fts MATCH ?`).all(search).map(r => r.thread_id);
+        if (!matchingIds.length) return send(res, 200, { threads: [], total: 0, page });
+        const ph = matchingIds.map(() => '?').join(',');
+        total = db.prepare(`SELECT COUNT(*) as c FROM threads WHERE id IN (${ph})`).get(...matchingIds).c;
+        threads = db.prepare(`SELECT * FROM threads WHERE id IN (${ph}) ORDER BY pinned DESC, sort_order DESC, updated_at DESC LIMIT ? OFFSET ?`).all(...matchingIds, limit, offset);
+      } catch { return send(res, 200, { threads: [], total: 0, page }); }
+    } else {
+      total = db.prepare('SELECT COUNT(*) as c FROM threads').get().c;
+      threads = db.prepare('SELECT * FROM threads ORDER BY pinned DESC, sort_order DESC, updated_at DESC LIMIT ? OFFSET ?').all(limit, offset);
+    }
+    send(res, 200, { threads, total, page });
+  }
+
+  getUnread(req, res) {
+    const db = this.getActiveDb();
+    const threads = db.prepare(`SELECT t.id, t.title, t.unread_count, m.content as lastMessage FROM threads t LEFT JOIN messages m ON m.thread_id = t.id WHERE t.unread_count > 0 AND m.timestamp = (SELECT MAX(timestamp) FROM messages WHERE thread_id = t.id) ORDER BY t.updated_at DESC`).all();
+    for (const t of threads) t.unreadMessageIds = db.prepare('SELECT message_id FROM unread_messages WHERE thread_id = ?').all(t.id).map(r => r.message_id);
+    send(res, 200, { threads });
+  }
+
+  async markRead(req, res, params) {
+    const { messageIds } = await parseBody(req);
+    if (!Array.isArray(messageIds) || !messageIds.length) return send(res, 400, { error: 'messageIds array required' });
+    const db = this.getActiveDb();
+    const ph = messageIds.map(() => '?').join(',');
+    db.prepare(`DELETE FROM unread_messages WHERE thread_id = ? AND message_id IN (${ph})`).run(params.id, ...messageIds);
+    const remaining = syncThreadUnreadCount(db, params.id);
+    this.broadcast(JSON.stringify({ type: 'clawchats', event: 'unread-update', workspace: this.getWorkspaces().active, threadId: params.id, action: 'read', messageIds, unreadCount: remaining, timestamp: Date.now() }));
+    send(res, 200, { unread_count: remaining });
+  }
+
+  async create(req, res) {
+    const body = await parseBody(req);
+    const db = this.getActiveDb();
+    const ws = this.getWorkspaces();
+    const id = body.id || uuid();
+    const now = Date.now();
+    const agent = ws.workspaces[ws.active]?.agent || 'main';
+    try {
+      db.prepare('INSERT INTO threads (id, session_key, title, created_at, updated_at) VALUES (?, ?, ?, ?, ?)').run(id, `agent:${agent}:${ws.active}:chat:${id}`, 'New chat', now, now);
+    } catch (e) {
+      if (e.message.includes('UNIQUE constraint')) return sendError(res, 409, 'Thread already exists');
+      throw e;
+    }
+    send(res, 201, { thread: db.prepare('SELECT * FROM threads WHERE id = ?').get(id) });
+  }
+
+  get(req, res, params) {
+    const thread = this.getActiveDb().prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+    if (!thread) return sendError(res, 404, 'Thread not found');
+    send(res, 200, { thread });
+  }
+
+  async update(req, res, params) {
+    const body = await parseBody(req);
+    const db = this.getActiveDb();
+    if (!db.prepare('SELECT id FROM threads WHERE id = ?').get(params.id)) return sendError(res, 404, 'Thread not found');
+    const fields = [], values = [];
+    for (const [col, val] of [['title', body.title], ['model', body.model], ['last_session_id', body.last_session_id], ['unread_count', body.unread_count]]) {
+      if (val !== undefined) { fields.push(`${col} = ?`); values.push(val); }
+    }
+    if (body.pinned !== undefined) { fields.push('pinned = ?'); values.push(body.pinned ? 1 : 0); }
+    if (body.pin_order !== undefined) { fields.push('pin_order = ?'); values.push(body.pin_order); }
+    if (body.sort_order !== undefined) { fields.push('sort_order = ?'); values.push(body.sort_order); }
+    if (fields.length) {
+      fields.push('updated_at = ?');
+      values.push(Date.now(), params.id);
+      db.prepare(`UPDATE threads SET ${fields.join(', ')} WHERE id = ?`).run(...values);
+    }
+    send(res, 200, { thread: db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id) });
+  }
+
+  delete(req, res, params) {
+    const db = this.getActiveDb();
+    const thread = db.prepare('SELECT * FROM threads WHERE id = ?').get(params.id);
+    if (!thread) return sendError(res, 404, 'Thread not found');
+    db.prepare('DELETE FROM threads WHERE id = ?').run(params.id);
+    const agentMatch = (thread.session_key || '').match(/^agent:([^:]+):/);
+    const sessionsDir = getSessionsDirForAgent(agentMatch?.[1]);
+    let sessionIdToDelete = thread.last_session_id;
+    if (!sessionIdToDelete) {
+      try { sessionIdToDelete = JSON.parse(fs.readFileSync(path.join(sessionsDir, 'sessions.json'), 'utf8'))[thread.session_key]?.sessionId; } catch { /* ok */ }
+    }
+    cleanGatewaySession(thread.session_key);
+    if (sessionIdToDelete) { try { fs.unlinkSync(path.join(sessionsDir, `${sessionIdToDelete}.jsonl`)); } catch { /* ok */ } }
+    try { fs.rmSync(path.join(this.uploadsDir, params.id), { recursive: true }); } catch { /* ok */ }
+    send(res, 200, { ok: true });
+  }
+}

package/server/controllers/transcribe.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { send } from '../util/http.js';
+
+export async function handleTranscribe(req, res) {
+  try {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    const audioBuffer = Buffer.concat(chunks);
+
+    if (audioBuffer.length === 0) return send(res, 400, { error: 'No audio data' });
+    if (audioBuffer.length > 25 * 1024 * 1024) return send(res, 400, { error: 'Audio too large (max 25MB)' });
+
+    let apiKey;
+    try {
+      const ocConfig = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.openclaw', 'openclaw.json'), 'utf8'));
+      apiKey = ocConfig?.skills?.entries?.['openai-whisper-api']?.apiKey;
+    } catch { /* ok */ }
+    if (!apiKey) apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) return send(res, 500, { error: 'No OpenAI API key configured' });
+
+    const contentType = req.headers['content-type'] || 'audio/webm';
+    const ext = contentType.includes('wav') ? 'wav' : contentType.includes('mp4') || contentType.includes('m4a') ? 'm4a' : contentType.includes('ogg') ? 'ogg' : 'webm';
+
+    const boundary = '----WhisperBoundary' + Date.now();
+    const body = Buffer.concat([
+      `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="audio.${ext}"\r\nContent-Type: ${contentType}\r\n\r\n`,
+      audioBuffer,
+      `\r\n--${boundary}\r\nContent-Disposition: form-data; name="model"\r\n\r\nwhisper-1\r\n`,
+      `--${boundary}\r\nContent-Disposition: form-data; name="response_format"\r\n\r\njson\r\n`,
+      `--${boundary}--\r\n`,
+    ].map(p => typeof p === 'string' ? Buffer.from(p) : p));
+
+    const resp = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': `multipart/form-data; boundary=${boundary}` },
+      body,
+    });
+
+    if (!resp.ok) {
+      console.error('Whisper API error:', resp.status, await resp.text());
+      return send(res, 502, { error: `Whisper API error: ${resp.status}` });
+    }
+    const result = await resp.json();
+    return send(res, 200, { text: result.text || '' });
+  } catch (err) {
+    console.error('Transcribe error:', err);
+    return send(res, 500, { error: err.message });
+  }
+}

package/server/controllers/workspaces.js

@@ -0,0 +1,102 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { send, sendError, parseBody } from '../util/http.js';
+import { validateAgent } from '../config.js';
+import { cleanGatewaySession, cleanGatewaySessionsByPrefix } from '../gateway-cleanup.js';
+
+export class WorkspaceController {
+  constructor({ getDb, closeDb, getWorkspaces, setWorkspaces, dataDir, broadcast }) {
+    this.getDb = getDb;
+    this.closeDb = closeDb;
+    this.getWorkspaces = getWorkspaces;
+    this.setWorkspaces = setWorkspaces;
+    this.dataDir = dataDir;
+    this.broadcast = broadcast;
+  }
+
+  getAll(req, res) {
+    const ws = this.getWorkspaces();
+    const sorted = Object.values(ws.workspaces).sort((a, b) => (a.order ?? 999) - (b.order ?? 999));
+    for (const workspace of sorted) {
+      try {
+        workspace.unread_count = this.getDb(workspace.name).prepare('SELECT COALESCE(SUM(unread_count), 0) as total FROM threads').get().total;
+      } catch { workspace.unread_count = 0; }
+    }
+    send(res, 200, { active: ws.active, workspaces: sorted });
+  }
+
+  async create(req, res) {
+    const body = await parseBody(req);
+    const { name, label } = body;
+    if (!name || !/^[a-z0-9-]{1,32}$/.test(name)) return sendError(res, 400, 'Name must be [a-z0-9-], 1-32 chars');
+    const ws = this.getWorkspaces();
+    if (ws.workspaces[name]) return sendError(res, 409, 'Workspace already exists');
+    let agent = 'main';
+    try { agent = validateAgent(body.agent || 'main'); } catch { agent = 'main'; }
+    ws.workspaces[name] = { name, label: label || name, color: body.color || null, icon: body.icon || null, agent, createdAt: Date.now() };
+    this.setWorkspaces(ws);
+    this.getDb(name);
+    send(res, 201, { workspace: ws.workspaces[name] });
+  }
+
+  async update(req, res, params) {
+    const body = await parseBody(req);
+    const ws = this.getWorkspaces();
+    if (!ws.workspaces[params.name]) return sendError(res, 404, 'Workspace not found');
+    if (body.label !== undefined) ws.workspaces[params.name].label = body.label;
+    if (body.color !== undefined) ws.workspaces[params.name].color = body.color;
+    if (body.icon !== undefined) ws.workspaces[params.name].icon = body.icon;
+    if (body.lastThread !== undefined) ws.workspaces[params.name].lastThread = body.lastThread;
+    let migratedThreads = 0;
+    if (body.agent !== undefined) {
+      let newAgent;
+      try { newAgent = validateAgent(body.agent); } catch (e) { return sendError(res, 400, e.message); }
+      const oldAgent = ws.workspaces[params.name].agent || 'main';
+      if (newAgent !== oldAgent) {
+        const db = this.getDb(params.name);
+        const threads = db.prepare(`SELECT id, session_key FROM threads WHERE session_key LIKE ?`).all(`agent:${oldAgent}:${params.name}:chat:%`);
+        db.prepare(`UPDATE threads SET session_key = replace(session_key, 'agent:' || ? || ':' || ? || ':chat:', 'agent:' || ? || ':' || ? || ':chat:') WHERE session_key LIKE 'agent:' || ? || ':' || ? || ':chat:%'`).run(oldAgent, params.name, newAgent, params.name, oldAgent, params.name);
+        for (const t of threads) cleanGatewaySession(t.session_key);
+        ws.workspaces[params.name].agent = newAgent;
+        migratedThreads = threads.length;
+        this.broadcast(JSON.stringify({ type: 'clawchats', event: 'workspace-agent-changed', workspace: params.name, agent: newAgent }));
+      }
+    }
+    this.setWorkspaces(ws);
+    send(res, 200, { workspace: ws.workspaces[params.name], migratedThreads });
+  }
+
+  delete(req, res, params) {
+    const ws = this.getWorkspaces();
+    if (!ws.workspaces[params.name]) return sendError(res, 404, 'Workspace not found');
+    if (Object.keys(ws.workspaces).length <= 1) return sendError(res, 400, 'Cannot delete the only workspace');
+    this.closeDb(params.name);
+    const dbPath = path.join(this.dataDir, `${params.name}.db`);
+    for (const suffix of ['', '-wal', '-shm']) { try { fs.unlinkSync(dbPath + suffix); } catch { /* ok */ } }
+    const wsAgent = ws.workspaces[params.name]?.agent || 'main';
+    const cleaned = cleanGatewaySessionsByPrefix(`agent:${wsAgent}:${params.name}:chat:`);
+    if (cleaned > 0) console.log(`Cleaned ${cleaned} gateway sessions for workspace: ${params.name}`);
+    delete ws.workspaces[params.name];
+    if (ws.active === params.name) ws.active = Object.keys(ws.workspaces)[0] || null;
+    this.setWorkspaces(ws);
+    send(res, 200, { ok: true });
+  }
+
+  async reorder(req, res) {
+    const body = await parseBody(req);
+    if (!Array.isArray(body.order)) return sendError(res, 400, 'order must be an array of workspace names');
+    const ws = this.getWorkspaces();
+    body.order.forEach((name, i) => { if (ws.workspaces[name]) ws.workspaces[name].order = i; });
+    this.setWorkspaces(ws);
+    send(res, 200, { ok: true, workspaces: Object.values(ws.workspaces) });
+  }
+
+  activate(req, res, params) {
+    const ws = this.getWorkspaces();
+    if (!ws.workspaces[params.name]) return sendError(res, 404, 'Workspace not found');
+    ws.active = params.name;
+    this.setWorkspaces(ws);
+    this.getDb(params.name);
+    send(res, 200, { ok: true, workspace: ws.workspaces[params.name] });
+  }
+}

package/server/debug.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export class DebugLogger {
+  constructor(baseDir) {
+    this.baseDir = path.join(baseDir, '..', 'debug');
+    this.active = false;
+    this.sessionId = null;
+    this.wsStream = null;
+    this.originatingClient = null;
+  }
+
+  start(ts, originatingClient) {
+    if (this.active) return { error: 'already-active', sessionId: this.sessionId };
+    this.sessionId = ts.replace(/[:.]/g, '-');
+    this.originatingClient = originatingClient;
+    fs.mkdirSync(this.baseDir, { recursive: true });
+    this.wsStream = fs.createWriteStream(path.join(this.baseDir, `session-${this.sessionId}-ws.log`), { flags: 'a' });
+    this.active = true;
+    console.log(`Debug recording started: ${this.sessionId}`);
+    return { sessionId: this.sessionId };
+  }
+
+  logFrame(direction, data) {
+    if (this.active && this.wsStream) this.wsStream.write(`${new Date().toISOString()} ${direction} ${data}\n`);
+  }
+
+  saveDump(payload) {
+    if (!this.sessionId) return { sessionId: null, files: [] };
+    const files = [];
+    const id = this.sessionId;
+    if (this.wsStream) { this.wsStream.end(); this.wsStream = null; files.push(`session-${id}-ws.log`); }
+
+    let logContent = '';
+    for (const entry of (payload.console || [])) {
+      logContent += `${entry.ts} [${entry.level.toUpperCase()}] ${entry.args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ')}\n`;
+    }
+    for (const err of (payload.errors || [])) logContent += `${err.ts} [UNHANDLED] ${err.message}\n${err.stack || ''}\n`;
+    if (logContent) { fs.writeFileSync(path.join(this.baseDir, `session-${id}-client.log`), logContent); files.push(`session-${id}-client.log`); }
+    if (payload.state) { fs.writeFileSync(path.join(this.baseDir, `session-${id}-state.json`), JSON.stringify(payload.state, null, 2)); files.push(`session-${id}-state.json`); }
+    if (payload.screenshot) { fs.writeFileSync(path.join(this.baseDir, `session-${id}-screenshot.jpg`), Buffer.from(payload.screenshot, 'base64')); files.push(`session-${id}-screenshot.jpg`); }
+
+    const savedId = id;
+    this.active = false; this.sessionId = null; this.originatingClient = null;
+    console.log(`Debug session saved: ${files.join(', ')}`);
+    return { sessionId: savedId, files };
+  }
+
+  handleClientDisconnect(ws) {
+    if (this.active && this.originatingClient === ws) {
+      console.log(`Debug session ${this.sessionId} auto-closed: client disconnected`);
+      if (this.wsStream) { this.wsStream.write(`${new Date().toISOString()} SYSTEM Client disconnected — session auto-closed\n`); this.wsStream.end(); this.wsStream = null; }
+      this.active = false; this.sessionId = null; this.originatingClient = null;
+    }
+  }
+}

package/server/gateway-cleanup.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getSessionsDirForAgent } from './config.js';
+
+export function cleanGatewaySession(sessionKey) {
+  try {
+    const agentMatch = (sessionKey || '').match(/^agent:([^:]+):/);
+    const sessionsDir = getSessionsDirForAgent(agentMatch?.[1]);
+    const sessionsPath = path.join(sessionsDir, 'sessions.json');
+    const store = JSON.parse(fs.readFileSync(sessionsPath, 'utf8'));
+    const entry = store[sessionKey];
+    if (!entry) return null;
+    if (entry.sessionId) {
+      try { fs.unlinkSync(path.join(sessionsDir, `${entry.sessionId}.jsonl`)); } catch { /* ok */ }
+    }
+    const sessionId = entry.sessionId || null;
+    delete store[sessionKey];
+    fs.writeFileSync(sessionsPath, JSON.stringify(store, null, 2));
+    return sessionId;
+  } catch (err) {
+    console.warn(`cleanGatewaySession(${sessionKey}):`, err.message);
+    return null;
+  }
+}
+
+export function cleanGatewaySessionsByPrefix(prefix) {
+  try {
+    const agentMatch = (prefix || '').match(/^agent:([^:]+):/);
+    const sessionsDir = getSessionsDirForAgent(agentMatch?.[1]);
+    const sessionsPath = path.join(sessionsDir, 'sessions.json');
+    const store = JSON.parse(fs.readFileSync(sessionsPath, 'utf8'));
+    let cleaned = 0;
+    for (const key of Object.keys(store)) {
+      if (!key.startsWith(prefix)) continue;
+      if (store[key]?.sessionId) {
+        try { fs.unlinkSync(path.join(sessionsDir, `${store[key].sessionId}.jsonl`)); } catch { /* ok */ }
+      }
+      delete store[key];
+      cleaned++;
+    }
+    if (cleaned > 0) fs.writeFileSync(sessionsPath, JSON.stringify(store, null, 2));
+    return cleaned;
+  } catch (err) {
+    console.warn(`cleanGatewaySessionsByPrefix(${prefix}):`, err.message);
+    return 0;
+  }
+}