wtt-connect 0.2.11 → 0.2.14

package/README.md

@@ -21,7 +21,6 @@ Implemented production-oriented surfaces:
   - `acp` for any Agent Client Protocol compatible agent
   - `devin` through ACP (`devin acp`)
 - Normalized tool/progress event publishing
-- OpenDesign visual artifact generation for formula/principle/process/UI explanations, with a quality gate that checks for dense structure, SVG/canvas diagrams, animation, examples, and formula/metric explanation before upload
 - TTS extension point:
   - `none`
   - `macos-say` using the macOS `say` command, emitted as WAV when upload is enabled
@@ -122,10 +121,19 @@ Codex, Claude Code, and other adapters can generate user-facing files on the age
 Supported generated artifact types:
 
 ```text
-.doc .docx .ppt .pptx .xls .xlsx .pdf .csv .md .txt .zip
+.doc .docx .ppt .pptx .xls .xlsx .pdf .csv .md .txt .zip .html .png .jpg .webp .mp4 .webm .mov
 ```
 
-When an agent creates a deliverable file, it should save the file under its workspace or artifact directory and include one final-response marker per file:
+When an agent creates a deliverable file, it can save the file anywhere under its own WTT workspace (`~/.wtt-connect/<agentID>` by default, or `WTT_CONNECT_WORKDIR` when set). The agent should then explicitly publish it with:
+
+```bash
+wtt-connect upload-file --topic-id <topic_id> --title "Project Report" ./report.pdf
+wtt-connect upload-file --topic-id <topic_id> --title "Design Pack" ./a.pdf ./slides.pptx ./notes.md
+```
+
+`upload-file` uploads the file through WTT media and publishes a clickable file card into the topic. If several files are passed, it packages them into one zip before publishing. `wtt-connect` does not scan the workspace automatically.
+
+Agents can also include one final-response marker per file to provide a better display title:
 
 ```text
 [WTT_ARTIFACT_FILE path="report.docx" title="Project Report"]
@@ -140,7 +148,7 @@ When an agent creates a deliverable file, it should save the file under its work
 
 Notes:
 
-- Generated file markers are explicit user-facing uploads; they are uploaded even when `WTT_CONNECT_UPLOAD_ARTIFACTS=0`.
+- Generated files published through `upload-file` and explicit markers are user-facing uploads; they are uploaded even when `WTT_CONNECT_UPLOAD_ARTIFACTS=0`.
 - Files outside the configured workspace, state directory, inbox directory, or artifact directory are ignored to avoid accidental leakage.
 - `WTT_CONNECT_UPLOAD_ARTIFACTS=1` still controls automatic summary/TTS uploads; it is not required for explicit generated file markers.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtt-connect",
-  "version": "0.2.11",
+  "version": "0.2.14",
   "private": false,
   "description": "WTT-native connector daemon for Codex, Claude Code, Cursor, Gemini, ACP, and other coding agent surfaces.",
   "type": "module",

package/src/main.js

@@ -1,4 +1,6 @@
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 import { loadDefaultEnvFiles } from './env.js';
 import { loadConfig } from './config.js';
 import { Runner } from './runner.js';
@@ -7,6 +9,7 @@ import { setup } from './setup.js';
 import { smokeChat, smokeTask } from './smoke.js';
 import { ArtifactManager } from './artifacts.js';
 import { DurableStore } from './store.js';
+import { WTTClient } from './wtt-client.js';
 import { log, redact } from './logger.js';
 import { adapterBin, normalizeProfileName } from './adapters/generic-cli.js';
 import { normalizeAdapterName } from './adapters/index.js';
@@ -30,6 +33,7 @@ export async function main(args) {
   if (cmd === 'claim-code') return setup(loadConfig(argv), { ...argv, noRegister: true, claimCode: true });
   if (cmd === 'smoke-task') return smokeTask(loadConfig(argv), argv);
   if (cmd === 'smoke-chat') return smokeChat(loadConfig(argv), argv);
+  if (cmd === 'upload-file' || cmd === 'send-file') return uploadFile(loadConfig(argv), argv);
   if (cmd === 'upload-artifact' || cmd === 'opendesign-upload') return uploadArtifact(loadConfig(argv), argv);
   if (cmd === 'start') {
     const config = loadConfig(argv);
@@ -73,6 +77,14 @@ function parseArgs(args) {
     else if (a === '--expected') out.expected = args[++i];
     else if (a === '--prompt') out.prompt = args[++i];
     else if (a === '--message') out.message = args[++i];
+    else if (a === '--topic-id' || a === '--topic') out.topicId = args[++i];
+    else if (a === '--file') {
+      if (!out.files) out.files = [];
+      out.files.push(args[++i]);
+    }
+    else if (a === '--zip') out.zip = true;
+    else if (a === '--no-zip') out.noZip = true;
+    else if (a === '--semantic-type') out.semanticType = args[++i];
     else if (a === '--dir') out.dir = args[++i];
     else if (a === '--source') out.source = args[++i];
     else if (a === '--source-id') out.sourceId = args[++i];
@@ -111,6 +123,8 @@ Commands:
   smoke-task                     Create/run a WTT task and wait for connector result
   smoke-chat                     Send P2P chat from smoke sender and wait for reply
   claim-code                     Print claim code for current WTT_AGENT_ID/TOKEN
+  upload-file --topic-id <id> <file...>
+                                  Upload generated file(s) and publish WTT file card
   upload-artifact --dir <path>  Upload an OpenDesign/artifact directory to WTT
   opendesign-upload --dir <path>
                                   Alias for upload-artifact
@@ -118,6 +132,83 @@ Commands:
 `);
 }
 
