@ai-workbench/remote-agent 0.8.0 → 0.8.1

package/README.md

@@ -1,4 +1,4 @@
-在 DSH「插件 → 添加插件」填 `@ai-workbench/remote-agent@0.8.0`（由编排发布后可用），或运行 `dsh plugin --profile desktop add @ai-workbench/remote-agent@0.8.0`。
+在 DSH「插件 → 添加插件」填 `@ai-workbench/remote-agent@0.8.1`（由编排发布后可用），或运行 `dsh plugin --profile desktop add @ai-workbench/remote-agent@0.8.1`。
 
 # 远程ACP插件
 
@@ -52,3 +52,8 @@ Codex单次模式首版仅文本，不转接中途审批；图片或系统/开
 ## 验证范围
 
 当前准备结果与限制记入源码仓`docs/evidence/2026-10-21-X-npm-prep/`（不进npm包）。先前真实emp-a协议诊断及固定三件套GUI是不同轮次，不能代替本次新包安装门。L完整绑定/登录、真实模型、物理断网、HanaMesh及leo E以实际已执行证据为准。主机命令安装来自S，X不修改S仓/安装脚本或登录状态。
+
+
+D19（0.8.1）：相邻正文增量合成连续文本块，工作区首次说明合入真实回复，按官方持久记录核对后才回报“已记入可核对回复”。这不代表界面已经显示。
+
+技术详情由 L 0.7.9 的唯一“远程主机连接”设置节展示，正文只放模型文本。命令目录保留完整描述；未知事件和工具输入输出保留字段、JSON类型及处理结果，未获准原文明确脱敏，数字用量可核对。没有 `remoteConversationDetails:1` 时明确提示“技术详情暂不可用”，本轮不发送模型请求。X 在官方当前 profile 的 `ai-workbench-remote-agent/diagnostics/` 保存私有诊断日志（目录700、文件600、落盘同步）；写入/归属/顺序/容量失败中止本轮，不自动重发、换代重投、过期或淘汰。结果未知时只读核对原事件完整回执，未找到仍保持未知。X本轮无新增设置/阈值；L的单事件容量和分页设置在L设置节可见。

package/dist/acp.d.ts

@@ -2,12 +2,14 @@ import * as stable from '@agentclientprotocol/sdk';
 import * as acp from '@agentclientprotocol/sdk/unstable';
 import { NeedError, type Need } from './remote.ts';
 import type { BrokerTransport } from './broker.ts';
