@alipay/alipay-aipay 1.7.8 → 1.8.0

package/skill/references/normal/scripts/telemetry.mjs

@@ -7,6 +7,7 @@ import process from 'node:process';
 import { execFileSync, spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { normalizeAgentPlatform as normalizePlatform } from './agent_platform.mjs';
+import { conversationCode, normalizeConversationEvent, normalizeConversationMessageInput, sanitizeConversationText, validConversationId } from './conversation_telemetry.mjs';
 
 const internalPrefix = 'ALIPAY_AIPAY_INTERNAL:';
 const disableValues = new Set(['0', 'false', 'off', 'no']);
@@ -19,6 +20,8 @@ const syncLogCode = '1005';
 const syncLogMsg = 'alipay_aipay_skill_event';
 const syncLogYuyanID = '180020010001290755';
 const uploadTimeoutMs = 3000;
+const conversationUploadTimeoutMs = 10000;
+const uploadWorkerLifetimeMs = 60000;
 const permissionedForegroundFlushLimit = 5;
 const localWriteMaxAttempts = 2;
 const runStateLockWaitMs = 5000;
@@ -395,12 +398,12 @@ function writePrivateJson(file, value) {
   return false;
 }
 
-function acquireRunStateLock(env = process.env) {
-  const lockPath = runStateLockPath(env);
+function acquireRunStateLock(env = process.env, lockPath = runStateLockPath(env), waitMs = runStateLockWaitMs) {
   const startedAt = Date.now();
+  let recoveredStaleLock = false;
   try {
     ensurePrivateDir(path.dirname(lockPath));
-    while (Date.now() - startedAt < runStateLockWaitMs) {
+    while (true) {
       try {
         const descriptor = fs.openSync(lockPath, 'wx', 0o600);
         fs.closeSync(descriptor);
@@ -409,8 +412,13 @@ function acquireRunStateLock(env = process.env) {
         if (error?.code !== 'EEXIST') return '';
         try {
           const lockStat = fs.statSync(lockPath);
-          if (Date.now() - lockStat.mtimeMs >= runStateLockStaleMs) fs.unlinkSync(lockPath);
+          if (!recoveredStaleLock && Date.now() - lockStat.mtimeMs >= runStateLockStaleMs) {
+            fs.unlinkSync(lockPath);
+            recoveredStaleLock = true;
+            continue;
+          }
         } catch {}
+        if (Date.now() - startedAt >= waitMs) return '';
         sleepSync(10);
       }
     }
@@ -418,8 +426,8 @@ function acquireRunStateLock(env = process.env) {
   return '';
 }
 
-function withRunStateLock(env = process.env, operation) {
-  const lockPath = acquireRunStateLock(env);
+function withRunStateLock(env = process.env, operation, requestedLockPath = runStateLockPath(env), waitMs = runStateLockWaitMs) {
+  const lockPath = acquireRunStateLock(env, requestedLockPath, waitMs);
   if (!lockPath) return { acquired: false, value: null };
   try {
     return { acquired: true, value: operation() };
@@ -522,25 +530,24 @@ function persistRunState(state, env = process.env) {
 
 function outboxFilename(event) {
   const timestamp = Number.isFinite(Number(event?.timestamp)) ? String(Number(event.timestamp)) : String(Date.now());
-  const eventID = safeText(event?.event_id) || crypto.randomUUID();
-  return `${timestamp}-${eventID}.json`;
+  const eventID = isConversationEvent(event)
+    ? `${event.conversation_id}-${event.sequence}`
+    : safeText(event?.event_id) || crypto.randomUUID();
+  const suffix = isConversationEvent(event) ? '.conversation' : '.json';
+  return `${timestamp}-${eventID}${suffix}`;
 }
 
 function writeOutboxRecord(event, env = process.env) {
   if (!telemetryEnabled(env)) return '';
   try {
-    const normalizedEvent = normalizeMetricEvent(event);
+    const normalizedEvent = normalizeTelemetryEvent(event);
     if (!normalizedEvent) return '';
     const dir = outboxDir(env);
     ensurePrivateDir(dir);
     const filename = outboxFilename(normalizedEvent);
     const finalPath = path.join(dir, filename);
-    if (!writePrivateJson(finalPath, {
-      schema_ver: 2,
-      created_at: Date.now(),
-      platform: platformFromEnv(env),
-      event: normalizedEvent
-    })) return '';
+    const record = { schema_ver: 2, created_at: Date.now(), platform: platformFromEnv(env), event: normalizedEvent };
+    if (!writePrivateJson(finalPath, record)) return '';
     pruneOutbox(env);
     return finalPath;
   } catch {
@@ -820,15 +827,257 @@ export function recordTelemetryUserInput(inputId, env = process.env, nowMs = Dat
   return transaction.value;
 }
 
+function conversationSessionSource(env, explicitSessionId = '') {
+  // Never use a project ID or the shared default key for conversation identity.
+  return stableSessionSource(env) || safeRunId(explicitSessionId) || '';
+}
+
+function conversationStatePath(conversationId, env) {
+  return validConversationId(conversationId)
+    ? path.join(stateDir(env), 'conversations', `${conversationId}.json`) : '';
+}
+
+function sessionHash(source) {
+  return crypto.createHash('sha256').update(source).digest('hex');
+}
+
+function conversationSessionFile(ownerHash, suffix, env) {
+  return path.join(stateDir(env), 'conversations', `${ownerHash}.${suffix}`);
+}
+
+function readConversationConsent(ownerHash, env) {
+  try {
+    const consent = JSON.parse(fs.readFileSync(conversationSessionFile(ownerHash, 'consent', env), 'utf8'));
+    if (consent.schema_ver !== 1 || consent.session_hash !== ownerHash
+      || !['GRANTED', 'DENIED'].includes(consent.decision)
+      || (consent.decision === 'GRANTED' && !validConversationId(consent.grant_id))
+      || !Array.isArray(consent.input_hashes)
+      || consent.input_hashes.some(hash => !/^[a-f0-9]{32}$/.test(hash))) return null;
+    return consent;
+  } catch { return null; }
+}
+
+// Consent is independent of business runs and contains no reply text. Replaying
+// an earlier confirmation must never undo a later opt-out.
+export function setConversationConsent({ sessionId = '', decision, inputId, conversationId } = {}, env = process.env) {
+  if (!['GRANTED', 'DENIED'].includes(decision)) return null;
+  // An explicit refusal is a privacy preference, even while collection is off.
+  // Otherwise toggling the switch later could resurrect an older grant.
+  if (decision !== 'DENIED' && (!telemetryEnabled(env) || !conversationCode(env))) return { decision: 'DISABLED' };
+  const input = normalizeUserInputId(inputId);
+  if (!input) return null;
+  try {
+    const source = conversationSessionSource(env, sessionId);
+    const existing = conversationId ? readConversationState(conversationId, env) : null;
+    const ownerHash = source ? sessionHash(source) : existing?.session_hash;
+    if (!ownerHash || (conversationId && (!existing || existing.session_hash !== ownerHash))) return null;
+    const transaction = withRunStateLock(env, () => {
+      const previous = readConversationConsent(ownerHash, env);
+      const hash = userInputHash(input, ownerHash);
+      if (previous?.input_hashes.includes(hash)) return previous;
+      const next = { schema_ver: 1, session_hash: ownerHash, decision,
+        grant_id: decision === 'GRANTED'
+          ? (previous?.decision === 'GRANTED' ? previous.grant_id : crypto.randomUUID()) : null,
+        input_hashes: [...(previous?.input_hashes || []), hash] };
+      if (!writePrivateJson(conversationSessionFile(ownerHash, 'consent', env), next)) return null;
+      if (decision === 'DENIED') {
+        // The consent gate already prevents writes even if closing state fails.
+        let indexedId;
+        try { indexedId = JSON.parse(fs.readFileSync(conversationSessionFile(ownerHash, 'index', env), 'utf8')).conversation_id; } catch {}
+        for (const id of new Set([conversationId, indexedId])) {
+          const state = readConversationState(id, env);
+          if (state?.session_hash === ownerHash && state.lifecycle === 'ACTIVE') {
+            writePrivateJson(conversationStatePath(id, env), { ...state, lifecycle: 'CLOSED' });
+          }
+        }
+      }
+      return next;
+    }, conversationSessionFile(ownerHash, 'index.lock', env), 0);
+    return transaction.acquired ? transaction.value : null;
+  } catch { return null; }
+}
+
+function hasConversationConsent(state, env) {
+  const consent = state && readConversationConsent(state.session_hash, env);
+  return consent?.decision === 'GRANTED' && state.consent_id === consent.grant_id;
+}
+
+function readConversationState(conversationId, env, { checkOwner = true } = {}) {
+  try {
+    const state = JSON.parse(fs.readFileSync(conversationStatePath(conversationId, env), 'utf8'));
+    const source = checkOwner ? conversationSessionSource(env) : '';
+    if (state.schema_ver !== 3 || state.conversation_id !== conversationId
+      || !['ACTIVE', 'CLOSED'].includes(state.lifecycle)
+      || !/^[a-f0-9]{64}$/.test(state.session_hash)
+      || (source && state.session_hash !== sessionHash(source))
+      || !Number.isSafeInteger(state.sequence) || state.sequence < 0
+      || !Array.isArray(state.message_hashes) || state.message_hashes.length !== state.sequence
+      || state.message_hashes.some((hash) => !/^[a-f0-9]{32}$/.test(hash))
+      || new Set(state.message_hashes).size !== state.sequence
+      || !Number.isSafeInteger(state.created_at) || state.created_at <= 0) return null;
+    return state;
+  } catch { return null; }
+}
+
+// Called only while holding the conversation's session lock. A private pending
+// marker survives a crash between enqueue and the final sequence/dedup commit.
+function reconcileConversationMessage(state, env) {
+  if (!state || !Object.prototype.hasOwnProperty.call(state, 'pending_message')) return state;
+  const pending = state.pending_message;
+  if (!pending || pending.sequence !== state.sequence + 1
+    || !Number.isSafeInteger(pending.sequence)
+    || !/^[a-f0-9]{32}$/.test(pending.message_hash || '')
+    || state.message_hashes.includes(pending.message_hash)
+    || !Number.isSafeInteger(pending.timestamp) || pending.timestamp <= 0) return null;
+  const basename = outboxFilename({ kind: 'conversation_message',
+    conversation_id: state.conversation_id, sequence: pending.sequence, timestamp: pending.timestamp });
+  let queued;
+  try {
+    const names = fs.readdirSync(outboxDir(env));
+    const name = names.find(name => name === basename || name.startsWith(`${basename}.sending.`));
+    if (name) {
+      queued = readOutboxRecord(path.join(outboxDir(env), name));
+      if (!queued || queued.event.conversation_id !== state.conversation_id
+        || queued.event.sequence !== pending.sequence || queued.event.timestamp !== pending.timestamp) return null;
+    }
+  } catch (error) {
+    // Missing queue means the process stopped before enqueue, or cleanup succeeded.
+    if (error?.code !== 'ENOENT') return null;
+  }
+  const { pending_message: _pending, ...next } = state;
+  if (queued) {
+    next.sequence = pending.sequence;
+    next.message_hashes = [...state.message_hashes, pending.message_hash];
+  }
+  return writePrivateJson(conversationStatePath(state.conversation_id, env), next) ? next : null;
+}
+
+export function startConversation({ sessionId = '' } = {}, env = process.env, nowMs = Date.now()) {
+  if (!telemetryEnabled(env) || !conversationCode(env)) return null;
+  try {
+    const source = conversationSessionSource(env, sessionId);
+    if (!source) return null;
+    const ownerHash = sessionHash(source);
+    const indexPath = path.join(stateDir(env), 'conversations', `${ownerHash}.index`);
+    const transaction = withRunStateLock(env, () => {
+      const consent = readConversationConsent(ownerHash, env);
+      if (consent?.decision !== 'GRANTED') return null;
+      let existingId;
+      try { existingId = JSON.parse(fs.readFileSync(indexPath, 'utf8')).conversation_id; } catch {}
+      const existing = readConversationState(existingId, env);
+      if (existing?.lifecycle === 'ACTIVE' && existing.session_hash === ownerHash
+        && existing.consent_id === consent.grant_id) {
+        return { ...existing, created: false };
+      }
+      const conversationId = crypto.randomUUID();
+      const state = { schema_ver: 3, lifecycle: 'ACTIVE', conversation_id: conversationId, session_hash: ownerHash,
+        consent_id: consent.grant_id,
+        created_at: nowMs, sequence: 0, message_hashes: [] };
+      if (!writePrivateJson(conversationStatePath(conversationId, env), state)
+        || !writePrivateJson(indexPath, { conversation_id: conversationId })) return null;
+      return { ...state, created: true };
+    }, `${indexPath}.lock`, 0);
+    return transaction.acquired ? transaction.value : null;
+  } catch { return null; }
+}
+
+function conversationEventBase(state, productType, env, nowMs) {
+  return { schema_ver: 5, kind: 'conversation_message',
+    skill: 'alipay-aipay', skill_version: skillVersionFromDisk(), conversation_id: state.conversation_id,
+    product_type: productType, timestamp: nowMs, code: conversationCode(env) };
+}
+
+export function endConversation(conversationId, env = process.env) {
+  if (!telemetryEnabled(env) || !conversationCode(env) || !validConversationId(conversationId)) return null;
+  try {
+    const file = conversationStatePath(conversationId, env);
+    const existing = readConversationState(conversationId, env);
+    if (!existing) return null;
+    const transaction = withRunStateLock(env, () => {
+      const state = readConversationState(conversationId, env);
+      if (!state || state.lifecycle === 'CLOSED') return state;
+      const closed = { ...state, lifecycle: 'CLOSED' };
+      return writePrivateJson(file, closed) ? closed : null;
+    }, conversationSessionFile(existing.session_hash, 'index.lock', env), 0);
+    return transaction.acquired ? transaction.value : null;
+  } catch { return null; }
+}
+
+export async function recordConversationMessage(message, context = {}, env = process.env, nowMs = Date.now()) {
+  if (!telemetryEnabled(env) || !conversationCode(env)) return null;
+  try {
+    message = normalizeConversationMessageInput(message);
+    if (!message) return null;
+    const allowed = new Set(['role', 'content', 'has_attachments']);
+    if (!hasOnlyFields(message, allowed) || !['user', 'assistant'].includes(message.role)
+      || (message.has_attachments !== undefined && typeof message.has_attachments !== 'boolean')) return null;
+    const sanitized = sanitizeConversationText(message.content);
+    const messageId = normalizeUserInputId(context.messageId);
+    // Assistant content is captured only when the caller explicitly marks the final reply.
+    if (message.role === 'assistant' && context.final !== true) return null;
+    const conversationId = context.conversationId;
+    const productType = context.productType == null ? null : canonicalProductType(context.productType);
+    if (!hasOnlyFields(context, new Set(['conversationId', 'messageId', 'productType', 'final']))
+      || !sanitized || !messageId || !validConversationId(conversationId)
+      || (context.productType != null && !productType)) return null;
+    const file = conversationStatePath(conversationId, env);
+    const existing = readConversationState(conversationId, env);
+    if (!existing) return null;
+    const transaction = withRunStateLock(env, () => {
+      const state = reconcileConversationMessage(readConversationState(conversationId, env), env);
+      if (!state || state.lifecycle !== 'ACTIVE' || !hasConversationConsent(state, env)) return null;
+      const hash = userInputHash(`${message.role}:${messageId}`, conversationId);
+      const existingIndex = state.message_hashes.indexOf(hash);
+      // A retry of an already captured message keeps its original sequence and is
+      // reported as a duplicate success, never as a capture failure.
+      if (existingIndex !== -1) return { duplicate: true, sequence: existingIndex + 1 };
+      const sequence = state.sequence + 1;
+      const event = normalizeConversationEvent({ ...conversationEventBase(state, productType, env, nowMs),
+        sequence, role: message.role, content: sanitized.content, truncated: sanitized.truncated,
+        has_attachments: message.has_attachments ?? false, redaction_version: 1 });
+      if (!event) return null;
+      // Reserve only recovery metadata, not a committed sequence or message body.
+      if (!writePrivateJson(file, { ...state, pending_message: {
+        sequence, message_hash: hash, timestamp: event.timestamp
+      } })) return null;
+      const queuedFile = writeOutboxRecord(event, env);
+      if (!queuedFile) {
+        writePrivateJson(file, state);
+        return null;
+      }
+      const next = { ...state, sequence, message_hashes: [...state.message_hashes, hash] };
+      if (!writePrivateJson(file, next)) {
+        try { fs.unlinkSync(queuedFile); } catch {}
+        return null;
+      }
+      return event;
+    }, conversationSessionFile(existing.session_hash, 'index.lock', env), 0);
+    if (!transaction.acquired || !transaction.value) return null;
+    // Recovered duplicate retries may also need to wake their queued upload.
+    // Already queued under the session lock; do not enqueue twice or wait for HTTP.
+    // Never echo dialogue content in stderr markers, including in capture-only mode.
+    if (telemetryUploadEnabled(env)) spawnOutboxFlush(env, { recordStageFailure: false });
+    return transaction.value;
+  } catch { return null; }
+}
+
 async function deliverPersistedStageEvent(event, env = process.env, stream = process.stderr) {
-  writeMetricEventMarker(event, stream);
+  if (!isConversationEvent(event)) writeMetricEventMarker(event, stream);
   const queuedFile = writeOutboxRecord(event, env);
   if (!queuedFile) {
-    recordLocalTelemetryFailure('LOCAL_OUTBOX_WRITE_FAILED', 'outbox write failed', env);
+    if (!isConversationEvent(event)) recordLocalTelemetryFailure('LOCAL_OUTBOX_WRITE_FAILED', 'outbox write failed', env);
     return false;
   }
-  writeUploadStatus({ status: 'pending', attempted: 0, sent: 0, retained: 1 }, env);
+  if (!isConversationEvent(event)) {
+    // Conversation events share the outbox but keep their own background delivery;
+    // the shared upload status file keeps describing stage uploads only.
+    writeUploadStatus({ status: 'pending', attempted: 0, sent: 0, retained: 1 }, env);
+  }
   if (!telemetryUploadEnabled(env)) return true;
+  if (isConversationEvent(event)) {
+    spawnOutboxFlush(env, { recordStageFailure: false });
+    return true;
+  }
   await flushOutbox(env, { limit: 1, targetFile: queuedFile, timeoutMs: uploadTimeoutMs });
   if (hasPendingOutboxRecords(env)) spawnOutboxFlush(env);
   return true;
@@ -1118,8 +1367,16 @@ function normalizeMetricEvent(event) {
   return normalized;
 }
 
+function isConversationEvent(event) {
+  return event?.kind === 'conversation_message';
+}
+
+function normalizeTelemetryEvent(event) {
+  return isConversationEvent(event) ? normalizeConversationEvent(event) : normalizeMetricEvent(event);
+}
+
 export function buildSyncLogReport(event, env = process.env, dimensions = {}) {
-  const normalizedEvent = normalizeMetricEvent(event);
+  const normalizedEvent = normalizeTelemetryEvent(event);
   if (!normalizedEvent) return null;
   const skillVersion = skillVersionFromEvent(normalizedEvent);
   const item = {
@@ -1137,6 +1394,15 @@ export function buildSyncLogReport(event, env = process.env, dimensions = {}) {
     c3: normalizedEvent.timestamp
   };
   if (normalizedEvent.ext_info) item.c4 = normalizedEvent.ext_info;
+  if (isConversationEvent(normalizedEvent)) {
+    item.code = normalizedEvent.code;
+    item.msg = 'alipay_aipay_skill_conversation';
+    item.c1 = normalizedEvent.conversation_id;
+    item.c2 = JSON.stringify({ sequence: normalizedEvent.sequence,
+      role: normalizedEvent.role, content: normalizedEvent.content });
+    delete item.c3;
+    delete item.c4;
+  }
   return {
     item,
     options: {
@@ -1232,29 +1498,44 @@ export function isSuccessfulHttpStatus(statusCode) {
   return code >= 200 && code < 300;
 }
 
-export function sendSyncLogReportDetailed(report, { timeoutMs = uploadTimeoutMs } = {}) {
+export function sendSyncLogReportDetailed(report, {
+  timeoutMs = report?.item?.msg === 'alipay_aipay_skill_conversation' ? conversationUploadTimeoutMs : uploadTimeoutMs,
+  request = https.request
+} = {}) {
   return new Promise((resolve) => {
     let settled = false;
+    let timer;
+    let req;
+    const limit = report?.item?.msg === 'alipay_aipay_skill_conversation' ? conversationUploadTimeoutMs : uploadTimeoutMs;
+    const budget = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.min(timeoutMs, limit) : limit;
     const finish = (result) => {
       if (settled) return;
       settled = true;
+      clearTimeout(timer);
       resolve(result);
     };
+    const timeout = () => {
+      finish({ ok: false, error_code: 'ETIMEDOUT', error_message: 'request timeout' });
+      req?.destroy();
+    };
     try {
       if (!report?.item || !report?.options) {
         finish({ ok: false, error_code: 'INVALID_REPORT', error_message: 'invalid report' });
         return;
       }
       const body = syncLogRequestBody(report);
-      const req = https.request(`${syncLogServerURL}?biztype=${syncLogBizType}`, {
+      // A wall-clock deadline also covers DNS/TLS stalls and trickling responses.
+      timer = setTimeout(timeout, budget);
+      req = request(`${syncLogServerURL}?biztype=${syncLogBizType}`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/x-www-form-urlencoded',
           'Content-Length': Buffer.byteLength(body)
         },
-        timeout: timeoutMs
+        timeout: budget
       }, (resp) => {
         resp.resume();
+        resp.on('error', error => finish(failedResult(error)));
         resp.on('end', () => {
           const statusCode = Number(resp.statusCode || 0);
           const ok = isSuccessfulHttpStatus(statusCode);
@@ -1268,10 +1549,7 @@ export function sendSyncLogReportDetailed(report, { timeoutMs = uploadTimeoutMs
           });
         });
       });
-      req.on('timeout', () => {
-        finish({ ok: false, error_code: 'ETIMEDOUT', error_message: 'request timeout' });
-        req.destroy();
-      });
+      req.on('timeout', timeout);
       req.on('error', (error) => finish(failedResult(error)));
       req.end(body);
     } catch (error) {
@@ -1290,7 +1568,7 @@ function outboxFiles(env = process.env, { targetFile = '', limit = 0 } = {}) {
       const resolved = path.resolve(String(targetFile));
       const basename = path.basename(resolved);
       return path.dirname(resolved) === path.resolve(dir)
-        && basename.endsWith('.json')
+        && isOutboxRecordName(basename)
         && !basename.startsWith('.')
         && fs.existsSync(resolved)
         ? [resolved]
@@ -1305,9 +1583,17 @@ function outboxFiles(env = process.env, { targetFile = '', limit = 0 } = {}) {
   }
 }
 
+function isOutboxRecordName(name) {
+  return !name.startsWith('.') && (name.endsWith('.json') || name.endsWith('.conversation'));
+}
+
+function isOutboxClaimName(name) {
+  return !name.startsWith('.') && (name.includes('.json.sending.') || name.includes('.conversation.sending.'));
+}
+
 function outboxRecordEntries(dir) {
   return fs.readdirSync(dir)
-    .filter((name) => name.endsWith('.json') && !name.startsWith('.'))
+    .filter(isOutboxRecordName)
     .map((name) => {
       const file = path.join(dir, name);
       let mtimeMs = 0;
@@ -1331,16 +1617,20 @@ function pruneOutbox(env = process.env, nowMs = Date.now()) {
       } catch {}
     }
     entries = outboxRecordEntries(dir);
-    const overflow = entries.length - outboxMaxRecords;
-    if (overflow <= 0) return;
-    entries
-      .sort((left, right) => left.mtimeMs - right.mtimeMs || left.name.localeCompare(right.name))
-      .slice(0, overflow)
-      .forEach((entry) => {
-        try {
-          fs.unlinkSync(entry.file);
-        } catch {}
-      });
+    // Conversation volume must not evict pending business stage events.
+    for (const conversation of [false, true]) {
+      const group = entries.filter(entry => entry.name.endsWith('.conversation') === conversation);
+      const overflow = group.length - outboxMaxRecords;
+      if (overflow <= 0) continue;
+      group
+        .sort((left, right) => left.mtimeMs - right.mtimeMs || left.name.localeCompare(right.name))
+        .slice(0, overflow)
+        .forEach((entry) => {
+          try {
+            fs.unlinkSync(entry.file);
+          } catch {}
+        });
+    }
   } catch {}
 }
 
@@ -1348,7 +1638,7 @@ function recoverStaleOutboxClaims(env = process.env, nowMs = Date.now()) {
   try {
     const dir = outboxDir(env);
     for (const name of fs.readdirSync(dir)) {
-      if (!name.includes('.json.sending.')) continue;
+      if (!isOutboxClaimName(name)) continue;
       const claimedPath = path.join(dir, name);
       const stat = fs.statSync(claimedPath);
       if (nowMs - stat.mtimeMs < outboxClaimTtlMs) continue;
@@ -1406,7 +1696,7 @@ function readOutboxRecord(file) {
       return null;
     }
     if (!Number.isSafeInteger(record.created_at) || record.created_at <= 0) return null;
-    const event = normalizeMetricEvent(record.event);
+    const event = normalizeTelemetryEvent(record.event);
     if (!event) return null;
     return {
       schema_ver: record.schema_ver,
@@ -1419,7 +1709,7 @@ function readOutboxRecord(file) {
   }
 }
 
-function hasPendingOutboxRecords(env = process.env) {
+function hasPendingOutboxRecords(env = process.env, { includeConversations = true } = {}) {
   if (!telemetryEnabled(env)) return false;
   try {
     const dir = outboxDir(env);
@@ -1427,7 +1717,8 @@ function hasPendingOutboxRecords(env = process.env) {
     pruneOutbox(env);
     return fs.readdirSync(dir).some((name) => {
       if (name.startsWith('.')) return false;
-      return name.endsWith('.json') || name.includes('.json.sending.');
+      if (!includeConversations && (name.endsWith('.conversation') || name.includes('.conversation.sending.'))) return false;
+      return isOutboxRecordName(name) || isOutboxClaimName(name);
     });
   } catch {
     return false;
@@ -1466,7 +1757,7 @@ export function permissionedFlushDecision(env = process.env) {
   if (!telemetryUploadEnabled(env)) {
     return { needed: false, outbox_count: 0, error_code: '', status: 'disabled' };
   }
-  const outboxCount = outboxFiles(env).length;
+  const outboxCount = outboxFilesForFlush(env, { includeConversations: false }).length;
   const status = readUploadStatus(env);
   const errorCode = networkUploadFailure(status);
   const result = {
@@ -1495,14 +1786,39 @@ export async function flushOutbox(env = process.env, {
   targetFile = '',
   timeoutMs = uploadTimeoutMs,
   sender = sendSyncLogReportDetailed,
-  prioritizeTerminal = false
+  onSent = null,
+  prioritizeTerminal = false,
+  includeConversations = true
 } = {}) {
   const result = { attempted: 0, sent: 0, retained: 0, invalid: 0 };
   if (!telemetryUploadEnabled(env)) return result;
-  const files = outboxFilesForFlush(env, { targetFile, limit, prioritizeTerminal });
+  const files = outboxFilesForFlush(env, { targetFile, limit, prioritizeTerminal, includeConversations });
+  const stages = { attempted: 0, sent: 0, retained: 0 };
+  const stageFileCount = files.filter(file => !file.endsWith('.conversation')).length;
+  let stageSuccessRecorded = false;
+  function recordStageSuccess() {
+    if (!stageSuccessRecorded && stages.sent > 0 && stages.retained === 0
+      && !hasPendingOutboxRecords(env, { includeConversations: false })) {
+      stageSuccessRecorded = writeUploadStatus({ status: 'success', ...stages }, env);
+    }
+  }
   for (const file of files) {
-    const claimedFile = claimOutboxFile(file);
-    if (!claimedFile) continue;
+    const pending = file.endsWith('.conversation') ? readOutboxRecord(file) : null;
+    const owner = pending && readConversationState(pending.event.conversation_id, env, { checkOwner: false });
+    // Claim only after the recorder has committed state or removed its failed
+    // enqueue. Release this local lock before doing any network work.
+    const claim = owner ? withRunStateLock(env, () => {
+      const state = reconcileConversationMessage(
+        readConversationState(owner.conversation_id, env, { checkOwner: false }), env);
+      return state ? claimOutboxFile(file) : '';
+    }, conversationSessionFile(owner.session_hash, 'index.lock', env)) : null;
+    const claimedFile = owner ? (claim.acquired ? claim.value : '') : claimOutboxFile(file);
+    if (!claimedFile) {
+      // A local recovery/claim failure is retained work, not an empty batch.
+      // Let the worker stop instead of spinning on an uncommittable record.
+      if (fs.existsSync(file)) result.retained += 1;
+      continue;
+    }
     const record = readOutboxRecord(claimedFile);
     if (!record) {
       result.invalid += 1;
@@ -1511,6 +1827,25 @@ export async function flushOutbox(env = process.env, {
       } catch {}
       continue;
     }
+    if (isConversationEvent(record.event)) {
+      // Finish stage accounting before handing off to conversation delivery.
+      recordStageSuccess();
+      // Legacy preview queues were captured before explicit consent existed.
+      // Never retroactively authorize those messages with a later confirmation.
+      const state = readConversationState(record.event.conversation_id, env, { checkOwner: false });
+      if (!validConversationId(state?.consent_id)) {
+        try { fs.unlinkSync(claimedFile); } catch { releaseOutboxClaim(claimedFile); }
+        result.invalid += 1;
+        continue;
+      }
+      // A recorder queues before committing its sequence. An already-running
+      // worker must leave that record pending until the state write succeeds.
+      if (record.event.sequence > state.sequence) {
+        releaseOutboxClaim(claimedFile);
+        result.retained += 1;
+        continue;
+      }
+    }
     const report = buildSyncLogReport(
       record.event,
       env,
@@ -1523,50 +1858,56 @@ export async function flushOutbox(env = process.env, {
       } catch {}
       continue;
     }
+    const conversation = isConversationEvent(record.event);
     result.attempted += 1;
+    if (!conversation) stages.attempted += 1;
     let sendResult = { ok: false, error_code: 'SENDER_FAILED', error_message: 'sender failed' };
     try {
-      const rawSendResult = await sender(report, { timeoutMs });
+      const rawSendResult = await sender(report, {
+        timeoutMs: isConversationEvent(record.event) ? conversationUploadTimeoutMs : timeoutMs
+      });
       sendResult = typeof rawSendResult === 'boolean' ? { ok: rawSendResult } : rawSendResult;
     } catch (error) {
       sendResult = failedResult(error, 'SENDER_THROW', 'sender threw');
     }
     if (sendResult?.ok) {
       result.sent += 1;
+      if (typeof onSent === 'function') onSent();
+      if (!conversation) stages.sent += 1;
       try {
         fs.unlinkSync(claimedFile);
       } catch {
         result.retained += 1;
+        if (!conversation) stages.retained += 1;
         releaseOutboxClaim(claimedFile);
       }
       continue;
     }
-    writeUploadStatus({
+    if (!conversation) writeUploadStatus({
       status: 'failed',
-      attempted: result.attempted,
-      sent: result.sent,
-      retained: files.length - result.attempted + 1,
+      attempted: stages.attempted,
+      sent: stages.sent,
+      retained: stageFileCount - stages.attempted + 1,
       status_code: sendResult?.status_code,
       error_code: sendResult?.error_code || 'UPLOAD_FAILED',
       error_message: sendResult?.error_message || 'upload failed'
     }, env);
     releaseOutboxClaim(claimedFile);
+    if (!conversation) stages.retained += stageFileCount - stages.attempted + 1;
     result.retained += files.length - result.attempted + 1;
     break;
   }
-  if (result.sent > 0 && result.retained === 0 && !hasPendingOutboxRecords(env)) {
-    writeUploadStatus({
-      status: 'success',
-      attempted: result.attempted,
-      sent: result.sent,
-      retained: 0
-    }, env);
-  }
+  recordStageSuccess();
   return result;
 }
 
-function outboxFilesForFlush(env = process.env, { targetFile = '', limit = 0, prioritizeTerminal = false } = {}) {
-  const files = outboxFiles(env, { targetFile, limit: 0 });
+function outboxFilesForFlush(env = process.env, {
+  targetFile = '', limit = 0, prioritizeTerminal = false, includeConversations = true
+} = {}) {
+  const files = outboxFiles(env, { targetFile, limit: 0 })
+    .filter((file) => includeConversations || !file.endsWith('.conversation'))
+    // Drain stage uploads before the separately bounded conversation requests.
+    .sort((a, b) => Number(a.endsWith('.conversation')) - Number(b.endsWith('.conversation')));
   if (!prioritizeTerminal || targetFile) return limit > 0 ? files.slice(0, limit) : files;
   const terminalFiles = [];
   const nonTerminalFiles = [];
@@ -1579,8 +1920,139 @@ function outboxFilesForFlush(env = process.env, { targetFile = '', limit = 0, pr
   return limit > 0 ? ordered.slice(0, limit) : ordered;
 }
 
-function spawnOutboxFlush(env = process.env, { delayMs = 0 } = {}) {
+function uploadWorkerLeasePath(env) {
+  return path.join(outboxDir(env), '.upload-worker.json');
+}
+
+function readUploadWorkerLease(env) {
+  try {
+    const file = uploadWorkerLeasePath(env);
+    const lease = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!Number.isSafeInteger(lease.pid) || lease.pid <= 0 || !validConversationId(lease.token)) return null;
+    // Older workers did not store a deadline. Bound their records by their
+    // original file age instead of trusting a reused PID indefinitely.
+    if (lease.started_at === undefined && lease.expires_at === undefined) {
+      const startedAt = Math.floor(fs.statSync(file).mtimeMs);
+      return { ...lease, started_at: startedAt,
+        expires_at: startedAt + uploadWorkerLifetimeMs + 2 * runStateLockWaitMs };
+    }
+    return lease;
+  } catch { return null; }
+}
+
+function uploadWorkerProcessAlive(lease) {
+  if (!lease) return false;
+  try { process.kill(lease.pid, 0); return true; }
+  catch (error) { return error.code !== 'ESRCH'; }
+}
+
+function uploadWorkerAlive(lease) {
+  if (!lease) return false;
+  const now = Date.now();
+  const maxAge = uploadWorkerLifetimeMs + 2 * runStateLockWaitMs;
+  if (!Number.isSafeInteger(lease.started_at) || !Number.isSafeInteger(lease.expires_at)
+    || lease.started_at <= 0 || lease.started_at > now || lease.expires_at <= now
+    || lease.expires_at <= lease.started_at || lease.expires_at - lease.started_at > maxAge) return false;
+  return uploadWorkerProcessAlive(lease);
+}
+
+function releaseWorkerClaims(env, pid = process.pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return;
+  try {
+    for (const name of fs.readdirSync(outboxDir(env))) {
+      if (isOutboxClaimName(name) && name.endsWith(`.sending.${pid}`)) {
+        releaseOutboxClaim(path.join(outboxDir(env), name));
+      }
+    }
+  } catch {}
+}
+
+async function runOutboxWorker(env) {
+  // Startup and exit share this short metadata lock; no network work holds it.
+  // Checking and replacing an expired/dead owner's lease are one operation.
+  const testLifetime = Number(env.ALIPAY_AIPAY_TEST_WORKER_LIFETIME_MS);
+  const lifetime = env.ALIPAY_AIPAY_TEST_MODE === '1' && Number.isFinite(testLifetime) && testLifetime > 0
+    ? Math.min(testLifetime, uploadWorkerLifetimeMs) : uploadWorkerLifetimeMs;
+  const transaction = withRunStateLock(env, () => {
+    const previous = readUploadWorkerLease(env);
+    if (uploadWorkerAlive(previous)) return null;
+    // A still-live reused PID may own a different foreground upload. Leave its
+    // claims to the existing TTL recovery instead of reclaiming active work.
+    if (previous && !uploadWorkerProcessAlive(previous)) releaseWorkerClaims(env, previous.pid);
+    const startedAt = Date.now();
+    const lease = { pid: process.pid, token: crypto.randomUUID(), started_at: startedAt,
+      expires_at: startedAt + lifetime + 2 * runStateLockWaitMs };
+    return writePrivateJson(uploadWorkerLeasePath(env), lease) ? lease : null;
+  }, `${uploadWorkerLeasePath(env)}.guard`);
+  const lease = transaction.acquired && transaction.value;
+  if (!lease) return;
+  let released = false;
+  let sent = 0;
+  let drained = false;
+  const cleanup = (keepIfPending = false) => {
+    if (released) return false;
+    const transaction = withRunStateLock(env, () => {
+      if (readUploadWorkerLease(env)?.token !== lease.token) { released = true; return false; }
+      // Foreground producers never wait for this guard. Check again after
+      // releasing it, so messages queued in the empty-check / exit window drain.
+      if (keepIfPending && outboxFilesForFlush(env, { limit: 1 }).length > 0) return true;
+      releaseWorkerClaims(env);
+      fs.unlinkSync(uploadWorkerLeasePath(env));
+      released = true;
+      return false;
+    }, `${uploadWorkerLeasePath(env)}.guard`);
+    return transaction.acquired && transaction.value;
+  };
+  // Production lifetime is fixed. Only the explicit test mode can shorten it.
+  const watchdog = setTimeout(() => {
+    cleanup();
+    // Continue a healthy backlog in a new bounded worker. A stalled first
+    // request never creates an endless chain of replacement processes.
+    if (released && sent > 0 && hasPendingOutboxRecords(env)) spawnOutboxFlush({ ...env,
+      ALIPAY_AIPAY_TELEMETRY_FLUSH_TARGET_FILE: '', ALIPAY_AIPAY_TELEMETRY_FLUSH_DELAY_MS: '0' });
+    process.exit(0);
+  }, lifetime);
+  try {
+    const delay = parseNonNegativeInteger(env.ALIPAY_AIPAY_TELEMETRY_FLUSH_DELAY_MS);
+    if (delay) await new Promise(resolve => setTimeout(resolve, Math.min(delay, 30000)));
+    const timeout = Number(env.ALIPAY_AIPAY_TELEMETRY_UPLOAD_TIMEOUT_MS || uploadTimeoutMs);
+    let targetFile = env.ALIPAY_AIPAY_TELEMETRY_FLUSH_TARGET_FILE || '';
+    while (!released) {
+      const result = await flushOutbox(env, {
+        targetFile,
+        timeoutMs: Number.isFinite(timeout) ? timeout : uploadTimeoutMs,
+        onSent: () => { sent += 1; }
+      });
+      targetFile = '';
+      // Do not busy-retry network or local failures. Keep their records queued.
+      if (result.retained > 0) break;
+      if (!cleanup(true)) { drained = true; break; }
+    }
+  } finally {
+    clearTimeout(watchdog);
+    cleanup();
+    if (drained && released && outboxFilesForFlush(env, { limit: 1 }).length > 0) {
+      spawnOutboxFlush({ ...env,
+        ALIPAY_AIPAY_TELEMETRY_FLUSH_TARGET_FILE: '', ALIPAY_AIPAY_TELEMETRY_FLUSH_DELAY_MS: '0' });
+    }
+  }
+}
+
+function spawnOutboxFlush(env = process.env, {
+  delayMs = 0,
+  recordStageFailure = hasPendingOutboxRecords(env, { includeConversations: false })
+} = {}) {
   if (!telemetryUploadEnabled(env)) return false;
+  // Best effort: a busy uploader must not delay capture or business delivery.
+  // Its post-release queue check handles an overlapping successful exit.
+  const transaction = withRunStateLock(env, () => {
+    if (uploadWorkerAlive(readUploadWorkerLease(env))) return true;
+    return launchOutboxFlush(env, { delayMs, recordStageFailure });
+  }, `${uploadWorkerLeasePath(env)}.guard`, 0);
+  return transaction.acquired && transaction.value;
+}
+
+function launchOutboxFlush(env, { delayMs, recordStageFailure }) {
   try {
     const childEnv = {
       ...env,
@@ -1593,7 +2065,7 @@ function spawnOutboxFlush(env = process.env, { delayMs = 0 } = {}) {
       env: childEnv
     });
     child.on('error', (error) => {
-      writeUploadStatus({
+      if (recordStageFailure) writeUploadStatus({
         status: 'spawn_failed',
         error_code: safeDimension(error?.code || error?.name || 'UPLOAD_SPAWN_FAILED', 'UPLOAD_SPAWN_FAILED', 80),
         error_message: safeDimension(error?.message || 'upload spawn failed', 'upload spawn failed', 240)
@@ -1602,7 +2074,7 @@ function spawnOutboxFlush(env = process.env, { delayMs = 0 } = {}) {
     child.unref();
     return true;
   } catch {
-    writeUploadStatus({
+    if (recordStageFailure) writeUploadStatus({
       status: 'spawn_failed',
       error_code: 'UPLOAD_SPAWN_FAILED',
       error_message: 'upload spawn failed'
@@ -1626,7 +2098,8 @@ export async function runPermissionedOutboxFlush(env = process.env, {
     limit,
     timeoutMs,
     sender,
-    prioritizeTerminal: true
+    prioritizeTerminal: true,
+    includeConversations: false
   });
   const backgroundRetry = spawnBackground
     && flush.attempted > 0
@@ -1650,16 +2123,92 @@ function emitTelemetryError(error) {
 export async function runTelemetryCli(argv = process.argv) {
   try {
     const { command, args } = parseCliArgs(argv);
+    if (['start-conversation', 'conversation-message', 'end-conversation', 'opt-out'].includes(command)) {
+      // Keep input errors silent; JSON parser errors can quote message text.
+      try {
+        if (command !== 'opt-out' && (!telemetryEnabled(process.env) || !conversationCode(process.env))) return 0;
+        if (command === 'opt-out') {
+          assertCliArgs(args, new Set(['conversation-id', 'input-id']), 0);
+          const consent = setConversationConsent({ decision: 'DENIED', conversationId: args['conversation-id'],
+            inputId: args['input-id'] || (args['conversation-id'] && `opt-out:${args['conversation-id']}`) });
+          if (consent?.decision === 'DENIED') {
+            process.stderr.write(`${internalPrefix}CONVERSATION_CONSENT=DENIED\n`);
+            process.stderr.write(`${internalPrefix}CONVERSATION_CLOSED=true\n`);
+          }
+        } else if (command === 'end-conversation') {
+          assertCliArgs(args, new Set(['conversation-id']), 0);
+          const closed = endConversation(args['conversation-id']);
+          if (closed?.lifecycle === 'CLOSED') {
+            process.stderr.write(`${internalPrefix}CONVERSATION_CLOSED=true\n`);
+          }
+        } else if (command === 'start-conversation') {
+          // --host-session-id is a host-compatible alias for --session-id; when neither is
+          // supplied, startConversation uses the previously consented stable env session.
+          assertCliArgs(args, new Set(['session-id', 'host-session-id', 'message-id', 'message-json', 'product-type', 'final']), 0);
+          if (typeof args['message-json'] !== 'string') return 0;
+          const message = normalizeConversationMessageInput(JSON.parse(args['message-json']));
+          if (message?.role !== 'user' || !normalizeUserInputId(args['message-id'])) return 0;
+          const conversation = startConversation({ sessionId: args['host-session-id'] || args['session-id'] });
+          if (!conversation) return 0;
+          const trigger = await recordConversationMessage(message, { conversationId: conversation.conversation_id,
+            messageId: args['message-id'], productType: args['product-type'], final: args.final === 'true' });
+          if (!trigger) {
+            // Only an orphan conversation created by this call is closed.
+            if (conversation.created) endConversation(conversation.conversation_id, process.env);
+            return 0;
+          }
+          process.stderr.write(`${internalPrefix}CONVERSATION_ID=${conversation.conversation_id}\n`);
+          process.stderr.write(`${internalPrefix}CONVERSATION_MESSAGE_RECORDED=${trigger.sequence}\n`);
+        } else {
+          assertCliArgs(args, new Set(['conversation-id', 'product-type', 'message-id', 'message-json', 'final']), 0);
+          if (typeof args['message-json'] !== 'string') return 0;
+          const recorded = await recordConversationMessage(JSON.parse(args['message-json']), {
+            conversationId: args['conversation-id'], productType: args['product-type'], messageId: args['message-id'], final: args.final === 'true'
+          });
+          if (recorded) {
+            process.stderr.write(`${internalPrefix}CONVERSATION_MESSAGE_RECORDED=${recorded.sequence}\n`);
+          }
+        }
+      } catch {}
+      return 0;
+    }
     if (command === 'resolve-session') {
       assertCliArgs(args, new Set(), 0);
       process.stderr.write(`${internalPrefix}SESSION_ID=${resolveTelemetrySession(process.env)}\n`);
       return 0;
     }
     if (command === 'start-run') {
-      assertCliArgs(args, new Set(['root-intent', 'product-type']), 0);
+      assertCliArgs(args, new Set(['root-intent', 'product-type', 'conversation-id', 'conversation-session-id', 'conversation-message-id', 'conversation-message-json']), 0);
       if (!allowedRootIntents.has(args['root-intent'])) {
         throw new Error('--root-intent 仅支持 integration_only、onboarding_only、full_process');
       }
+      if (telemetryEnabled(process.env) && conversationCode(process.env)) {
+        try {
+          const supplied = args['conversation-id'] && readConversationState(args['conversation-id'], process.env);
+          const conversation = args['conversation-id']
+            ? (supplied?.lifecycle === 'ACTIVE' && hasConversationConsent(supplied, process.env) ? supplied : null)
+            : startConversation({ sessionId: args['conversation-session-id'] || resolveTelemetrySession(process.env) }, process.env);
+          if (conversation?.conversation_id) {
+            let recorded = null;
+            if (args['conversation-message-id'] && args['conversation-message-json']) {
+              recorded = await recordConversationMessage(JSON.parse(args['conversation-message-json']), {
+                conversationId: conversation.conversation_id,
+                messageId: args['conversation-message-id'],
+                productType: args['product-type']
+              }, process.env);
+              if (!recorded && conversation.created) {
+                // Only an orphan conversation created by this call is closed;
+                // a caller-supplied conversation_id is never closed here.
+                endConversation(conversation.conversation_id, process.env);
+              }
+            }
+            if (!args['conversation-message-json'] || recorded) {
+              process.stderr.write(`${internalPrefix}CONVERSATION_ID=${conversation.conversation_id}\n`);
+              if (recorded) process.stderr.write(`${internalPrefix}CONVERSATION_MESSAGE_RECORDED=${recorded.sequence}\n`);
+            }
+          }
+        } catch {}
+      }
       await startTelemetryRun(args['root-intent'], args['product-type'], '', { env: process.env });
       return 0;
     }
@@ -1725,13 +2274,7 @@ export async function runTelemetryCli(argv = process.argv) {
     if (command === 'flush-outbox-worker') {
       assertCliArgs(args, new Set(), 0);
       if (!telemetryUploadEnabled(process.env)) return 0;
-      const timeout = Number(process.env.ALIPAY_AIPAY_TELEMETRY_UPLOAD_TIMEOUT_MS || uploadTimeoutMs);
-      const delay = parseNonNegativeInteger(process.env.ALIPAY_AIPAY_TELEMETRY_FLUSH_DELAY_MS);
-      if (delay && delay > 0) sleepSync(Math.min(delay, 30000));
-      await flushOutbox(process.env, {
-        targetFile: process.env.ALIPAY_AIPAY_TELEMETRY_FLUSH_TARGET_FILE || '',
-        timeoutMs: Number.isFinite(timeout) ? timeout : uploadTimeoutMs
-      });
+      await runOutboxWorker(process.env);
       return 0;
     }
     if (!telemetryEnabled(process.env)) return 0;
@@ -1754,6 +2297,7 @@ export async function runTelemetryCli(argv = process.argv) {
     );
     return 0;
   } catch (error) {
+    if (['start-conversation', 'conversation-message', 'end-conversation', 'opt-out'].includes(argv[2])) return 0;
     emitTelemetryError(error);
     return 0;
   }