@ai-workbench/remote-agent 0.0.0-stage → 0.8.1

package/dist/broker.js

@@ -0,0 +1,397 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { protectedOneShotLayout } from "./host-layout.js";
+import { NeedError, shellQuote } from "./remote.js";
+import { CODEX_AGENT } from "./agents.js";
+import { identity, unwrap, validateTarget, sameTarget } from "./provider.js";
+/** One byte stream / SDK app, multiple SSH attachments. Input is never replayed. */
+export class BrokerTransport {
+    readable;
+    writable;
+    options;
+    output;
+    attachment;
+    cursor = 0;
+    epoch = 0;
+    attached = false;
+    ended = false;
+    joining;
+    lease = new AbortController();
+    listeners = new Set();
+    permits = new Map();
+    approvalSent = false;
+    unconfirmed = new Set();
+    failure;
+    constructor(options) {
+        if (!Number.isSafeInteger(options.maxFrameBytes) || options.maxFrameBytes < 1)
+            throw new NeedError('SETTINGS_REQUIRED', '我需要 brokerMaxFrameBytes', '管理员确认 brokerMaxFrameBytes');
+        this.options = options;
+        this.lease.abort();
+        this.readable = new ReadableStream({ start: c => { this.output = c; }, pull: () => { this.attachment?.stdout.resume(); }, cancel: () => { this.close(); } });
+        this.writable = new WritableStream({ write: bytes => this.write(bytes), close: () => this.close(), abort: () => this.close() });
+    }
+    get online() { return this.attached && !this.ended; }
+    get generation() { return this.epoch; }
+    get signal() { return this.lease.signal; }
+    get lastSequence() { return this.cursor; }
+    get error() { return this.failure; }
+    authorizeResponse(id, generation) { this.permits.set(JSON.stringify(id), generation); }
+    /** Called only by the ACP protocol layer after a matching result or current-turn output. */
+    acknowledge(method) { this.unconfirmed.delete(method); }
+    /** A matching terminal prompt response settles all approval replies in that turn. */
+    completePrompt() { this.unconfirmed.delete('session/prompt'); this.approvalSent = false; for (const key of this.unconfirmed)
+        if (key.startsWith('response:'))
+            this.unconfirmed.delete(key); }
+    onChange(fn) { this.listeners.add(fn); return () => this.listeners.delete(fn); }
+    changed() { for (const fn of this.listeners)
+        fn(); }
+    notice(code, message) { this.options.onNeed?.({ code, message, requires: '恢复原员工主机连接或显式结束本轮' }); }
+    fail(error) {
+        if (this.ended)
+            return;
+        this.failure = error;
+        this.ended = true;
+        this.attached = false;
+        this.lease.abort();
+        this.notice(error.code, error.message);
+        this.changed();
+        this.attachment?.kill('SIGTERM');
+        try {
+            this.output.error(error);
+        }
+        catch { /* Reader already cancelled. */ }
+    }
+    close() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.attached = false;
+        this.lease.abort();
+        this.changed();
+        this.attachment?.kill('SIGTERM');
+        try {
+            this.output.close();
+        }
+        catch { /* Reader already cancelled. */ }
+    }
+    async waitOnline(signal) {
+        signal?.throwIfAborted();
+        if (this.online)
+            return;
+        if (this.ended)
+            throw this.failure ?? new NeedError('SESSION_ENDED', '远端会话已结束', '重新建立会话');
+        await new Promise((resolve, reject) => {
+            const done = () => { off(); signal?.removeEventListener('abort', abort); };
+            const changed = () => { if (this.online) {
+                done();
+                resolve();
+            }
+            else if (this.ended) {
+                done();
+                reject(this.failure ?? new NeedError('SESSION_ENDED', '远端会话已结束', '重新建立会话'));
+            } };
+            const abort = () => { done(); reject(new NeedError('ABORTED', '本轮已取消', '确认主机状态')); };
+            const off = this.onChange(changed);
+            signal?.addEventListener('abort', abort, { once: true });
+            changed();
+        });
+    }
+    connect() {
+        if (this.online)
+            return Promise.resolve();
+        if (this.joining)
+            return this.joining;
+        if (this.ended)
+            return Promise.reject(this.failure ?? new NeedError('SESSION_ENDED', '远端会话已结束', '重新建立会话'));
+        this.joining = this.attach().finally(() => { this.joining = undefined; });
+        return this.joining;
+    }
+    async attach() {
+        const child = await this.options.attach(this.cursor);
+        if (this.ended) {
+            child.kill('SIGTERM');
+            throw new NeedError('SESSION_ENDED', '本轮已结束', '重新连接');
+        }
+        this.attachment = child;
+        this.epoch++;
+        const generation = this.epoch;
+        child.stderr.resume();
+        child.stdin.on('error', () => { });
+        let partial = Buffer.alloc(0);
+        let ready = false;
+        const connected = Promise.withResolvers();
+        // A local end suppresses detached(), so settle the handshake independently.
+        const off = this.onChange(() => { if (this.ended)
+            connected.reject(this.failure ?? new NeedError('SESSION_ENDED', '远端会话已结束', '重新建立会话')); });
+        const fatal = (error) => { connected.reject(error); this.fail(error); };
+        const frame = (f) => {
+            if (f.type === 'ready') {
+                if (ready)
+                    throw new NeedError('BROKER_PROTOCOL_INVALID', 'broker 重复 ready', '有效的 broker 帧');
+                ready = true;
+                this.attached = true;
+                this.lease = new AbortController();
+                this.changed();
+                connected.resolve();
+                return;
+            }
+            if (f.type === 'error')
+                throw new NeedError(typeof f.code === 'string' ? f.code : 'BROKER_FAILED', '主机会话无法续接（' + (typeof f.code === 'string' ? f.code : '未知错误') + '）；没有重放输入或代答审批', '恢复或显式结束原会话');
+            if (f.type === 'exit') {
+                connected.reject(new NeedError('AGENT_EXITED', '主机 agent 已退出', '重新建立会话'));
+                this.fail(new NeedError('AGENT_EXITED', '主机 agent 已退出，退出状态不代表本轮完成', '确认主机状态'));
+                return;
+            }
+            if (f.type !== 'data' || !Number.isSafeInteger(f.seq) || f.seq < 1 || (f.channel !== 'stdout' && f.channel !== 'stderr') || typeof f.data !== 'string' || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(f.data))
+                throw new NeedError('BROKER_PROTOCOL_INVALID', 'broker 输出帧无效', '有效的序号/通道/base64 数据');
+            const seq = f.seq;
+            if (seq <= this.cursor)
+                return;
+            if (seq !== this.cursor + 1)
+                throw new NeedError('REPLAY_GAP', '主机输出存在缺口，不能安全继续审批', '显式结束或恢复原会话');
+            if (f.channel === 'stdout')
+                this.output.enqueue(Buffer.from(f.data, 'base64'));
+            this.cursor = seq;
+            if ((this.output.desiredSize ?? 0) <= 0)
+                child.stdout.pause();
+        };
+        child.stdout.on('data', (bytes) => {
+            if (this.ended || generation !== this.epoch)
+                return;
+            try {
+                partial = Buffer.concat([partial, bytes]);
+                let newline;
+                while ((newline = partial.indexOf(10)) >= 0) {
+                    if (newline > this.options.maxFrameBytes)
+                        throw new NeedError('BROKER_FRAME_TOO_LARGE', 'broker 输出超出具名帧大小设置', '管理员调整 brokerMaxFrameBytes');
+                    const line = partial.subarray(0, newline);
+                    partial = partial.subarray(newline + 1);
+                    const parsed = JSON.parse(line.toString('utf8'));
+                    if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object')
+                        throw Error('frame');
+                    frame(parsed);
+                    if (this.ended)
+                        return;
+                }
+                if (partial.length > this.options.maxFrameBytes)
+                    throw new NeedError('BROKER_FRAME_TOO_LARGE', 'broker 输出超出具名帧大小设置', '管理员调整 brokerMaxFrameBytes');
+            }
+            catch (error) {
+                fatal(error instanceof NeedError ? error : new NeedError('BROKER_PROTOCOL_INVALID', 'broker 输出帧无法解析', '有效的 broker 输出'));
+            }
+        });
+        const detached = () => {
+            if (generation !== this.epoch || this.ended)
+                return;
+            this.attached = false;
+            this.lease.abort();
+            this.changed();
+            if (!ready) {
+                fatal(new NeedError('BROKER_ATTACH_FAILED', '主机会话附着失败；根因未查明', '有效的原员工 SSH/broker 连接'));
+                return;
+            }
+            // A matching remote receipt can precede the local stdin write callback.
+            // The protocol ledger, rather than that callback's timing, owns delivery.
+            if (this.approvalSent || this.unconfirmed.size) {
+                fatal(new NeedError('INPUT_DELIVERY_UNCONFIRMED', '输入或审批应答尚无协议收件证明时连接中断；不会重发或再次批准', '显式结束原进程并检查项目状态'));
+                return;
+            }
+            this.notice('CONNECTION_LOST', '连接中断，主机可能正在等待你的审批；重连前不发送审批');
+            void this.options.onDisconnect?.().catch(error => this.fail(error instanceof NeedError ? error : new NeedError('RECONNECT_FAILED', '续接失败，根因未查明', '恢复原连接')));
+        };
+        child.once('error', detached);
+        child.once('close', detached);
+        return connected.promise.finally(off);
+    }
+    async write(bytes) {
+        if (!this.online || !this.attachment)
+            throw new NeedError('INPUT_DELIVERY_UNCONFIRMED', '连接不在线，输入没有排队或重放', '恢复连接并确认原会话状态');
+        let response;
+        try {
+            response = JSON.parse(Buffer.from(bytes).toString('utf8'));
+        }
+        catch {
+            throw new NeedError('ACP_INPUT_INVALID', 'ACP 输出不是一条完整 JSON 消息', '有效的 ACP SDK 字节输出');
+        }
+        const selected = response.result?.outcome?.outcome === 'selected';
+        if (selected) {
+            const key = JSON.stringify(response.id);
+            const permit = this.permits.get(key);
+            this.permits.delete(key);
+            if (permit !== this.epoch)
+                throw new NeedError('APPROVAL_STALE', '连接已改变，旧审批未发送', '重连后的本次审批');
+            this.approvalSent = true;
+        }
+        this.unconfirmed.add(response.method ?? 'response:' + JSON.stringify(response.id));
+        const child = this.attachment;
+        await new Promise((resolve, reject) => {
+            const closed = () => { cleanup(); reject(new NeedError('INPUT_DELIVERY_UNCONFIRMED', '输入送达未确认，未重发', '确认原进程状态')); };
+            const cleanup = () => { child.removeListener('close', closed); };
+            child.once('close', closed);
+            child.stdin.write(bytes, error => { cleanup(); error ? reject(new NeedError('INPUT_DELIVERY_UNCONFIRMED', '输入送达失败，未重发', '确认原进程状态')) : resolve(); });
+        });
+    }
+}
+export function controlNeed(stderr) {
+    let code = 'BROKER_CONTROL_FAILED';
+    try {
+        const result = JSON.parse(stderr);
+        if (typeof result?.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(result.code))
+            code = result.code;
+    }
+    catch { /* Only the declared JSON error code is public, never raw stderr. */ }
+    return new NeedError(code, code === 'EACCES' ? '我需要管理员让该员工可读、不可写主机会话配置；当前路径访问被拒绝' : `主机会话控制失败（${code}）；根因${code === 'BROKER_CONTROL_FAILED' ? '未查明' : '见错误代码'}，没有重试或新建替代进程`, code === 'EACCES' ? '员工可读且员工不可写的 session.settingsPath' : '恢复原员工 broker 连接并确认会话状态');
+}
+export function sshIo(target, argv, maxControlBytes) {
+    const base = argv(target);
+    return { attach: async (command) => spawn('ssh', [...base, command], { stdio: ['pipe', 'pipe', 'pipe'] }), run: (command, signal) => new Promise((resolve, reject) => {
+            const child = spawn('ssh', ['-n', ...base, command], { stdio: ['ignore', 'pipe', 'pipe'] });
+            let bytes = Buffer.alloc(0);
+            let diagnostics = Buffer.alloc(0);
+            let failure;
+            const abort = () => { failure = new NeedError('ABORTED', '主机会话操作已取消，需确认进程状态', '确认主机状态'); child.kill('SIGTERM'); };
+            if (signal?.aborted)
+                abort();
+            else
+                signal?.addEventListener('abort', abort, { once: true });
+            child.stdout.on('data', (b) => { if (failure)
+                return; bytes = Buffer.concat([bytes, b]); if (bytes.length > maxControlBytes) {
+                failure = new NeedError('BROKER_CONTROL_TOO_LARGE', 'broker 控制响应超过具名大小设置', '管理员调整 brokerControlMaxBytes');
+                child.kill('SIGTERM');
+            } });
+            child.stderr.on('data', (b) => { if (failure)
+                return; diagnostics = Buffer.concat([diagnostics, b]); if (diagnostics.length > maxControlBytes) {
+                failure = new NeedError('BROKER_CONTROL_TOO_LARGE', 'broker 错误响应超过具名大小设置', '管理员调整 brokerControlMaxBytes');
+                child.kill('SIGTERM');
+            } });
+            child.on('error', () => { failure = new NeedError('SSH_FAILED', 'SSH 启动失败，根因未查明', '有效的 SSH 执行程序'); });
+            child.on('close', code => { signal?.removeEventListener('abort', abort); failure ? reject(failure) : code === 0 ? resolve(bytes.toString('utf8')) : reject(controlNeed(diagnostics.toString('utf8'))); });
+        }) };
+}
+export function brokerCommand(t, args) { return `AW_SESSION_ROOT=${shellQuote(t.session.root)} ${shellQuote(t.session.command)} ${args.map(shellQuote).join(' ')}`; }
+export function brokerId(sessionId, agentId = CODEX_AGENT.id) { return (agentId === CODEX_AGENT.id ? 'x' : 'a') + createHash('sha256').update(agentId === CODEX_AGENT.id ? sessionId : agentId + '/' + sessionId).digest('hex').slice(0, 23); }
+function controlJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new NeedError('BROKER_PROTOCOL_INVALID', 'broker 控制响应不是有效 JSON，未复制原始输出', '有效的 broker 控制响应');
+    }
+}
+export function brokerFactory(get, _ask, configuration, provided) {
+    const active = new Set();
+    const retained = new Map();
+    const open = async (target, project, request) => {
+        const settings = request.brokerSettings ?? (typeof configuration === 'function' ? configuration() : configuration);
+        if (!request.sessionId)
+            throw new NeedError('SESSION_REQUIRED', '我需要当前 DSH 会话标识', 'DSH sessionId');
+        if (request.mode === 'one-shot') {
+            return { identity: identity(target), cwd: project.path, oneShot: { target, cwd: project.path, ...protectedOneShotLayout(target) } };
+        }
+        if (![settings.brokerMaxFrameBytes, settings.brokerControlMaxBytes].every(n => Number.isSafeInteger(n) && n > 0))
+            throw new NeedError('SETTINGS_REQUIRED', '我需要管理员确认 broker 帧和控制响应大小设置', 'brokerMaxFrameBytes / brokerControlMaxBytes（无默认）');
+        let argv = provided?.argv;
+        if (!provided?.io && !argv) {
+            try {
+                const moduleName = '@ai-workbench/connect';
+                const supplied = await import(__rewriteRelativeImportExtension(moduleName));
+                if (typeof supplied.sshArgs !== 'function')
+                    throw Error('missing sshArgs');
+                argv = supplied.sshArgs;
+            }
+            catch {
+                throw new NeedError('DEPENDENCY_REQUIRED', '我需要 connect 0.3.0 包导出的 sshArgs 来执行可信 SSH', '@ai-workbench/connect 0.3.0');
+            }
+        }
+        const ioFor = (t) => provided?.io?.(t) ?? sshIo(t, argv, settings.brokerControlMaxBytes);
+        const agent = request.agent ?? CODEX_AGENT;
+        let io = ioFor(target);
+        const id = brokerId(request.sessionId, agent.id);
+        const command = (args) => brokerCommand(target, args);
+        const list = controlJson(await io.run(command(['list']), request.signal));
+        if (!Array.isArray(list) || list.some(s => typeof s?.id !== 'string'))
+            throw new NeedError('BROKER_PROTOCOL_INVALID', '主机会话列表无效', '有效的 broker 列表');
+        if (list.some(s => s.id === id)) {
+            throw new NeedError('ACP_CLIENT_LOST', '我需要管理员确认并结束遗留的主机会话；当前保留原进程，没有代答旧审批', '管理员核对并明确结束对应主机会话');
+        }
+        const started = controlJson(await io.run(command(['start', id, '--cwd', project.path, '--settings', target.session.settingsPath, '--', agent.command]), request.signal));
+        if (started?.protocolVersion !== 1 || started.id !== id || !Number.isSafeInteger(started.pid) || started.pid < 1 || typeof started.socket !== 'string')
+            throw new NeedError('BROKER_START_UNCONFIRMED', 'broker 未返回匹配的启动确认，需确认遗留会话；未自动新建替代进程', `确认主机会话 ${id} 的状态`);
+        let transport;
+        transport = new BrokerTransport({ maxFrameBytes: settings.brokerMaxFrameBytes, attach: after => io.attach(command(['attach', id, '--after', String(after), '--framed'])), onDisconnect: async () => {
+                const connect = get();
+                if (!connect)
+                    throw new NeedError('DEPENDENCY_REQUIRED', '我需要连接插件恢复员工连接', 'aiWorkbenchConnect');
+                const next = unwrap(await connect.getSshTarget());
+                validateTarget(next);
+                if (!sameTarget(next, target))
+                    throw new NeedError('SESSION_CONTEXT_MISMATCH', '重连目标与原会话不一致', '原员工主机、可信SSH参数和broker');
+                io = ioFor(next);
+                await transport.connect();
+            } });
+        const aborted = () => transport.fail(new NeedError('ABORTED', '本轮已取消，正在结束主机进程', '确认主机状态'));
+        request.signal?.addEventListener('abort', aborted, { once: true });
+        if (request.signal?.aborted)
+            aborted();
+        const dispose = async () => { request.signal?.removeEventListener('abort', aborted); transport.close(); try {
+            await io.run(command(['kill', id]));
+        }
+        catch {
+            throw new NeedError('REMOTE_CLEANUP_UNCONFIRMED', '无法确认原主机会话已结束；不会自动新建替代进程', '恢复连接并结束对应主机会话');
+        } };
+        try {
+            await transport.connect();
+            request.signal?.throwIfAborted();
+            if (request.retainProcess)
+                request.signal?.removeEventListener('abort', aborted);
+        }
+        catch (error) {
+            await dispose();
+            throw error;
+        }
+        return { identity: identity(target), cwd: project.path, broker: transport, acpTransport: transport, dispose };
+    };
+    return async (target, project, request) => {
+        const key = (request.agent ?? CODEX_AGENT).id + '/' + identity(target) + '/' + request.sessionId;
+        const existing = request.retainProcess ? retained.get(key) : undefined;
+        if (existing) {
+            const settings = request.brokerSettings ?? (typeof configuration === 'function' ? configuration() : configuration);
+            if (existing.cwd !== project.path || existing.settings.brokerMaxFrameBytes !== settings.brokerMaxFrameBytes || existing.settings.brokerControlMaxBytes !== settings.brokerControlMaxBytes || !sameTarget(existing.target, target))
+                throw new NeedError('SESSION_CONTEXT_MISMATCH', '会话工作区、可信SSH参数或主机运行设置已改变，请新建会话', '原会话的可信主机、工作区与运行设置');
+            if (existing.runtime.broker?.error)
+                throw existing.runtime.broker.error;
+            return existing.runtime;
+        }
+        if (active.has(key))
+            throw new NeedError('TURN_BUSY', '当前 DSH 会话已有远端运行，不能当作遗留进程结束', '等待当前运行结束');
+        active.add(key);
+        try {
+            const runtime = await open(target, project, request);
+            const dispose = runtime.dispose;
+            let disposed = false;
+            runtime.dispose = async () => { if (disposed)
+                return; disposed = true; try {
+                await dispose?.();
+            }
+            finally {
+                active.delete(key);
+                retained.delete(key);
+            } };
+            if (request.retainProcess && request.mode === 'session')
+                retained.set(key, { runtime, cwd: project.path, settings: { ...(request.brokerSettings ?? (typeof configuration === 'function' ? configuration() : configuration)) }, target });
+            return runtime;
+        }
+        catch (error) {
+            active.delete(key);
+            throw error;
+        }
+    };
+}