+import { type SanitizedObservation } from './conversation-details.ts';
 export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
 export interface AcpHooks {
     onUpdate?: (notification: acp.SessionNotification) => void;
     onResponse?: (response: acp.PromptResponse) => void;
     approve?: (request: acp.RequestPermissionRequest, signal?: AbortSignal) => Promise<ApprovalOutcome>;
     onNeed?: (need: Need) => void;
+    onDetail?: (detail: Readonly<SanitizedObservation>) => void;
     broker?: BrokerTransport;
 }
 export interface AcpStartContext {
@@ -29,6 +31,12 @@ export declare class AcpSession {
     private updating;
     private cwd?;
     private systemPrompt;
+    private reports;
+    private reportingFailure;
+    get diagnostics(): readonly Readonly<SanitizedObservation>[];
+    private detail;
+    private need;
+    private checkReporting;
     constructor(transport: acp.Stream | acp.AgentApp | stable.AgentApp, hooks: AcpHooks);
     private observe;
     get id(): string | undefined;

package/dist/acp.js

@@ -1,5 +1,6 @@
 import * as acp from '@agentclientprotocol/sdk/unstable';
 import { NeedError } from "./remote.js";
+import { sanitizeObservation } from "./conversation-details.js";
 /** ACP v1 with explicitly negotiated SDK 2.0 lifecycle/context extensions. */
 export class AcpSession {
     connection;
@@ -15,19 +16,45 @@ export class AcpSession {
     updating = false;
     cwd;
     systemPrompt = '';
+    reports = [];
+    reportingFailure;
+    get diagnostics() { return this.reports.map(entry => sanitizeObservation(entry)); }
+    detail(observation) {
+        const safe = sanitizeObservation(observation);
+        this.reports.push(safe);
+        try {
+            this.hooks.onDetail?.(safe);
+        }
+        catch (cause) {
+            this.reportingFailure ??= { cause };
+            this.connection?.close();
+        }
+    }
+    need(need) {
+        this.detail({ kind: 'need', severity: 'action-required', code: need.code, summary: need.message, payload: { requires: need.requires } });
+        this.hooks.onNeed?.(need);
+    }
+    checkReporting() { if (this.reportingFailure)
+        throw new NeedError('CONVERSATION_DETAILS_FAILED', '技术详情未能记录；本轮未继续发送', '可用的技术详情记录渠道'); }
     constructor(transport, hooks) {
         this.hooks = hooks;
         const app = acp.client({ name: '@ai-workbench/remote-agent' })
             .onNotification(acp.methods.client.session.update, ({ params: notification }) => {
-            if (this.busy && notification.sessionId === this.sessionId) {
-                // Session metadata is not evidence that the current prompt was accepted.
+            if (this.sessionId && notification.sessionId !== this.sessionId) {
+                this.detail({ kind: 'session', severity: 'warning', code: 'ACP_FOREIGN_SESSION_UPDATE', summary: '收到不属于当前远端会话的通知，未作为正文处理', method: 'session/update', payload: notification });
+                return;
+            }
+            const meta = record(notification._meta);
+            if (meta && Object.keys(meta).length)
+                this.detail({ kind: 'extension', severity: 'info', code: 'ACP_NOTIFICATION_META', summary: '远端通知扩展', method: 'session/update', payload: notification._meta });
+            if (this.busy) {
+                // Only actual turn output acknowledges prompt acceptance.
                 if (['agent_message_chunk', 'agent_thought_chunk', 'tool_call', 'tool_call_update'].includes(notification.update.sessionUpdate))
                     this.hooks.broker?.acknowledge(acp.methods.agent.session.prompt);
-                const meta = record(notification._meta);
-                if (meta && Object.keys(meta).length)
-                    this.hooks.onNeed?.({ code: 'ACP_EXTENSION_UNSUPPORTED', message: `首版不支持：远端通知扩展字段 ${Object.keys(meta).map(safeLabel).join('、')}；扩展值未展开`, requires: '对应的公开扩展映射' });
                 this.hooks.onUpdate?.(notification);
             }
+            else
+                this.detail({ kind: notification.update.sessionUpdate === 'available_commands_update' ? 'commands' : 'session', severity: 'info', code: 'ACP_IDLE_UPDATE', summary: '远端会话建立、恢复或空闲时的轨迹', method: 'session/update', payload: notification });
         })
             .onRequest(acp.methods.client.session.requestPermission, async ({ params: request, signal: rpcSignal, requestId }) => {
             if (request.sessionId !== this.sessionId || !this.busy || this.turnSignal?.aborted)
@@ -35,7 +62,7 @@ export class AcpSession {
             this.hooks.broker?.acknowledge(acp.methods.agent.session.prompt);
             const toolName = request.toolCall.name ?? record(request.toolCall._meta?.claudeCode)?.toolName;
             if (toolName === 'AskUserQuestion') {
-                this.hooks.onNeed?.({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问；已取消，未提交答案', requires: '可承载此提问的官方交互接口' });
+                this.need({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问；已取消，未提交答案', requires: '可承载此提问的官方交互接口' });
                 return { outcome: { outcome: 'cancelled' } };
             }
             const eligible = request.options.filter(option => {
@@ -43,11 +70,13 @@ export class AcpSession {
                 const sameKind = request.options.filter(candidate => candidate.kind === option.kind);
                 const unique = single && sameKind.length === 1 && request.options.filter(candidate => candidate.optionId === option.optionId).length === 1;
                 if (!unique)
-                    this.hooks.onNeed?.({ code: 'APPROVAL_OPTION_UNSUPPORTED', message: `首版不支持：${option.name} / ${option.optionId} / ${option.kind}`, requires: '唯一对应的允许一次或拒绝一次选项' });
+                    this.detail({ kind: 'tool', severity: 'info', code: 'APPROVAL_OPTION_NOT_OFFERED', summary: '此远端审批选项未映射到单次审批', method: 'session/request_permission', payload: option });
                 return unique;
             });
-            if (!eligible.length)
+            if (!eligible.length) {
+                this.need({ code: 'APPROVAL_OPTION_UNSUPPORTED', message: '远端没有可唯一映射的单次审批选项，此动作未获授权', requires: '唯一对应的允许一次或拒绝一次选项' });
                 return { outcome: { outcome: 'cancelled' } };
+            }
             const presented = { ...request, options: eligible };
             const token = this.turnToken;
             const id = this.sessionId;
@@ -78,7 +107,7 @@ export class AcpSession {
                 }
             }
             catch {
-                this.hooks.onNeed?.({ code: 'APPROVAL_FAILED', message: '审批渠道失败或连接已结束；此动作未获授权', requires: '可用的 DSH 审批渠道和原连接' });
+                this.need({ code: 'APPROVAL_FAILED', message: '审批渠道失败或连接已结束；此动作未获授权', requires: '可用的 DSH 审批渠道和原连接' });
             }
             const kind = outcome === 'allowed-once' ? 'allow_once' : outcome === 'rejected' ? 'reject_once' : undefined;
             const option = kind && eligible.find(item => item.kind === kind);
@@ -87,23 +116,24 @@ export class AcpSession {
                     broker.authorizeResponse(requestId, generation);
                 return { outcome: { outcome: 'selected', optionId: option.optionId } };
             }
-            this.hooks.onNeed?.({ code: outcome === 'allowed-once' ? 'APPROVAL_OPTION_UNSUPPORTED' : 'APPROVAL_UNAVAILABLE',
+            this.need({ code: outcome === 'allowed-once' ? 'APPROVAL_OPTION_UNSUPPORTED' : 'APPROVAL_UNAVAILABLE',
                 message: '此动作未获授权；审批已取消、不可用或没有可映射的单次选项', requires: '本次动作的有效审批' });
             return { outcome: { outcome: 'cancelled' } };
         })
             .onRequest(acp.methods.client.elicitation.create, () => {
-            this.hooks.onNeed?.({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问或信息收集；已取消，未提交答案', requires: '可承载此提问的官方交互接口' });
+            this.need({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问或信息收集；已取消，未提交答案', requires: '可承载此提问的官方交互接口' });
             return { action: 'cancel' };
         })
             .onNotification(acp.methods.client.elicitation.complete, () => {
-            this.hooks.onNeed?.({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问完成通知；未提交答案', requires: '可承载此提问的官方交互接口' });
+            this.need({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问完成通知；未提交答案', requires: '可承载此提问的官方交互接口' });
         })
-            .onRequest('*', () => {
-            this.hooks.onNeed?.({ code: 'ACP_EXTENSION_UNSUPPORTED', message: '首版不支持：远端请求的扩展交互；未授权此动作', requires: '受支持的公开 ACP 交互接口' });
+            .onRequest('*', ({ method, params }) => {
+            this.detail({ kind: 'extension', severity: 'action-required', code: 'ACP_UNKNOWN_REQUEST', summary: '未知远端交互请求未获授权', method, payload: params });
+            this.need({ code: 'ACP_EXTENSION_UNSUPPORTED', message: '首版不支持：远端请求的扩展交互；未授权此动作', requires: '受支持的公开 ACP 交互接口' });
             throw new acp.RequestError(-32601, '不支持此扩展交互');
         })
-            .onNotification('*', () => {
-            this.hooks.onNeed?.({ code: 'ACP_EXTENSION_UNSUPPORTED', message: '首版不支持：收到未知的远端扩展通知', requires: '受支持的公开 ACP 通知接口' });
+            .onNotification('*', ({ method, params }) => {
+            this.detail({ kind: 'extension', severity: 'warning', code: 'ACP_UNKNOWN_NOTIFICATION', summary: '收到未知远端扩展通知，已保留技术记录', method, payload: params });
         });
         if ('readable' in transport && 'writable' in transport)
             this.connection = app.connect(this.observe(transport));
@@ -126,8 +156,7 @@ export class AcpSession {
                 const params = record(raw?.params);
                 const update = record(params?.update);
                 if (raw?.method === acp.methods.client.session.update && typeof update?.sessionUpdate === 'string' && !knownUpdates.has(update.sessionUpdate)) {
-                    if (this.busy && params?.sessionId === this.sessionId)
-                        this.hooks.onNeed?.({ code: 'ACP_UPDATE_UNSUPPORTED', message: `首版不支持：远端事件 ${safeLabel(update.sessionUpdate)}；未展开未知事件内容`, requires: '对应的公开 ACP 显示映射' });
+                    this.detail({ kind: 'extension', severity: 'warning', code: 'ACP_UNKNOWN_UPDATE', summary: '收到未知远端会话事件，已保留结构', method: 'session/update', payload: params });
                     return;
                 }
                 controller.enqueue(message);
@@ -166,12 +195,13 @@ export class AcpSession {
         signal?.addEventListener('abort', abort, { once: true });
         try {
             const hello = await this.connection.agent.request(acp.methods.agent.initialize, {
-                protocolVersion: acp.PROTOCOL_VERSION, clientInfo: { name: '@ai-workbench/remote-agent', version: '0.8.0' },
+                protocolVersion: acp.PROTOCOL_VERSION, clientInfo: { name: '@ai-workbench/remote-agent', version: '0.8.1' },
                 clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false, session: { notices: {} } },
             }, { cancellationSignal: signal });
             this.hooks.broker?.acknowledge(acp.methods.agent.initialize);
             if (hello.protocolVersion !== acp.PROTOCOL_VERSION)
                 throw new NeedError('ACP_VERSION_MISMATCH', 'ACP 协议版本不兼容', '支持 ACP v1 的远端 agent');
+            this.checkReporting();
             this.negotiated = hello.agentCapabilities ?? {};
             const systemPrompt = context?.systemPrompt;
             if (systemPrompt && !this.negotiated.sessionCapabilities?.systemPrompt) {
@@ -197,6 +227,7 @@ export class AcpSession {
                 this.method = acp.methods.agent.session.new;
             }
             this.hooks.broker?.acknowledge(this.method);
+            this.checkReporting();
             this.ready = true;
             this.cwd = cwd;
             this.systemPrompt = systemPrompt ?? '';
@@ -205,6 +236,7 @@ export class AcpSession {
         catch (error) {
             if (signal?.aborted)
                 throw new NeedError('ABORTED', '会话建立已取消；尚无本轮输出', '重新连接主机');
+            this.checkReporting();
             throw acpNeed(error);
         }
         finally {
@@ -212,6 +244,7 @@ export class AcpSession {
         }
     }
     async updateContext(context, signal) {
+        this.checkReporting();
         if (!this.ready || !this.sessionId || !this.cwd)
             throw new NeedError('SESSION_REQUIRED', '我需要先建立远端会话', 'ACP 会话');
         if (this.busy || this.updating)
@@ -233,12 +266,14 @@ export class AcpSession {
             this.hooks.broker?.acknowledge(method);
             this.systemPrompt = text;
             this.ready = true;
-            this.hooks.onNeed?.({ code: 'SYSTEM_PROMPT_UPDATE_DEFERRED', message: '系统与开发者上下文变更已通过原会话恢复接口传送。Claude 恢复会话沿用首次系统提示，新要求在下次上下文整理后生效；不能据此认定本轮已立即生效。', requires: '远端实际应用新要求；Claude 须完成下一次上下文整理' });
+            this.need({ code: 'SYSTEM_PROMPT_UPDATE_DEFERRED', message: '系统与开发者上下文变更已通过原会话恢复接口传送。Claude 恢复会话沿用首次系统提示，新要求在下次上下文整理后生效；不能据此认定本轮已立即生效。', requires: '远端实际应用新要求；Claude 须完成下一次上下文整理' });
+            this.checkReporting();
             return method;
         }
         catch (error) {
             if (signal?.aborted)
                 throw new NeedError('ABORTED', '上下文更新已取消；原会话状态需确认', '重新连接原会话');
+            this.checkReporting();
             throw acpNeed(error);
         }
         finally {
@@ -254,6 +289,7 @@ export class AcpSession {
         signal?.throwIfAborted();
         const prompt = typeof input === 'string' ? [{ type: 'text', text: input }] : input;
         this.validatePrompt(prompt);
+        this.checkReporting();
         this.busy = true;
         this.turnSignal = signal;
         this.turnToken = Symbol('turn');
@@ -262,7 +298,7 @@ export class AcpSession {
         const cancel = () => {
             rejectAbort?.(new NeedError('ABORTED', '已请求取消本轮，远端状态需确认', '确认主机取消状态'));
             void this.connection.agent.notify(acp.methods.agent.session.cancel, { sessionId: this.sessionId }).catch(() => {
-                this.hooks.onNeed?.({ code: 'CANCEL_UNCONFIRMED', message: '连接中断，无法确认主机已取消本轮', requires: '恢复连接以确认远端状态' });
+                this.need({ code: 'CANCEL_UNCONFIRMED', message: '连接中断，无法确认主机已取消本轮', requires: '恢复连接以确认远端状态' });
             });
         };
         signal?.addEventListener('abort', cancel, { once: true });
@@ -272,12 +308,14 @@ export class AcpSession {
             this.hooks.broker?.acknowledge(acp.methods.agent.session.prompt);
             signal?.throwIfAborted();
             this.hooks.broker?.completePrompt();
+            this.checkReporting();
             this.hooks.onResponse?.(result);
             return result.stopReason;
         }
         catch (error) {
             if (signal?.aborted)
                 throw new NeedError('ABORTED', '本轮已取消；已请求主机停止', '确认主机取消状态');
+            this.checkReporting();
             throw acpNeed(error);
         }
         finally {

package/dist/conversation-details.d.ts

@@ -0,0 +1,47 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface DetailScope {
+    instanceId: string;
+    epoch: number;
+    sessionId: string;
+    provider: 'claude' | 'codex';
+    turn: number;
+    step: number;
+}
+export interface DetailObservation {
+    kind: 'extension' | 'commands' | 'tool' | 'usage' | 'notice' | 'need' | 'session';
+    severity: 'info' | 'warning' | 'action-required';
+    code: string;
+    summary: string;
+    method?: string;
+    payload?: unknown;
+}
+export type SanitizedObservation = Omit<DetailObservation, 'payload'> & {
+    payload: JsonValue;
+};
+export interface DetailRecord extends Omit<DetailObservation, 'payload'>, DetailScope {
+    version: 1;
+    eventId: string;
+    sequence: number;
+    payload: JsonValue;
+}
+export type DetailSink = {
+    append(record: Readonly<DetailRecord>): Promise<void>;
+};
+/** Only objects created by this module are trusted as redaction markers. */
+export declare function isSanitizedRedaction(value: unknown): boolean;
+/** Sanitize an internal observation without attaching any L wire semantics. */
+export declare function sanitizeObservation(observation: DetailObservation, protectModelMaterial?: boolean): Readonly<SanitizedObservation>;
+/** Internal diagnostic recorder; a sink is not an assertion that an L wire API exists. */
+export declare class ConversationDetails {
+    private readonly scope;
+    private readonly sink;
+    private readonly records;
+    private tail;
+    private firstFailure;
+    constructor(scope: DetailScope, sink: DetailSink);
+    record(observation: DetailObservation): void;
+    flush(): Promise<void>;
+    snapshot(): readonly DetailRecord[];
+}

package/dist/conversation-details.js

@@ -0,0 +1,319 @@
+import { randomUUID } from 'node:crypto';
+const redactionMarkers = new WeakSet();
+function redaction(fields) {
+    const marker = { redacted: true, ...fields };
+    redactionMarkers.add(marker);
+    return marker;
+}
+/** Only objects created by this module are trusted as redaction markers. */
+export function isSanitizedRedaction(value) {
+    return value !== null && typeof value === 'object' && redactionMarkers.has(value);
+}
+const sensitiveWords = new Set(['auth', 'token', 'tokens', 'password', 'passwords', 'passwd', 'secret', 'secrets', 'authorization', 'cookie', 'cookies', 'credential', 'credentials', 'key', 'keys']);
+const sensitiveCompounds = new Set([
+    'apikey', 'privatekey', 'publickey', 'accesskey', 'secretkey', 'sshkey', 'encryptionkey', 'signingkey',
+    'devicecode', 'usercode', 'onetimecode', 'verificationcode', 'codeverifier', 'authcode', 'authorizationcode', 'authpayload', 'authorizationpayload',
+    'accesstoken', 'refreshtoken', 'idtoken', 'apitoken', 'authtoken', 'sessiontoken', 'bearertoken',
+    'clientsecret', 'tokenpayload', 'tokenvalue', 'passwordpayload', 'passwordvalue', 'secretpayload', 'secretvalue',
+    'credentialpayload', 'credentialspayload', 'cookiepayload', 'keypayload',
+]);
+// These whole words are safe despite containing a credential-like substring.
+// redactedKeys is the recorder's explicit entry-wrapper marker and is stable
+// across repeated sanitization. It is not an exception for arbitrary values.
+const safeWholeFieldWords = new Set(['author', 'monkey', 'keyboard', 'secretary', 'keyword', 'keywords', 'tokenizer', 'tokenization', 'redactedkeys']);
+// A recognized suffix supplies a field boundary after case information is lost.
+// Prefixes remain unrestricted: employeePassword and customApiKey must not depend
+// on an inventory of employee/customer/application-specific field prefixes.
+const sensitiveFieldSuffixes = new Set([
+    '', 'code', 'payload', 'value', 'values', 'data', 'header', 'headers', 'config', 'configuration',
+    'option', 'options', 'detail', 'details', 'info',
+]);
+const unsafeKeys = new Set(['__proto__', 'constructor', 'prototype']);
+function isSensitiveFieldWord(word) {
+    if (safeWholeFieldWords.has(word))
+        return false;
+    if (sensitiveWords.has(word) || sensitiveCompounds.has(word))
+        return true;
+    for (const root of sensitiveWords) {
+        for (let index = word.indexOf(root); index !== -1; index = word.indexOf(root, index + 1)) {
+            // Match roots at the start, or roots ending a field (possibly followed by
+            // a known suffix), rather than fuzzy containment at any word position.
+            if (index === 0 || sensitiveFieldSuffixes.has(word.slice(index + root.length)))
+                return true;
+        }
+    }
+    return false;
+}
+function isSensitiveKey(key) {
+    if (safeWholeFieldWords.has(key.toLowerCase()))
+        return false;
+    // Preserve the original camel/delimiter rule. Anchored field-shape matching
+    // additionally recognizes the same common fields after case normalization.
+    const camelWords = key.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/);
+    const words = key.toLowerCase().split(/[^a-z0-9]+/);
+    return camelWords.some(word => sensitiveWords.has(word)) || words.some(isSensitiveFieldWord)
+        || sensitiveCompounds.has(key.replace(/[^a-z0-9]/gi, '').toLowerCase());
+}
+function unsupported(type, reason) {
+    return { unsupported: true, type, reason };
+}
+function credentialText(value) {
+    return /\bBearer\s+\S+/i.test(value)
+        || /\bsk-[a-z\d_-]+/i.test(value)
+        || /-----BEGIN (?:[A-Z\d]+ )*PRIVATE KEY-----/i.test(value)
+        || /\b(?:gh[pousr]_|github_pat_|xox[baprs]-)[a-z\d_-]+/i.test(value);
+}
+function cleanUrls(value) {
+    let changed = false;
+    const safe = value.replace(/\b[a-z][a-z\d+.-]*:\/\/[^\s<>"'`]+/gi, raw => {
+        let url;
+        try {
+            url = new URL(raw);
+        }
+        catch {
+            changed = true;
+            return '[已脱敏：无法解析URL]';
+        }
+        const userinfo = /^[a-z][a-z\d+.-]*:\/\/[^/?#]*@/i.test(raw);
+        if (!userinfo && !raw.includes('?') && !raw.includes('#'))
+            return raw;
+        url.username = '';
+        url.password = '';
+        url.search = '';
+        url.hash = '';
+        changed = true;
+        return url.toString();
+    });
+    return { value: safe, changed };
+}
+function safeText(value) {
+    if (credentialText(value))
+        return redaction({ reason: '凭据文本' });
+    const url = cleanUrls(value);
+    return url.changed ? redaction({ reason: 'URL敏感部分', value: url.value }) : value;
+}
+function safeLabel(value) {
+    if (typeof value !== 'string')
+        throw new TypeError('Detail observation labels must be strings');
+    // Inspect credentials before removing control characters, so a bearer newline cannot evade detection.
+    if (credentialText(value))
+        return '[已脱敏：凭据文本]';
+    const cleaned = value.replace(/[\u0000-\u001f\u007f-\u009f]/g, '');
+    if (credentialText(cleaned))
+        return '[已脱敏：凭据文本]';
+    const url = cleanUrls(cleaned);
+    return url.changed ? `[已脱敏：URL敏感部分] ${url.value}` : cleaned;
+}
+/** JSON-only snapshot. Non-JSON input is represented, never coerced or executed. */
+function snapshotPayload(value, ancestors = new Set(), protectModelMaterial = false) {
+    if (isSanitizedRedaction(value))
+        return value;
+    if (value === null || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string')
+        return safeText(value);
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : unsupported('number', '非有限数值不能表示为JSON');
+    if (typeof value !== 'object')
+        return unsupported(typeof value, '非JSON值');
+    if (ancestors.has(value))
+        return unsupported('object', '循环引用');
+    let descriptors;
+    let isArray;
+    try {
+        isArray = Array.isArray(value);
+        const prototype = Object.getPrototypeOf(value);
+        if (!isArray && prototype !== Object.prototype && prototype !== null)
+            return unsupported('object', '非JSON普通对象');
+        if (Object.getOwnPropertySymbols(value).some(symbol => Object.getOwnPropertyDescriptor(value, symbol)?.enumerable)) {
+            return unsupported('object', 'JSON不能表示符号字段');
+        }
+        descriptors = Object.getOwnPropertyDescriptors(value);
+    }
+    catch {
+        return unsupported('object', '无法读取对象结构');
+    }
+    if (Object.keys(descriptors).some(key => descriptors[key].enumerable && unsafeKeys.has(key))) {
+        return unsupported('object', '不允许的原型字段');
+    }
+    ancestors.add(value);
+    try {
+        if (isArray) {
+            // Array metadata beyond indexed items is not representable in a JSON array.
+            const length = descriptors.length?.value;
+            if (Object.keys(descriptors).some(key => descriptors[key].enumerable && (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= length))) {
+                return unsupported('array', 'JSON数组不能表示额外字段');
+            }
+            return Array.from({ length }, (_, index) => {
+                const descriptor = descriptors[String(index)];
+                return !descriptor ? unsupported('undefined', '数组空位')
+                    : 'value' in descriptor ? snapshotPayload(descriptor.value, ancestors, protectModelMaterial)
+                        : unsupported('accessor', '不执行访问器');
+            });
+        }
+        const result = {};
+        const entries = [];
+        let redactedKeys = false;
+        for (const [key, descriptor] of Object.entries(descriptors)) {
+            if (!descriptor.enumerable)
+                continue;
+            const name = safeText(key);
+            const value = 'value' in descriptor ? descriptor.value : undefined;
+            const normalized = key.replace(/[^a-z0-9]/gi, '').toLowerCase();
+            const counterNames = new Set(['inputtokens', 'outputtokens', 'cachedinputtokens', 'cachedreadtokens', 'cachedwritetokens', 'thoughtTokens'.toLowerCase(), 'totaltokens', 'cachewriteinputtokens', 'cachereadinputtokens', 'reasoningoutputtokens']);
+            const validCounter = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+            const counter = counterNames.has(normalized) && validCounter(value)
+                || normalized === 'tokencount' && value !== null && typeof value === 'object' && Object.values(Object.getOwnPropertyDescriptors(value)).every(d => 'value' in d && validCounter(d.value)) && Object.keys(value).every(k => counterNames.has(k.replace(/[^a-z0-9]/gi, '').toLowerCase()));
+            const material = protectModelMaterial && (/(?:headers?|body|oldtext|newtext|aggregatedoutput|stdout|stderr)$/.test(normalized)
+                || ['text', 'content', 'prompt', 'input', 'output', 'rawinput', 'rawoutput', 'messages', 'modelinput', 'modeloutput', 'patch', 'diff', 'arguments', 'command', 'commandline', 'filecontent', 'data', 'message', 'usercode', 'devicecode', 'onetimecode'].includes(normalized));
+            const child = ((!counter && isSensitiveKey(key)) || material) ? redaction({ reason: '敏感字段' })
+                : 'value' in descriptor ? snapshotPayload(descriptor.value, ancestors, protectModelMaterial)
+                    : unsupported('accessor', '不执行访问器');
+            if (typeof name !== 'string')
+                redactedKeys = true;
+            // Only safe property names may become object keys. The entry form keeps
+            // distinct original fields even when multiple names redact identically.
+            if (typeof name === 'string')
+                result[name] = child;
+            entries.push({ name, value: child });
+        }
+        return redactedKeys ? { redactedKeys: true, entries } : result;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function freezeDeep(value) {
+    if (value !== null && typeof value === 'object') {
+        for (const child of Object.values(value))
+            freezeDeep(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+function cloneFrozen(value) { return freezeDeep(structuredClone(value)); }
+/** No raw values from unclassified events or tool I/O are approved. The
+ * structure and original JSON types remain inspectable, including unknown keys. */
+function opaqueStructure(value) {
+    if (Array.isArray(value))
+        return value.map(opaqueStructure);
+    if (value !== null && typeof value === 'object') {
+        if (isSanitizedRedaction(value))
+            return value;
+        return Object.fromEntries(Object.entries(value).map(([name, child]) => [name, opaqueStructure(child)]));
+    }
+    return redaction({ valueType: value === null ? 'null' : typeof value });
+}
+/** Structural identifiers are approved only at the SDK/ACP envelope and its
+ * immediate item/update. Arbitrary result subtrees never inherit that trust. */
+function toolStructure(value, level = 'envelope') {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return opaqueStructure(value);
+    if (isSanitizedRedaction(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => {
+        const field = key.replace(/[^a-z0-9]/gi, '').toLowerCase();
+        if (typeof child === 'string' && ['id', 'type', 'kind', 'status', 'code', 'name', 'toolcallid', 'optionid', 'sessionid', 'sessionupdate'].includes(field))
+            return [key, child];
+        if (typeof child === 'number' && ['exitcode', 'durationms'].includes(field))
+            return [key, child];
+        if (level === 'envelope' && ['item', 'update', 'toolCall'].includes(key))
+            return [key, toolStructure(child, 'item')];
+        return [key, opaqueStructure(child)];
+    }));
+}
+function catalogStructure(value, level = 'root') {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return opaqueStructure(value);
+    if (isSanitizedRedaction(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => {
+        if (typeof child === 'string' && ((level === 'entry' && ['name', 'description'].includes(key)) || (level === 'input' && key === 'hint') || (level === 'root' && ['sessionId', 'sessionUpdate'].includes(key))))
+            return [key, child];
+        if (level === 'root' && key === 'update')
+            return [key, catalogStructure(child)];
+        if (level === 'root' && key === 'availableCommands' && Array.isArray(child))
+            return [key, child.map(v => catalogStructure(v, 'entry'))];
+        if (level === 'entry' && key === 'input')
+            return [key, child === null ? null : catalogStructure(child, 'input')];
+        return [key, opaqueStructure(child)];
+    }));
+}
+function usageStructure(value, key = '') {
+    if (Array.isArray(value))
+        return value.map(child => usageStructure(child));
+    if (value !== null && typeof value === 'object') {
+        if (isSanitizedRedaction(value))
+            return value;
+        return Object.fromEntries(Object.entries(value).map(([name, child]) => [name, usageStructure(child, name)]));
+    }
+    const field = key.replace(/[^a-z0-9]/gi, '').toLowerCase();
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && ['inputtokens', 'outputtokens', 'cachedinputtokens', 'cachedreadtokens', 'cachedwritetokens', 'thoughttokens', 'totaltokens', 'cachewriteinputtokens', 'cachereadinputtokens', 'reasoningoutputtokens'].includes(field))
+        return value;
+    if (key === 'stopReason' && typeof value === 'string' && ['end_turn', 'max_tokens', 'max_turn_requests', 'refusal', 'cancelled'].includes(value))
+        return value;
+    return opaqueStructure(value);
+}
+/** Sanitize an internal observation without attaching any L wire semantics. */
+export function sanitizeObservation(observation, protectModelMaterial = false) {
+    const payload = snapshotPayload(observation.payload, new Set(), protectModelMaterial && observation.kind !== 'commands');
+    return freezeDeep({
+        kind: observation.kind, severity: observation.severity,
+        code: safeLabel(observation.code), summary: safeLabel(observation.summary),
+        ...(observation.method === undefined ? {} : { method: safeLabel(observation.method) }),
+        payload: !protectModelMaterial ? payload
+            : observation.kind === 'commands' ? catalogStructure(payload)
+                : observation.kind === 'usage' ? usageStructure(payload)
+                    : observation.kind === 'need' ? payload
+                        : observation.kind === 'tool' || ['SDK_ITEM', 'SDK_TOOL', 'ACP_SESSION_UPDATE', 'ACP_IDLE_UPDATE'].includes(observation.code) ? toolStructure(payload)
+                            : opaqueStructure(payload),
+    });
+}
+function validatedScope(scope) {
+    for (const name of ['instanceId', 'sessionId']) {
+        if (typeof scope[name] !== 'string' || scope[name].trim().length === 0)
+            throw new TypeError(`Invalid detail scope ${name}`);
+    }
+    for (const name of ['epoch', 'turn', 'step']) {
+        if (!Number.isInteger(scope[name]) || scope[name] < (name === 'epoch' ? 0 : 1))
+            throw new TypeError(`Invalid detail scope ${name}`);
+    }
+    if (scope.provider !== 'claude' && scope.provider !== 'codex')
+        throw new TypeError('Invalid detail scope provider');
+    return { instanceId: scope.instanceId, epoch: scope.epoch, sessionId: scope.sessionId, provider: scope.provider, turn: scope.turn, step: scope.step };
+}
+/** Internal diagnostic recorder; a sink is not an assertion that an L wire API exists. */
+export class ConversationDetails {
+    scope;
+    sink;
+    records = [];
+    tail = Promise.resolve();
+    firstFailure;
+    constructor(scope, sink) {
+        this.scope = freezeDeep(validatedScope(scope));
+        this.sink = sink;
+    }
+    record(observation) {
+        const record = freezeDeep({
+            ...this.scope, version: 1, eventId: randomUUID(), sequence: this.records.length + 1,
+            ...sanitizeObservation(observation),
+        });
+        this.records.push(record);
+        this.tail = this.tail.then(async () => {
+            try {
+                await this.sink.append(cloneFrozen(record));
+            }
+            catch (error) {
+                // Keep processing later entries in order, but never turn a failed flush green.
+                if (!this.firstFailure)
+                    this.firstFailure = { error };
+            }
+        });
+    }
+    async flush() {
+        await this.tail;
+        if (this.firstFailure)
+            throw this.firstFailure.error;
+    }
+    snapshot() { return cloneFrozen(this.records); }
+}