wtt-connect 0.2.62 → 0.2.64

package/package.json

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

package/src/runner.js

@@ -21,6 +21,7 @@ import { runShellCommand } from './shell-runner.js';
 import { TerminalSessionManager } from './terminal-session.js';
 import { isModelSwitcherEnabled, switchModelProvider } from './model-switcher.js';
 import { formatSlashCommandHelp, isAgentSlashCommand, parseSlashCommand, slashCommandsForAdapter } from './slash.js';
+import { createUsageCollector, taskUsagePatch } from './usage.js';
 
 const TERMINAL_STATUSES = new Set(['review', 'done', 'approved', 'cancelled']);
 const GENERATED_FILE_EXTENSIONS = new Set([
@@ -184,12 +185,14 @@ export class Runner {
     await this.wtt.typing(topicId, 'start', { statusText: 'Agent 已接收消息，正在准备执行', statusKind: 'queued', ttlMs: 30000 });
     let runtimeSelection = null;
     let chatStream = null;
+    let usageCollector = null;
     try {
       const transcripts = await this.transcribeAttachments(staged.files);
       const modelConfig = modelConfigFromMessage(m);
       const adapter = this.registry.select({ ...m, content, model_config: modelConfig });
+      usageCollector = createUsageCollector(adapter.name, modelConfig);
       runtimeSelection = { adapter: adapter.name, modelConfig };
-      chatStream = this.createChatStream(topicId, adapter.name, modelConfig);
+      chatStream = this.createChatStream(topicId, adapter.name, modelConfig, () => usageCollector?.summary());
       await chatStream.start();
       this.recordRuntimeSelection(adapter.name, modelConfig, 'running');
       await this.wtt.typing(topicId, 'start', { statusText: `${adapterDisplayName(adapter.name)} 正在执行${modelConfig.model ? ` · ${modelConfig.model}` : ''}`, statusKind: 'running', adapter: adapter.name, model: modelConfig.model || undefined, ttlMs: 30000 });
@@ -211,18 +214,23 @@ export class Runner {
           modelConfig,
           files: staged.files,
           images: staged.images,
-          onProgress: (event) => this.handleChatProgress(topicId, event, adapter.name, chatStream),
+          onProgress: (event) => {
+            usageCollector?.observe(event);
+            return this.handleChatProgress(topicId, event, adapter.name, chatStream);
+          },
         });
         if (localSlash !== null) {
           const reply = stripHiddenContextLeak(localSlash || '(empty response)') || '(empty response)';
           await chatStream.finish(reply);
           await this.wtt.publish(topicId, reply, 'CHAT_REPLY', chatStream.finalMetadata());
+          await this.reportUsageBestEffort(usageCollector?.summary(), { runId: chatStream.id, topicId, messageId: m.id });
           log('info', 'slash command replied', { topicId, adapter: adapter.name, chars: reply.length });
           return;
         }
       }
+      const skillSlashPrompt = isSlashPassthrough ? this.skillSlashPrompt(content, m.metadata) : '';
       const compactSummary = this.store.getSession(sessionKey).compactSummary || '';
-      const prompt = isSlashPassthrough ? content : [
+      const prompt = isSlashPassthrough ? (skillSlashPrompt || content) : [
         'You are replying to a WTT Web conversation. Do not mention implementation internals unless asked.',
         `WTT topic_id: ${topicId}`,
         `WTT topic_type: ${messageTopicType(m) || 'unknown'}`,
@@ -255,13 +263,17 @@ export class Runner {
         modelConfig,
         files: staged.files,
         images: staged.images,
-        onProgress: (event) => this.handleChatProgress(topicId, event, adapter.name, chatStream),
+        onProgress: (event) => {
+          usageCollector?.observe(event);
+          return this.handleChatProgress(topicId, event, adapter.name, chatStream);
+        },
       });
       const prepared = prepareGeneratedFileArtifacts(stripHiddenContextLeak(output || '(empty response)') || '(empty response)');
       const reply = prepared.text || '(empty response)';
       await chatStream.finish(reply);
       await this.maybeAttachSpeech(topicId, reply, `chat-${topicId}`);
       await this.wtt.publish(topicId, reply, 'CHAT_REPLY', chatStream.finalMetadata());
+      await this.reportUsageBestEffort(usageCollector?.summary(), { runId: chatStream.id, topicId, messageId: m.id });
       await this.publishGeneratedFileArtifacts(topicId, prepared.refs, { source: 'chat', sourceId: topicId, adapter: adapter.name });
       log('info', 'chat replied', { topicId, chars: reply.length });
     } catch (err) {
@@ -284,6 +296,7 @@ export class Runner {
     const transcripts = await this.transcribeAttachments(staged.files);
     const modelConfig = modelConfigFromMessage(task);
     const adapter = this.registry.select({ ...task, model_config: modelConfig });
+    const usageCollector = createUsageCollector(adapter.name, modelConfig);
     this.recordRuntimeSelection(adapter.name, modelConfig, 'running');
     const agentProfile = await this.getAgentProfile();
     if (topicId) await this.wtt.typing(topicId, 'start', { statusText: `${adapterDisplayName(adapter.name)} 正在执行任务${modelConfig.model ? ` · ${modelConfig.model}` : ''}`, statusKind: 'running', adapter: adapter.name, model: modelConfig.model || undefined, ttlMs: 30000 });
@@ -314,14 +327,18 @@ export class Runner {
         modelConfig,
         files: staged.files,
         images: staged.images,
-        onProgress: (ev) => topicId ? this.maybePublishProgress(topicId, ev, adapter.name) : Promise.resolve(),
+        onProgress: (ev) => {
+          usageCollector.observe(ev);
+          return topicId ? this.maybePublishProgress(topicId, ev, adapter.name) : Promise.resolve();
+        },
       });
       const prepared = prepareGeneratedFileArtifacts(output || '(empty response)');
       const summary = prepared.text || '(empty response)';
       await this.maybeRelayArenaOpenCLResult(task, summary);
       const artifact = await this.materializeTaskArtifact(taskId, summary);
       const commitIds = extractCommitIds(summary);
-      const patch = { status: 'review', progress: 100, output: summary, summary, usage_source: `wtt-connect/${adapter.name}` };
+      const usage = usageCollector.summary();
+      const patch = { status: 'review', progress: 100, output: summary, summary, usage_source: `wtt-connect/${adapter.name}`, ...taskUsagePatch(usage) };
       if (commitIds.length) patch.commit_id = commitIds[0];
       await this.api.patchTask(taskId, patch);
       if (topicId) {
@@ -329,6 +346,7 @@ export class Runner {
         await this.publishGeneratedFileArtifacts(topicId, prepared.refs, { source: 'task', sourceId: taskId, adapter: adapter.name });
         if (artifact?.asset?.url) await this.wtt.publish(topicId, `Artifact: ${artifact.asset.url}`, 'TASK_ARTIFACT');
       }
+      await this.reportUsageBestEffort(usage, { runId: `task-${taskId}-${Date.now().toString(36)}`, topicId, taskId });
       log('info', 'task completed', { taskId, chars: summary.length });
     } catch (err) {
       await this.api.patchTask(taskId, { status: 'blocked', output: String(err.message || err) });
@@ -417,6 +435,12 @@ export class Runner {
     return `${adapterDisplayName(adapter.name)} session cleared for this WTT topic. The next turn starts a fresh agent thread/session.`;
   }
 
+  skillSlashPrompt(content, metadata = null) {
+    const runtime = this.runtimeInfo();
+    const commands = Array.isArray(runtime.skill_commands) ? runtime.skill_commands : [];
+    return buildSkillSlashPrompt(content, metadata, commands);
+  }
+
   async compactAdapterSession(adapter, context = {}, command = '/compact', args = '') {
     const sessionKey = context.sessionKey || 'default';
     const topicId = String(context.topicId || '').trim();
@@ -626,7 +650,7 @@ export class Runner {
     }
   }
 
-  createChatStream(topicId, adapterName = 'agent', modelConfig = {}) {
+  createChatStream(topicId, adapterName = 'agent', modelConfig = {}, usageProvider = null) {
     const enabled = this.config.messageStream !== false && Boolean(topicId);
     const streamId = `wtt-${Date.now().toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
     let seq = 0;
@@ -649,11 +673,13 @@ export class Runner {
     return {
       id: streamId,
       finalMetadata() {
+        const usage = typeof usageProvider === 'function' ? usageProvider() : null;
         return {
           stream_id: streamId,
           streamId,
           adapter: adapterName,
           model: modelConfig.model || modelConfig.model_id || modelConfig.modelId || '',
+          ...(usage ? { usage } : {}),
         };
       },
       async start() {
@@ -699,6 +725,17 @@ export class Runner {
     ]);
   }
 
+  async reportUsageBestEffort(usage, { runId = '', topicId = '', taskId = '', messageId = '' } = {}) {
+    if (!usage) return;
+    await this.api.reportAgentUsage({
+      ...usage,
+      run_id: runId,
+      topic_id: topicId,
+      task_id: taskId,
+      message_id: messageId,
+    });
+  }
+
   async maybePublishProgress(topicId, event, adapterName = 'agent') {
     if (!topicId) return;
     const normalized = normalizeAgentEvent(adapterName, event);
@@ -734,6 +771,33 @@ export class Runner {
   }
 }
 
+export function buildSkillSlashPrompt(content, metadata = null, commands = []) {
+  const parsed = parseSlashCommand(content);
+  if (!parsed) return '';
+  const meta = parseMetadata(metadata);
+  const metadataSkillId = String(meta?.skill_id || meta?.skillId || '').trim();
+  const metadataFamily = String(meta?.command_family || meta?.commandFamily || '').trim().toLowerCase();
+  const matched = (Array.isArray(commands) ? commands : []).find((item) => String(item?.cmd || '').trim().toLowerCase() === parsed.command)
+    || (metadataFamily === 'skill' || metadataSkillId ? {
+      cmd: parsed.command,
+      skill_id: metadataSkillId || parsed.command.replace(/^\/+/, ''),
+      name: metadataSkillId || parsed.command.replace(/^\/+/, ''),
+      desc: '',
+    } : null);
+  if (!matched) return '';
+  const skillName = String(matched.name || matched.skill_id || matched.cmd || '').trim().replace(/^\/+/, '');
+  const skillId = String(matched.skill_id || skillName).trim();
+  const args = String(parsed.args || '').trim();
+  return [
+    `Use the ${skillName} skill${skillId && skillId !== skillName ? ` (${skillId})` : ''}.`,
+    matched.desc ? `Skill description: ${matched.desc}` : null,
+    '',
+    args ? `User request: ${args}` : 'User request: Run this skill for the current conversation.',
+    '',
+    `Original slash command: ${content}`,
+  ].filter(Boolean).join('\n');
+}
+
 function adapterDisplayName(name) {
   if (name === 'claude-code') return 'Claude Code';
   if (name === 'codex') return 'Codex';

package/src/runtime-info.js

@@ -3,6 +3,9 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { execFileSync } from 'node:child_process';
 
+let skillCommandCache = { at: 0, commands: [] };
+const SKILL_COMMAND_CACHE_MS = 60_000;
+
 export function buildRuntimeInfo(config, runtimeState = {}) {
   const workdir = resolveWorkDir(config.workDir);
   const git = gitInfo(workdir);
@@ -30,10 +33,145 @@ export function buildRuntimeInfo(config, runtimeState = {}) {
     node: process.version,
     mode: config.mode,
     git,
+    skill_commands: discoverSkillCommands(config, workdir),
     updated_at: new Date().toISOString(),
   };
 }
 
+export function discoverSkillCommands(config = {}, workdir = resolveWorkDir(config.workDir)) {
+  const now = Date.now();
+  if (now - skillCommandCache.at < SKILL_COMMAND_CACHE_MS) return skillCommandCache.commands;
+  const roots = skillRoots(config, workdir);
+  const seenCommands = new Set();
+  const commands = [];
+  for (const root of roots) {
+    for (const skillFile of findSkillFiles(root, 5)) {
+      const parsed = parseSkillFile(skillFile);
+      if (!parsed.id) continue;
+      const commandName = normalizeSkillCommandName(parsed.name || parsed.id);
+      if (!commandName) continue;
+      const cmd = `/${commandName}`;
+      const key = cmd.toLowerCase();
+      if (seenCommands.has(key)) continue;
+      seenCommands.add(key);
+      commands.push({
+        cmd,
+        desc: parsed.description || `Use ${parsed.name || parsed.id} skill`,
+        family: 'skill',
+        mode: 'passthrough',
+        skill_id: parsed.id,
+        name: parsed.name || parsed.id,
+        source: parsed.source,
+      });
+      if (commands.length >= 120) break;
+    }
+    if (commands.length >= 120) break;
+  }
+  skillCommandCache = { at: now, commands };
+  return commands;
+}
+
+function skillRoots(config = {}, workdir = '') {
+  const home = os.homedir();
+  const roots = [
+    path.join(home, '.codex', 'skills'),
+    path.join(home, '.agents', 'skills'),
+    path.join(home, '.claude', 'skills'),
+    path.join(home, '.claude', 'mattpocock-skills', 'skills'),
+    workdir ? path.join(workdir, '.codex', 'skills') : '',
+    workdir ? path.join(workdir, '.claude', 'skills') : '',
+    process.cwd() ? path.join(process.cwd(), '.codex', 'skills') : '',
+    process.cwd() ? path.join(process.cwd(), '.claude', 'skills') : '',
+  ];
+  const extra = String(process.env.WTT_CONNECT_SKILL_ROOTS || config.skillRoots || '').split(path.delimiter);
+  return Array.from(new Set(
+    [...roots, ...extra]
+      .map((item) => String(item || '').trim())
+      .filter(Boolean)
+      .map((item) => path.resolve(item))
+  ));
+}
+
+function findSkillFiles(root, maxDepth = 4) {
+  const out = [];
+  if (!root || !fs.existsSync(root)) return out;
+  const visit = (dir, depth) => {
+    if (depth < 0 || out.length >= 160) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    if (entries.some((entry) => entry.isFile() && entry.name === 'SKILL.md')) {
+      out.push(path.join(dir, 'SKILL.md'));
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'node_modules' || entry.name.startsWith('.git')) continue;
+      visit(path.join(dir, entry.name), depth - 1);
+      if (out.length >= 160) return;
+    }
+  };
+  visit(root, maxDepth);
+  return out;
+}
+
+function parseSkillFile(file) {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    const fallbackId = path.basename(path.dirname(file));
+    const frontmatter = text.match(/^---\s*\n([\s\S]*?)\n---/);
+    const meta = frontmatter ? parseSimpleYaml(frontmatter[1]) : {};
+    const id = String(meta.name || fallbackId || '').trim();
+    return {
+      id,
+      name: id,
+      description: String(meta.description || firstMarkdownSentence(text) || '').trim(),
+      source: sourceForSkillPath(file),
+    };
+  } catch {
+    return { id: '', name: '', description: '', source: 'local' };
+  }
+}
+
+function parseSimpleYaml(text) {
+  const out = {};
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const match = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1];
+    let value = match[2].trim();
+    value = value.replace(/^['"]|['"]$/g, '');
+    out[key] = value;
+  }
+  return out;
+}
+
+function firstMarkdownSentence(text) {
+  const body = String(text || '').replace(/^---\s*\n[\s\S]*?\n---/, '').trim();
+  const line = body.split(/\r?\n/).map((item) => item.trim().replace(/^#+\s*/, '')).find(Boolean);
+  return line || '';
+}
+
+function normalizeSkillCommandName(value) {
+  const raw = String(value || '').trim().split(':').pop() || '';
+  return raw
+    .replace(/[^A-Za-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80)
+    .toLowerCase();
+}
+
+function sourceForSkillPath(file) {
+  const normalized = String(file || '');
+  if (normalized.includes(`${path.sep}.codex${path.sep}`)) return 'codex-local';
+  if (normalized.includes(`${path.sep}.claude${path.sep}`)) return 'claude-local';
+  if (normalized.includes(`${path.sep}.agents${path.sep}`)) return 'agents-local';
+  return 'local';
+}
+
 function runtimeModel(config, adapter, runtimeState = {}) {
   const fromRun = String(runtimeState.current_model || runtimeState.model || '').trim();
   if (fromRun) return fromRun;

package/src/usage.js

@@ -0,0 +1,207 @@
+export function createUsageCollector(adapter = 'agent', modelConfig = {}) {
+  let best = null;
+  let responseModel = '';
+  let rawUsage = null;
+
+  function observe(event) {
+    if (!event || typeof event !== 'object') return;
+    responseModel = extractModel(event) || responseModel;
+    const usage = extractUsage(event);
+    if (!usage) return;
+    rawUsage = usage.raw_usage || usage;
+    if (!best || scoreUsage(usage) >= scoreUsage(best)) best = usage;
+  }
+
+  function summary() {
+    if (!best) return null;
+    const inputTokens = safeInt(best.input_tokens);
+    const outputTokens = safeInt(best.output_tokens);
+    const cacheReadTokens = safeInt(best.cache_read_tokens);
+    const cacheWriteTokens = safeInt(best.cache_write_tokens);
+    const cacheTokens = safeInt(best.cache_tokens) + cacheReadTokens + cacheWriteTokens;
+    const totalTokens = safeInt(best.total_tokens) || inputTokens + outputTokens + cacheTokens;
+    if (!totalTokens && !inputTokens && !outputTokens && !cacheTokens) return null;
+    return {
+      adapter,
+      provider: providerForAdapter(adapter),
+      request_model: modelFromConfig(modelConfig),
+      response_model: responseModel,
+      input_tokens: inputTokens,
+      output_tokens: outputTokens,
+      cache_read_tokens: cacheReadTokens,
+      cache_write_tokens: cacheWriteTokens,
+      cache_tokens: cacheTokens,
+      total_tokens: totalTokens,
+      source: sourceForAdapter(adapter),
+      raw_usage: compactRawUsage(rawUsage),
+    };
+  }
+
+  return { observe, summary };
+}
+
+export function taskUsagePatch(usage) {
+  if (!usage) return {};
+  return {
+    usage_prompt_tokens: safeInt(usage.input_tokens),
+    usage_completion_tokens: safeInt(usage.output_tokens),
+    usage_cache_read_tokens: safeInt(usage.cache_read_tokens) + safeInt(usage.cache_tokens),
+    usage_cache_write_tokens: safeInt(usage.cache_write_tokens),
+    usage_total_tokens: safeInt(usage.total_tokens),
+    usage_source: usage.source || 'wtt-connect',
+  };
+}
+
+function extractUsage(event) {
+  const direct = findUsageObject(event);
+  if (direct) return normalizeUsage(direct);
+  const stats = event?.stats;
+  if (stats && typeof stats === 'object') {
+    const models = stats.models;
+    if (models && typeof models === 'object' && !Array.isArray(models)) {
+      return normalizeUsage(aggregateModelStats(models));
+    }
+    return normalizeUsage(stats);
+  }
+  return null;
+}
+
+function findUsageObject(value, depth = 0) {
+  if (!value || typeof value !== 'object' || depth > 5) return null;
+  for (const key of ['usage', 'usage_metadata', 'usageMetadata', 'token_usage', 'tokenUsage']) {
+    const candidate = value[key];
+    if (candidate && typeof candidate === 'object') return candidate;
+  }
+  if (looksLikeUsage(value)) return value;
+  for (const key of ['message', 'response', 'result', 'item', 'delta', 'event']) {
+    const found = findUsageObject(value[key], depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+
+function looksLikeUsage(value) {
+  if (!value || typeof value !== 'object') return false;
+  return [
+    'input_tokens',
+    'prompt_tokens',
+    'output_tokens',
+    'completion_tokens',
+    'total_tokens',
+    'promptTokenCount',
+    'candidatesTokenCount',
+    'totalTokenCount',
+  ].some((key) => key in value);
+}
+
+function normalizeUsage(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const inputTokens = firstInt(raw, [
+    'input_tokens',
+    'prompt_tokens',
+    'promptTokens',
+    'prompt_token_count',
+    'promptTokenCount',
+    'inputTokenCount',
+  ]);
+  const candidateTokens = firstInt(raw, [
+    'output_tokens',
+    'completion_tokens',
+    'completionTokens',
+    'completion_token_count',
+    'candidatesTokenCount',
+    'outputTokenCount',
+  ]);
+  const thoughtsTokens = firstInt(raw, ['thoughtsTokenCount', 'reasoning_tokens', 'reasoningTokens']);
+  const outputTokens = candidateTokens + thoughtsTokens;
+  const cacheReadTokens = firstInt(raw, [
+    'cache_read_input_tokens',
+    'cached_tokens',
+    'cachedTokens',
+    'cachedContentTokenCount',
+  ]);
+  const cacheWriteTokens = firstInt(raw, ['cache_creation_input_tokens', 'cache_write_input_tokens']);
+  const cacheTokens = firstInt(raw, ['cache_tokens', 'cacheTokens']);
+  const totalTokens = firstInt(raw, ['total_tokens', 'totalTokens', 'totalTokenCount'])
+    || inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens + cacheTokens;
+  if (!inputTokens && !outputTokens && !cacheReadTokens && !cacheWriteTokens && !cacheTokens && !totalTokens) return null;
+  return {
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cache_read_tokens: cacheReadTokens,
+    cache_write_tokens: cacheWriteTokens,
+    cache_tokens: cacheTokens,
+    total_tokens: totalTokens,
+    raw_usage: raw,
+  };
+}
+
+function aggregateModelStats(models) {
+  const totals = {};
+  for (const value of Object.values(models || {})) {
+    if (!value || typeof value !== 'object') continue;
+    const usage = normalizeUsage(value);
+    if (!usage) continue;
+    for (const key of ['input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'cache_tokens', 'total_tokens']) {
+      totals[key] = safeInt(totals[key]) + safeInt(usage[key]);
+    }
+  }
+  return totals;
+}
+
+function extractModel(event) {
+  if (!event || typeof event !== 'object') return '';
+  for (const key of ['model', 'model_id', 'modelId', 'current_model', 'response_model']) {
+    const value = event[key];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return extractModel(event.message) || extractModel(event.response) || '';
+}
+
+function modelFromConfig(modelConfig = {}) {
+  return String(modelConfig.model || modelConfig.model_id || modelConfig.modelId || '').trim();
+}
+
+function firstInt(raw, keys) {
+  for (const key of keys) {
+    const value = raw?.[key];
+    const num = safeInt(value);
+    if (num) return num;
+  }
+  return 0;
+}
+
+function safeInt(value) {
+  const num = Number(value || 0);
+  if (!Number.isFinite(num) || num <= 0) return 0;
+  return Math.round(num);
+}
+
+function scoreUsage(usage) {
+  return safeInt(usage?.total_tokens) || safeInt(usage?.input_tokens) + safeInt(usage?.output_tokens) + safeInt(usage?.cache_tokens);
+}
+
+function providerForAdapter(adapter) {
+  if (adapter === 'claude-code') return 'anthropic-compatible';
+  if (adapter === 'codex') return 'openai-compatible';
+  if (adapter === 'gemini') return 'gemini';
+  return adapter || 'agent';
+}
+
+function sourceForAdapter(adapter) {
+  if (adapter === 'claude-code') return 'claude_code_stream_json';
+  if (adapter === 'codex') return 'codex_json';
+  if (adapter === 'gemini') return 'gemini_stream_json';
+  return `wtt-connect/${adapter || 'agent'}`;
+}
+
+function compactRawUsage(value) {
+  if (!value || typeof value !== 'object') return undefined;
+  try {
+    const json = JSON.stringify(value);
+    if (json.length <= 4000) return value;
+    return { truncated: true, total_tokens: safeInt(value.total_tokens || value.totalTokens || value.totalTokenCount) };
+  } catch {
+    return undefined;
+  }
+}

package/src/wtt-api.js

@@ -117,4 +117,17 @@ export class WTTApi {
     });
   }
 
+  async reportAgentUsage(usage) {
+    if (!usage || !this.config.agentId || !this.config.token) return null;
+    try {
+      return await this.request('POST', `/agents/${encodeURIComponent(this.config.agentId)}/usage`, {
+        headers: this.agentHeaders(),
+        json: usage,
+      });
+    } catch (err) {
+      log('warn', 'report_agent_usage failed', { error: err.message });
+      return null;
+    }
+  }
+
 }