+async function uploadFile(config, argv) {
+  const topicId = String(argv.topicId || argv.sourceId || '').trim();
+  if (!topicId) throw new Error('upload-file requires --topic-id <topic_id>');
+  const rawFiles = [...(argv.files || []), ...(argv._ || [])].map((file) => String(file || '').trim()).filter(Boolean);
+  if (!rawFiles.length) throw new Error('upload-file requires at least one file path');
+  const files = rawFiles.map((file) => resolveUploadFilePath(file, config));
+  for (const file of files) {
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) throw new Error(`not a file: ${file}`);
+  }
+
+  const store = new DurableStore(config.storeFile).load();
+  const artifacts = new ArtifactManager(config, store);
+  const wtt = new WTTClient(config, async () => {});
+  try {
+    await wtt.connectForActions();
+    const target = files.length > 1 || argv.zip ? packageUploadFiles(files, config, argv) : { path: files[0], originalFiles: files };
+    const stat = fs.statSync(target.path);
+    const asset = await artifacts.uploadFile(target.path, { force: true });
+    const url = asset?.url || asset?.public_url;
+    if (!url) throw new Error('WTT media upload returned no URL');
+    const title = String(argv.title || '').trim() || path.basename(target.path);
+    const content = `[file:${title}](${url})`;
+    const published = await wtt.publish(topicId, content, argv.semanticType || 'TASK_ARTIFACT', {
+      type: 'generated_file',
+      source: 'agent_upload',
+      source_id: topicId,
+      file_name: title,
+      local_path: target.path,
+      size: asset.size || stat.size,
+      packaged: files.length > 1 || Boolean(argv.zip),
+      original_files: target.originalFiles?.map((file) => path.basename(file)) || undefined,
+    });
+    console.log(JSON.stringify({ ok: true, topic_id: topicId, file: target.path, url, message: published }, null, 2));
+  } finally {
+    await wtt.close();
+  }
+}
+
+function packageUploadFiles(files, config, argv) {
+  if (argv.noZip && files.length === 1) return { path: files[0], originalFiles: files };
+  const dir = config.artifactDir || path.join(config.workDir || process.cwd(), '.wtt-connect', 'artifacts');
+  fs.mkdirSync(dir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const title = String(argv.title || 'agent-files').replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64) || 'agent-files';
+  const zipPath = path.join(dir, `${title}-${stamp}.zip`);
+  const result = spawnSync('zip', ['-j', '-q', zipPath, ...files], { encoding: 'utf8' });
+  if (result.status !== 0) {
+    const detail = result.stderr || result.stdout || `exit ${result.status}`;
+    throw new Error(`failed to package files with zip: ${detail}`);
+  }
+  return { path: zipPath, originalFiles: files };
+}
+
+function resolveUploadFilePath(filePath, config) {
+  const raw = String(filePath || '').trim();
+  if (!raw) throw new Error('empty file path');
+  const expanded = raw.startsWith('~/') ? path.join(process.env.HOME || '', raw.slice(2)) : raw;
+  const base = path.resolve(config.workDir || process.cwd());
+  const resolved = path.resolve(path.isAbsolute(expanded) ? expanded : path.join(base, expanded));
+  const roots = [
+    config.workDir,
+    config.artifactDir,
+    config.storeFile ? path.dirname(config.storeFile) : '',
+    config.inboxDir,
+  ].filter(Boolean).map((root) => path.resolve(root));
+  if (!roots.some((root) => isPathInside(resolved, root))) {
+    throw new Error(`upload-file refused path outside WTT workspace/state roots: ${resolved}`);
+  }
+  return resolved;
+}
+
+function isPathInside(candidate, root) {
+  const rel = path.relative(root, candidate);
+  return rel === '' || (rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
 async function uploadArtifact(config, argv) {
   const dir = argv.dir || argv._[0];
   if (!dir) throw new Error('upload-artifact requires --dir <path>');

package/src/runner.js

@@ -1,7 +1,9 @@
 import { WTTClient } from './wtt-client.js';
+import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
+import { promisify } from 'node:util';
 import { WTTApi } from './wtt-api.js';
 import { SessionManager } from './session-manager.js';
 import { TTSManager } from './tts.js';
@@ -16,12 +18,14 @@ import { log } from './logger.js';
 import { buildRuntimeInfo } from './runtime-info.js';
 import { runShellCommand } from './shell-runner.js';
 import { TerminalSessionManager } from './terminal-session.js';
-import { buildOpenDesignPrompt, buildOpenDesignRepairPrompt, chooseOpenDesignSkills, evaluateOpenDesignArtifact, prepareOpenDesignDir, shouldRenderOpenDesignArtifact } from './opendesign.js';
 
 const TERMINAL_STATUSES = new Set(['review', 'done', 'approved', 'cancelled']);
-const GENERATED_FILE_EXTENSIONS = new Set(['.doc', '.docx', '.ppt', '.pptx', '.xls', '.xlsx', '.pdf', '.csv', '.md', '.txt', '.zip']);
-const AUTO_DETECTED_FILE_EXTENSIONS = '(?:docx?|pptx?|xlsx?|pdf|csv|zip)';
+const GENERATED_FILE_EXTENSIONS = new Set([
+  '.doc', '.docx', '.ppt', '.pptx', '.xls', '.xlsx', '.pdf', '.csv', '.md', '.txt', '.zip',
+  '.html', '.htm', '.png', '.jpg', '.jpeg', '.webp', '.mp4', '.webm', '.mov', '.m4v',
+]);
 const BROADCAST_MENTIONS = new Set(['all', 'everyone', '全体', '所有人']);
+const execFileAsync = promisify(execFile);
 
 export class Runner {
   constructor(config) {
@@ -188,7 +192,7 @@ export class Runner {
         '',
         staged.promptBlock,
         renderTranscriptBlock(transcripts),
-        renderGeneratedFileArtifactInstruction(this.config),
+        renderGeneratedFileArtifactInstruction(this.config, topicId),
         'Reply naturally and concisely unless the user asks for detail.',
       ].filter(Boolean).join('\n');
       const output = await adapter.run(prompt, {
@@ -203,7 +207,6 @@ export class Runner {
       await this.maybeAttachSpeech(topicId, reply, `chat-${topicId}`);
       await this.wtt.publish(topicId, reply, 'CHAT_REPLY');
       await this.publishGeneratedFileArtifacts(topicId, prepared.refs, { source: 'chat', sourceId: topicId, adapter: adapter.name });
-      await this.maybeRenderOpenDesignArtifact(m, reply, adapter);
       log('info', 'chat replied', { topicId, chars: reply.length });
     } catch (err) {
       await this.wtt.publish(topicId, `执行失败：${err.message}`, 'CHAT_REPLY');
@@ -286,73 +289,11 @@ export class Runner {
     }
   }
 
-  async maybeRenderOpenDesignArtifact(message, reply, adapter) {
-    const topicId = String(message.topic_id || '');
-    if (!topicId || !shouldRenderOpenDesignArtifact(message, reply)) return;
-    try {
-      await this.wtt.typing(topicId, 'start', {
-        statusText: 'OpenDesign 正在生成可视化 artifact',
-        statusKind: 'opendesign',
-        adapter: adapter.name,
-        ttlMs: 90000,
-      });
-      const outputDir = await prepareOpenDesignDir(this.config, topicId);
-      const skills = chooseOpenDesignSkills(message, reply);
-      const locale = inferLocale(`${message.content || ''}\n${reply || ''}`);
-      const prompt = await buildOpenDesignPrompt({
-        config: this.config,
-        outputDir,
-        userMessage: message.content || '',
-        reply,
-        topicId,
-        locale,
-        skills,
-      });
-      await adapter.run(prompt, {
-        sessionKey: `wtt:opendesign:${topicId}`,
-        topicId,
-        onProgress: (event) => this.maybePublishProgress(topicId, event, adapter.name),
-      });
-      let quality = await evaluateOpenDesignArtifact(outputDir);
-      if (!quality.ok) {
-        log('warn', 'opendesign artifact quality check failed; requesting rewrite', { topicId, score: quality.score, issues: quality.issues.join('; ') });
-        await this.wtt.typing(topicId, 'start', {
-          statusText: 'OpenDesign 正在重写低质量 artifact',
-          statusKind: 'opendesign_repair',
-          adapter: adapter.name,
-          ttlMs: 120000,
-        });
-        await adapter.run(buildOpenDesignRepairPrompt({ outputDir, issues: quality.issues, locale }), {
-          sessionKey: `wtt:opendesign:${topicId}`,
-          topicId,
-          onProgress: (event) => this.maybePublishProgress(topicId, event, adapter.name),
-        });
-        quality = await evaluateOpenDesignArtifact(outputDir);
-        log(quality.ok ? 'info' : 'warn', 'opendesign artifact quality check after rewrite', { topicId, score: quality.score, issues: quality.issues.join('; ') });
-      }
-      const artifact = await this.artifacts.uploadDirectory(outputDir, {
-        source: messageTopicType(message) || 'feed',
-        sourceId: topicId,
-        title: `OpenDesign · ${topicId.slice(0, 8)}`,
-        entry: 'index.html',
-        type: 'opendesign',
-        metadata: { message_id: message.id || message.message_id || '', generated_by: adapter.name, opendesign_skills: skills },
-      });
-      const previewUrl = webPreviewUrl(artifact.preview_url || artifact.url);
-      if (previewUrl) {
-        const title = artifact.title || 'OpenDesign artifact';
-        await this.wtt.publish(topicId, `[opendesign:${title}](${previewUrl})`, 'TASK_ARTIFACT');
-      }
-      log('info', 'opendesign artifact completed', { topicId, preview: previewUrl });
-    } catch (err) {
-      log('warn', 'opendesign artifact failed', { topicId, error: err.message });
-    }
-  }
-
   async publishGeneratedFileArtifacts(topicId, refs, context = {}) {
     if (!topicId || !Array.isArray(refs) || !refs.length) return [];
     const uploaded = [];
     const seen = new Set();
+    const candidates = [];
     for (const ref of refs) {
       const resolved = resolveGeneratedFilePath(ref.path, this.config);
       if (!resolved || seen.has(resolved)) continue;
@@ -360,16 +301,26 @@ export class Runner {
       try {
         const stat = await fsp.stat(resolved);
         if (!stat.isFile()) continue;
+        candidates.push({ path: resolved, title: ref.title || path.basename(resolved), stat });
+      } catch (err) {
+        log('warn', 'generated file artifact skipped', { topicId, file: ref.path, error: err.message });
+      }
+    }
+
+    const publishTargets = await packageGeneratedFilesIfNeeded(candidates, this.config, context);
+    for (const ref of publishTargets) {
+      try {
         await this.wtt.typing(topicId, 'start', {
-          statusText: `Agent 正在上传生成文件：${path.basename(resolved)}`,
+          statusText: `Agent 正在上传生成文件：${path.basename(ref.path)}`,
           statusKind: 'artifact_upload',
           adapter: context.adapter,
           ttlMs: 60000,
         });
-        const asset = await this.artifacts.uploadFile(resolved, { force: true });
+        const asset = await this.artifacts.uploadFile(ref.path, { force: true });
         const url = asset?.url || asset?.public_url;
         if (!url) continue;
-        const fileName = ref.title || path.basename(resolved);
+        const stat = ref.stat || await fsp.stat(ref.path);
+        const fileName = ref.title || path.basename(ref.path);
         await this.wtt.publish(
           topicId,
           `[file:${fileName}](${url})`,
@@ -379,12 +330,14 @@ export class Runner {
             source: context.source || 'agent',
             source_id: context.sourceId || '',
             file_name: fileName,
-            local_path: resolved,
+            local_path: ref.path,
             mime_type: asset.mime_type || '',
             size: asset.size || stat.size,
+            packaged: Boolean(ref.packaged),
+            original_files: ref.originalFiles || undefined,
           },
         );
-        uploaded.push({ path: resolved, asset });
+        uploaded.push({ path: ref.path, asset });
       } catch (err) {
         log('warn', 'generated file artifact upload failed', { topicId, file: ref.path, error: err.message });
       }
@@ -442,28 +395,44 @@ function adapterDisplayName(name) {
   return name || 'Agent';
 }
 
-function inferLocale(text) {
-  return /[\u4e00-\u9fff]/.test(String(text || '')) ? 'zh' : 'en';
-}
-
-function webPreviewUrl(url) {
-  const text = String(url || '').trim();
-  if (!text) return '';
-  if (text.startsWith('/api/wtt/')) return text;
-  if (text.startsWith('/artifacts/')) return `/api/wtt${text}`;
-  return text;
-}
-
-function renderGeneratedFileArtifactInstruction(config) {
+function renderGeneratedFileArtifactInstruction(config, topicId = '') {
+  const workDir = config.workDir || process.cwd();
+  const uploadCommand = `wtt-connect upload-file --topic-id ${topicId || '<topic_id>'} --title "optional display name" <file-or-files>`;
   return [
     'Generated file artifact rule, for internal execution only:',
-    `- If you create a user-facing file (.docx, .pptx, .xlsx, .pdf, .csv, .zip), save it under the workspace or artifact directory: ${config.artifactDir}.`,
-    '- Include one marker line per generated file in your final response, exactly like: [WTT_ARTIFACT_FILE path="relative/or/absolute/file.docx" title="optional display name"].',
+    `- If you create a user-facing file (.docx, .pptx, .xlsx, .pdf, .csv, .md, .zip, images, or video), save it under your current WTT agent workspace: ${workDir}.`,
+    `- After creating the file, immediately publish it to this WTT conversation by running: ${uploadCommand}`,
+    '- For multiple related files, pass all file paths to one upload-file command; wtt-connect will package them into one zip before publishing.',
+    '- If upload-file is unavailable, include one marker line per generated file in your final response, exactly like: [WTT_ARTIFACT_FILE path="relative/or/absolute/file.docx" title="optional display name"].',
     '- Do not use this marker for source code files, temp files, private logs, credentials, or internal scratch files.',
-    '- wtt-connect will remove the marker from the visible chat and publish a WTT file card.',
+    '- wtt-connect will not scan your workspace automatically; only explicit upload-file commands or marker lines are published as WTT file cards.',
   ].join('\n');
 }
 
+async function packageGeneratedFilesIfNeeded(files, config, context = {}) {
+  if (!files.length) return [];
+  if (files.length === 1) return files;
+  const dir = config.artifactDir || path.join(config.workDir || process.cwd(), '.wtt-connect', 'artifacts');
+  await fsp.mkdir(dir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const sourceId = String(context.sourceId || 'chat').replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 48) || 'chat';
+  const zipPath = path.join(dir, `wtt-generated-${sourceId}-${stamp}.zip`);
+  try {
+    await execFileAsync('zip', ['-j', '-q', zipPath, ...files.map((file) => file.path)], { timeout: 120000 });
+    const stat = await fsp.stat(zipPath);
+    return [{
+      path: zipPath,
+      title: `agent-files-${sourceId}.zip`,
+      stat,
+      packaged: true,
+      originalFiles: files.map((file) => path.basename(file.path)),
+    }];
+  } catch (err) {
+    log('warn', 'generated files zip packaging failed; uploading files individually', { error: err.message, files: files.length });
+    return files;
+  }
+}
+
 function prepareGeneratedFileArtifacts(text) {
   const input = String(text || '');
   const refs = [];
@@ -477,7 +446,6 @@ function prepareGeneratedFileArtifacts(text) {
     if (parsed.path) refs.push(parsed);
     return '';
   });
-  for (const ref of extractLocalFilePathRefs(cleaned)) refs.push(ref);
   return { text: cleaned.replace(/\n{3,}/g, '\n\n').trim(), refs: dedupeArtifactRefs(refs) };
 }
 
@@ -495,17 +463,6 @@ function parseArtifactLine(body) {
   return { path: stripPathPunctuation(parts[0] || ''), title: String(parts[1] || '').trim() };
 }
 
-function extractLocalFilePathRefs(text) {
-  const refs = [];
-  const body = String(text || '');
-  const ext = AUTO_DETECTED_FILE_EXTENSIONS;
-  const pathLike = new RegExp(`(?:^|[\\s"'\\\`(（])((?:~\\/|\\.{1,2}\\/|\\/)[^\\s"'\\\`<>]+?\\.${ext})(?=$|[\\s"'\\\`)）.,;，。；])`, 'gi');
-  for (const m of body.matchAll(pathLike)) refs.push({ path: stripPathPunctuation(m[1]), title: '' });
-  const basename = new RegExp(`\\b([A-Za-z0-9][A-Za-z0-9._-]{0,160}\\.${ext})\\b`, 'gi');
-  for (const m of body.matchAll(basename)) refs.push({ path: stripPathPunctuation(m[1]), title: '' });
-  return refs;
-}
-
 function stripPathPunctuation(value) {
   return String(value || '').trim().replace(/^["'`]+|["'`.,;:，。；：)）\]]+$/g, '');
 }
@@ -532,7 +489,10 @@ function resolveGeneratedFilePath(filePath, config) {
 
   const expanded = raw.startsWith('~/') ? path.join(process.env.HOME || '', raw.slice(2)) : raw;
   const base = path.resolve(config.workDir || process.cwd());
-  const resolved = path.resolve(path.isAbsolute(expanded) ? expanded : path.join(base, expanded));
+  const relativeRoots = [base, config.artifactDir].filter(Boolean).map((root) => path.resolve(root));
+  const resolved = path.resolve(path.isAbsolute(expanded)
+    ? expanded
+    : (relativeRoots.map((root) => path.join(root, expanded)).find((candidate) => fs.existsSync(candidate)) || path.join(base, expanded)));
   const roots = [
     config.workDir,
     config.artifactDir,
@@ -859,7 +819,7 @@ function buildTaskPrompt(task, config, staged = { promptBlock: '' }, transcripts
     renderTranscriptBlock(transcripts),
     '',
     config.requireCommitPush ? 'For code changes, commit and push before final response, and include commit id.' : '',
-    renderGeneratedFileArtifactInstruction(config),
+    renderGeneratedFileArtifactInstruction(config, task.topic_id || task.topicId || ''),
     'Return a concise final summary with evidence, changed files, tests, artifacts, and blockers.',
   ].filter(Boolean).join('\n');
 }

package/src/wtt-client.js

@@ -59,6 +59,31 @@ export class WTTClient {
     }
   }
 
+  async connectForActions(timeoutMs = 15000) {
+    if (!globalThis.WebSocket) throw new Error('Node.js global WebSocket is unavailable; use Node >=22');
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) return;
+    log('info', 'connecting WTT websocket for action', { url: this.config.wttWsUrl, agentId: this.config.agentId });
+    const ws = new WebSocket(this.config.wttWsUrl);
+    this.ws = ws;
+    await onceOpen(ws, timeoutMs);
+    ws.addEventListener('message', (event) => this.handleMessage(String(event.data)).catch((err) => {
+      log('warn', 'WTT websocket action message failed', { error: err?.message || err });
+    }));
+    ws.addEventListener('close', () => {
+      if (this.ws === ws) this.ws = null;
+      for (const [, p] of this.pending) p.reject(new Error('WTT websocket closed'));
+      this.pending.clear();
+    });
+    if (this.config.token) {
+      try {
+        await this.action('auth', { token: this.config.token }, timeoutMs);
+      } catch (err) {
+        log('warn', 'WTT websocket action auth failed; continuing for agent-scoped actions', { error: err?.message || err });
+      }
+    }
+    await this.sendHeartbeat();
+  }
+
   async close() {
     this.closed = true;
     if (this.ws) this.ws.close();

package/systemd/wtt-connect-claude.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=WTT Connect Claude Code Agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=/mnt/wd10t/saiph/wtt/wtt/tools/wtt-connect
+ExecStart=/usr/bin/node --experimental-websocket /mnt/wd10t/saiph/wtt/wtt/tools/wtt-connect/bin/wtt-connect.js start --env-file /mnt/wd10t/saiph/wtt/wtt/tools/wtt-connect/.env.claude
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target

package/systemd/wtt-connect-codex.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=WTT Connect Codex Agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=/mnt/wd10t/saiph/wtt/wtt/tools/wtt-connect
+ExecStart=/usr/bin/node --experimental-websocket /mnt/wd10t/saiph/wtt/wtt/tools/wtt-connect/bin/wtt-connect.js start --env-file /mnt/wd10t/saiph/wtt/wtt/tools/wtt-connect/.env
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target