package/dist/client.js

@@ -0,0 +1,36 @@
+/* Official locale and provider-registration updates only; no custom UI or refresh. */
+window.__ModuleLoader__.load({id:'@ai-workbench/remote-agent',factory(){
+  const messages={"en":{"administratorNote":"Administrators: use Settings → Open configuration file to edit the existing plugin entry. See README for the six fields and approved defaults.","providerName":"Codex (Remote Host)"},"zh":{"administratorNote":"管理员：从设置使用“打开配置文件”，修改已有插件条目；六个字段和已批准默认值见 README。","providerName":"Codex（远程主机）"}};
+  return{inject:['locale','connection'],apply(ctx){
+    ctx.effect(()=>ctx.locale.register('ai-workbench-codex',messages),'Codex official translations');
+    ctx.effect(()=>{
+      let disposed=false,connected=false,previous,generation=0,request=new AbortController(),queue=Promise.resolve();
+      const sync=()=>{
+        if(disposed||!connected)return;
+        const active=ctx.locale.getSnapshot().active;
+        const language=active.split('-')[0].toLowerCase()==='zh'?'zh':'en';
+        if(language===previous)return;
+        previous=language;
+        const mine=generation,signal=request.signal;
+        queue=queue.then(async()=>{
+          if(disposed||signal.aborted||mine!==generation)return;
+          const result=await ctx.connection.rpc.call('/api','awCodexPresentation/setLocale',{args:{language}},signal);
+          signal.throwIfAborted();
+          if(result?.ok!==true||result.value?.language!==language||result.value?.name!==messages[language].providerName){
+            throw Object.assign(new Error('Provider-name locale sync was not confirmed'),{code:result?.ok===false&&typeof result.error?.code==='string'?result.error.code:'LOCALE_SYNC_INVALID'});
+          }
+        }).catch(error=>{
+          if(!disposed&&!signal.aborted&&mine===generation)ctx.logger.warn('Codex provider-name locale update failed',typeof error?.code==='string'?error.code:'LOCALE_SYNC_FAILED');
+        });
+      };
+      const link=()=>{
+        const next=ctx.connection.state.getSnapshot()==='connected';
+        if(next===connected)return;
+        connected=next;generation++;previous=undefined;request.abort();request=new AbortController();
+        if(connected)sync();
+      };
+      const offLocale=ctx.locale.subscribe(sync),offConnection=ctx.connection.state.subscribe(link);link();
+      return()=>{disposed=true;offLocale();offConnection();request.abort();};
+    },'Codex provider names follow the official locale');
+  }};
+}});

