@1agents/session-reader 0.6.1 → 0.7.0

package/README.md

@@ -71,6 +71,21 @@ npx @1agents/session-reader list      # 不安装直接用
 其他开关：`--agent claude,codex`（只装指定的几家，即使该智能体尚未安装也会建目录，
 方便先装 skill 后装智能体）、`--dry-run`（只说会做什么）、`--force`（覆盖同名条目）。
 
+**别用 `npx` 跑 `skill install`。** 默认的链接模式会指回包所在目录，而 npx 装的那份在
+`~/.npm/_npx/<hash>/` 的缓存里，npm 自己会清。清掉那天五家的 skill 一起静悄悄消失。
+先 `npm i -g` 再 `skill install`；实在要从 npx 引导就加 `--copy`，把字节交给各家自己拿着。
+
+传播给别人时，两行就够——第二行是大家会忘的那行：只装 CLI 的人得自己记着它存在，
+两行都跑了的人是智能体替他记着。
+
+```bash
+npm i -g @1agents/session-reader
+1session skill install
+```
+
+skill 自己也带着这套安装说明（`skills/1session/references/install.md`）：即便对方只拿到
+一份 SKILL.md、机器上没有 CLI，它也会先用 `npx` 把问题回答掉，再回头提一次永久安装。
+
 ## CLI
 
 ```bash
@@ -458,6 +473,18 @@ $ 1session graph ca8325e1
 
 运行时捕获：若环境注入了 `SESSION_READER_CALLER_SESSION`，调用当下就直接落边（`observed / runtime:caller-env`），无需事后从历史里恢复。
 
+## `1session web`：独立浏览器
+
+没有 DSH 也能看同一套历史会话列表、对话预览和文件账本：
+
+```bash
+1session web                 # http://127.0.0.1:7780
+1session web --open          # 启动后打开默认浏览器
+1session web --scope global  # 默认列出全部工作区
+```
+
+列表只拉元数据，点击某一条会话后再加载对话与文件。这和 `1session serve`（DreamMate Network 的 JSON 服务）不是同一件事。
+
 ## `1session serve`：接入 DreamMate Network
 
 把本地 Read Plane 原样暴露成网络能力——`1session overview <id>` 成为 `sessions.read`。
@@ -538,6 +565,21 @@ base_url  http://scott-mac.tailfb4720.ts.net:7777/v1   ← MagicDNS，跨机可
 > 而共用同一份定义才谈得上「公共语言」。**schema 是唯一事实源，改类型先去改那个包。**
 > `/manifest` 的 `metadata.protocol_version` 报告本服务遵循的协议版本。
 
+### SQLite 的 TEXT 列会在 NUL 处截断
+
+存进去 `A<NUL>B`，读出来只剩 `A`——**不报错**，安静地丢掉后面全部内容。
+实测一个 antigravity 会话里 `wsl -l -v` 的 UTF-16 输出被当 UTF-8 读，产生交错
+的 NUL，502 字符的 `tool_result` 存完只剩 342，后面 160 个字符凭空消失。
+
+改存 BLOB 能保真，但 `text` / `tool_result` 上有 SQL 搜索（`LIKE` 对 BLOB 不
+工作），所以走**写入转义、读取还原**（`src/store/nul.ts`）。引导符用 U+FFFF：
+Unicode 明确规定的 noncharacter，不会出现在有效文本里；万一真出现也会被双写，
+还原无歧义。绝大多数内容两个字符都不含，直接原样返回，常态零开销。
+
+这类 bug 的可怕之处在于**没有任何报错**——只有 round-trip 测试
+（`readSession(db,row)` 深度等于 `adapter.parse(candidate)`）能抓到它。
+那条断言就是整个索引层的安全网：一旦索引在改写事实而不是缓存事实，它就会红。
+
 ## 测试
 
 ```bash

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# DeepSeek Harness bundle patch for @1agents/session-reader
+- insert:
+    - id: session-reader
+      name: '@1agents/session-reader'

package/dist/bin/1session.js

@@ -27,6 +27,8 @@ const USAGE = `1session — cross-agent session Read Plane
   1session graph <session-id> [--json]                 会话之间的引用关系
   1session serve [--port 7777] [--host 127.0.0.1] [--token <t>] [--no-report]
                           起 HTTP Service，把本机会话接入 DreamMate Network
+  1session web [--port 7780] [--host 127.0.0.1] [--open] [--scope <path>|cwd|global]
+                          起独立 Web 端，浏览历史会话列表、对话与文件（无需 DSH）
   1session skill install|status|uninstall [--agent claude,codex,antigravity,grok,dsh]
                           [--copy] [--force] [--dry-run] [--json]  装到五家智能体的 skills 目录
   1session search <query> [--scope <path>|cwd|global] [--since 24h] [--limit n] [--provider name]
@@ -48,7 +50,7 @@ Providers: antigravity (~/.gemini/antigravity/brain), claude (~/.claude/projects
 /** Flags that never take a value, so they cannot swallow a positional. */
 const BOOLEAN_FLAGS = new Set([
     'json', 'failed', 'digest', 'regex', 'case', 'all', 'force', 'no-index', 'global',
-    'copy', 'dry-run', 'no-report', 'include-self',
+    'copy', 'dry-run', 'no-report', 'include-self', 'open',
 ]);
 function parseArgs(argv) {
     const [command = 'help', ...rest] = argv;
@@ -479,6 +481,29 @@ async function main() {
             await new Promise(() => { });
             break;
         }
+        case 'web': {
+            const { serveWeb, DEFAULT_WEB_PORT } = await import('../src/web/server.js');
+            const scope = str(flags.scope) ?? (flags.global === true ? 'global' : 'cwd');
+            let cwd = process.cwd();
+            let defaultScope = 'cwd';
+            if (scope === 'global') {
+                defaultScope = 'global';
+            }
+            else if (scope !== 'cwd') {
+                cwd = canonicalizePath(scope);
+                if (!existsSync(cwd))
+                    throw new Error(`--scope 目录不存在：${scope}`);
+            }
+            await serveWeb({
+                port: num(flags.port) ?? DEFAULT_WEB_PORT,
+                host: str(flags.host) ?? '127.0.0.1',
+                cwd,
+                defaultScope,
+                open: flags.open === true,
+            });
+            await new Promise(() => { });
+            break;
+        }
         case 'skill': {
             const { describeState, installSkill, skillStatus, uninstallSkill, bundledSkillDir, } = await import('../src/skill.js');
             const agents = str(flags.agent)

package/dist/src/dsh/adapter.d.ts

@@ -0,0 +1,18 @@
+import type { NormalizedSession } from '../types.js';
+export interface DshSessionEvent {
+    type: string;
+    seq: number;
+    time: number;
+    surfaceOp?: 'append';
+    data: Record<string, unknown>;
+}
+export interface ConvertOptions {
+    /** Initial sequence number, defaults to 0 (DSH 0-based sequence convention). */
+    startSeq?: number;
+}
+/**
+ * Converts a normalized session from @1agents/session-reader (across Claude, Codex,
+ * Antigravity, Grok, or DSH) into an ordered sequence of DSH SessionEvents suitable
+ * for direct ingestion and rendering by DSH Client UI (@deepseek-ai/dsh-client-ui-chat).
+ */
+export declare function convertSessionToDshEvents(session: NormalizedSession, options?: ConvertOptions): DshSessionEvent[];

package/dist/src/dsh/adapter.js

@@ -0,0 +1,198 @@
+/**
+ * Converts a normalized session from @1agents/session-reader (across Claude, Codex,
+ * Antigravity, Grok, or DSH) into an ordered sequence of DSH SessionEvents suitable
+ * for direct ingestion and rendering by DSH Client UI (@deepseek-ai/dsh-client-ui-chat).
+ */
+export function convertSessionToDshEvents(session, options = {}) {
+    const events = [];
+    let seq = options.startSeq ?? 0;
+    let currentTurn = 1;
+    let currentStep = 1;
+    let turnOpen = false;
+    let stepOpen = false;
+    const defaultTime = session.ref.createdAt
+        ? Date.parse(session.ref.createdAt)
+        : Date.now();
+    function parseTime(timestamp) {
+        if (!timestamp)
+            return defaultTime;
+        const parsed = Date.parse(timestamp);
+        return isNaN(parsed) ? defaultTime : parsed;
+    }
+    function emit(type, data, time, surfaceOp) {
+        events.push({
+            type,
+            seq: seq++,
+            time,
+            ...(surfaceOp ? { surfaceOp } : {}),
+            data,
+        });
+    }
+    function ensureTurnStart(turnNum, time) {
+        if (!turnOpen) {
+            emit('turn/start', { turn: turnNum }, time);
+            turnOpen = true;
+        }
+    }
+    function ensureStepStart(turnNum, stepNum, time) {
+        ensureTurnStart(turnNum, time);
+        if (!stepOpen) {
+            emit('step/start', { turn: turnNum, step: stepNum }, time);
+            stepOpen = true;
+        }
+    }
+    function closeStep(turnNum, stepNum, time) {
+        if (stepOpen) {
+            emit('step/end', { turn: turnNum, step: stepNum }, time);
+            stepOpen = false;
+        }
+    }
+    function closeTurn(turnNum, time, reason = 'completed') {
+        closeStep(turnNum, currentStep, time);
+        if (turnOpen) {
+            emit('turn/end', { turn: turnNum, reason: { kind: reason } }, time);
+            turnOpen = false;
+        }
+    }
+    const providerName = session.ref.provider || 'external';
+    const modelName = session.stats.models[0] || 'assistant';
+    if (session.ref.title && session.ref.title.trim()) {
+        emit('session/title', {
+            title: session.ref.title.trim(),
+            messageSeqs: [],
+            source: { kind: 'user' },
+        }, defaultTime);
+    }
+    for (let i = 0; i < session.turns.length; i++) {
+        const turnEvent = session.turns[i];
+        const eventTime = parseTime(turnEvent.timestamp);
+        switch (turnEvent.kind) {
+            case 'user': {
+                // A new user prompt begins a new turn
+                if (turnOpen) {
+                    closeTurn(currentTurn, eventTime);
+                    currentTurn++;
+                    currentStep = 1;
+                }
+                ensureStepStart(currentTurn, currentStep, eventTime);
+                emit('user/message', {
+                    id: `msg-${turnEvent.id}`,
+                    role: 'user',
+                    content: [{ type: 'text', text: turnEvent.text ?? '' }],
+                    source: { kind: 'user' },
+                }, eventTime, 'append');
+                break;
+            }
+            case 'thinking': {
+                ensureStepStart(currentTurn, currentStep, eventTime);
+                const thinkingText = turnEvent.text ?? '';
+                if (thinkingText.trim()) {
+                    emit('assistant/message', {
+                        turn: currentTurn,
+                        step: currentStep,
+                        message: {
+                            id: `asst-think-${turnEvent.id}`,
+                            role: 'assistant',
+                            content: [{ type: 'reasoning', text: thinkingText }],
+                            source: { kind: 'model', provider: providerName, model: modelName },
+                        },
+                        stream: [
+                            {
+                                type: 'chunk',
+                                time: eventTime,
+                                chunk: {
+                                    type: 'reasoning-delta',
+                                    index: 0,
+                                    text: thinkingText,
+                                },
+                            },
+                        ],
+                    }, eventTime, 'append');
+                }
+                break;
+            }
+            case 'tool_call': {
+                ensureStepStart(currentTurn, currentStep, eventTime);
+                const callId = turnEvent.id;
+                const toolName = turnEvent.toolName ?? 'tool';
+                const toolArgsStr = typeof turnEvent.toolArgs === 'string'
+                    ? turnEvent.toolArgs
+                    : JSON.stringify(turnEvent.toolArgs ?? {});
+                emit('tool/call', {
+                    turn: currentTurn,
+                    step: currentStep,
+                    callId,
+                    name: toolName,
+                    arguments: toolArgsStr,
+                }, eventTime);
+                break;
+            }
+            case 'tool_result': {
+                ensureStepStart(currentTurn, currentStep, eventTime);
+                const callId = turnEvent.id;
+                const toolName = turnEvent.toolName ?? 'tool';
+                const resultContent = turnEvent.toolResult ?? '';
+                emit('tool/result', {
+                    turn: currentTurn,
+                    step: currentStep,
+                    message: {
+                        id: `tool-res-${callId}`,
+                        role: 'user',
+                        source: { kind: 'tool', callId, tool: toolName },
+                        content: [
+                            {
+                                type: 'tool-result',
+                                toolCallId: callId,
+                                content: [{ type: 'text', text: resultContent }],
+                                ...(turnEvent.isError ? { isError: true } : {}),
+                            },
+                        ],
+                    },
+                    ...(turnEvent.exitCode !== undefined ? { meta: { exitCode: turnEvent.exitCode } } : {}),
+                }, eventTime, 'append');
+                // Tool execution concludes a step; next action starts a new step
+                closeStep(currentTurn, currentStep, eventTime);
+                currentStep++;
+                break;
+            }
+            case 'assistant': {
+                ensureStepStart(currentTurn, currentStep, eventTime);
+                const text = turnEvent.text ?? '';
+                emit('assistant/message', {
+                    turn: currentTurn,
+                    step: currentStep,
+                    message: {
+                        id: `asst-${turnEvent.id}`,
+                        role: 'assistant',
+                        content: [{ type: 'text', text }],
+                        source: { kind: 'model', provider: providerName, model: modelName },
+                    },
+                    stream: [
+                        {
+                            type: 'chunk',
+                            time: eventTime,
+                            chunk: {
+                                type: 'text-delta',
+                                index: 0,
+                                text,
+                            },
+                        },
+                    ],
+                }, eventTime, 'append');
+                const nextEvent = session.turns[i + 1];
+                if (!nextEvent || nextEvent.kind === 'user') {
+                    closeTurn(currentTurn, eventTime);
+                    currentTurn++;
+                    currentStep = 1;
+                }
+                break;
+            }
+        }
+    }
+    // Final cleanup if the last turn was still open
+    if (turnOpen) {
+        const lastTime = events.length > 0 ? events[events.length - 1].time : defaultTime;
+        closeTurn(currentTurn, lastTime);
+    }
+    return events;
+}

package/dist/src/dsh/client.d.ts

@@ -0,0 +1,2 @@
+export declare const inject: string[];
+export declare function apply(_ctx: any): void;