package/dist/connect-contract.d.ts

@@ -0,0 +1,26 @@
+import type { ConnectTarget } from './provider.ts';
+import type { ContractInfo, Provider, WorkspaceUse, WorkspaceNoticeReceipt as LWorkspaceNoticeReceipt } from '@ai-workbench/connect/api';
+/** 正式L0.7公开类型；消费子集不表示已安装或已通过真实产品门。 */
+export type { WorkspaceNotice, SessionProjectTarget } from '@ai-workbench/connect/api';
+import type { SessionProjectTarget } from '@ai-workbench/connect/api';
+export type LoginProvider = Provider;
+export type WorkspaceNoticeReceipt = Extract<LWorkspaceNoticeReceipt, {
+    surface: 'provider';
+}>;
+export type ConnectResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        requires: string;
+    };
+};
+export interface NativeWorkspaceApi {
+    getContractInfo(): ContractInfo;
+    ensureReady(provider: LoginProvider): Promise<ConnectResult<ConnectTarget>>;
+    resolveSessionProject(sessionId: string, use: WorkspaceUse): Promise<ConnectResult<SessionProjectTarget>>;
+    acknowledgeWorkspaceNotice(receipt: WorkspaceNoticeReceipt): Promise<ConnectResult<void>>;
+}

package/dist/connect-contract.js

@@ -0,0 +1 @@
+export {};

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[];
+}