@1agents/session-reader 0.5.1 → 0.6.2

package/dist/src/skill.d.ts

@@ -1,6 +1,6 @@
 /** The bundled skill's directory name, used as the entry name in every agent. */
 export declare const SKILL_NAME = "1session";
-export type SkillAgent = 'claude' | 'codex' | 'antigravity';
+export type SkillAgent = 'claude' | 'codex' | 'antigravity' | 'grok' | 'dsh';
 export interface AgentTarget {
     agent: SkillAgent;
     /** Where this agent loads user skills from. */
@@ -9,8 +9,8 @@ export interface AgentTarget {
     homeDir: string;
 }
 /**
- * All three agents load `<dir>/<name>/SKILL.md` with the same YAML frontmatter,
- * so one bundled skill can serve all of them unchanged.
+ * Every one of them loads `<dir>/<name>/SKILL.md` with the same YAML
+ * frontmatter, so one bundled skill can serve all of them unchanged.
  */
 export declare function agentTargets(home?: string): AgentTarget[];
 /**

package/dist/src/skill.js

@@ -6,8 +6,8 @@ import { fileURLToPath } from 'node:url';
 /** The bundled skill's directory name, used as the entry name in every agent. */
 export const SKILL_NAME = '1session';
 /**
- * All three agents load `<dir>/<name>/SKILL.md` with the same YAML frontmatter,
- * so one bundled skill can serve all of them unchanged.
+ * Every one of them loads `<dir>/<name>/SKILL.md` with the same YAML
+ * frontmatter, so one bundled skill can serve all of them unchanged.
  */
 export function agentTargets(home = os.homedir()) {
     return [
@@ -27,6 +27,16 @@ export function agentTargets(home = os.homedir()) {
             homeDir: path.join(home, '.gemini', 'antigravity'),
             skillsDir: path.join(home, '.gemini', 'antigravity', 'skills'),
         },
+        {
+            agent: 'grok',
+            homeDir: path.join(home, '.grok'),
+            skillsDir: path.join(home, '.grok', 'skills'),
+        },
+        {
+            agent: 'dsh',
+            homeDir: path.join(home, '.dsh'),
+            skillsDir: path.join(home, '.dsh', 'skills'),
+        },
     ];
 }
 /**

package/dist/src/store/nul.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 写进 SQLite 的 TEXT 列之前调用。
+ *
+ * 绝大多数内容两个字符都不含，直接原样返回——所以常态是零拷贝。
+ */
+export declare function encodeText(value: string): string;
+export declare function encodeText(value: string | null | undefined): string | null;
+/** 从 SQLite 的 TEXT 列读出来之后调用。 */
+export declare function decodeText(value: string): string;
+export declare function decodeText(value: string | null | undefined): string | null;
+/** 测试与诊断用：这段文本经过 SQLite 的 TEXT 列会不会被截断。 */
+export declare function wouldTruncate(value: string): boolean;

package/dist/src/store/nul.js

@@ -0,0 +1,52 @@
+/**
+ * SQLite 的 TEXT 列在第一个 NUL 处截断——不报错，安静地丢掉后面全部内容。
+ *
+ * 实测：一个 antigravity 会话里 `wsl -l -v` 的 UTF-16 输出被当 UTF-8 读，产生
+ * 交错的 NUL；502 字符的 tool_result 存进索引再读出来只剩 342，后面 160 个
+ * 字符凭空消失。round-trip 测试因此长期飘红，而失败信息指向的是内容本身，
+ * 很难看出是存储层干的。
+ *
+ * 改存 BLOB 能保真，但 `text` / `tool_result` 上有 SQL 搜索（`LIKE` 对 BLOB
+ * 不工作），所以改成**写入时转义、读取时还原**。
+ *
+ * 引导符用 U+FFFF：Unicode 明确规定的 noncharacter，不会出现在有效文本里；
+ * 万一真出现也会被双写，所以还原无歧义。
+ *
+ * 两个常量用 `String.fromCharCode` 而不是字面量，免得源文件里真带上这些
+ * 字符——它们在编辑器、diff、终端里都是隐形的。
+ */
+const NUL = String.fromCharCode(0x00);
+const LEAD = String.fromCharCode(0xffff);
+const ESCAPED_NUL = `${LEAD}0`;
+const ESCAPED_LEAD = `${LEAD}${LEAD}`;
+export function encodeText(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (!value.includes(NUL) && !value.includes(LEAD))
+        return value;
+    // 顺序要紧：先把引导符自己双写，再拿它去转义 NUL。反过来会把刚写出的
+    // 转义序列又转义一遍。
+    return value.split(LEAD).join(ESCAPED_LEAD).split(NUL).join(ESCAPED_NUL);
+}
+export function decodeText(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (!value.includes(LEAD))
+        return value;
+    let out = '';
+    for (let i = 0; i < value.length; i++) {
+        if (value[i] !== LEAD) {
+            out += value[i];
+            continue;
+        }
+        const next = value[++i];
+        // 双写还原成引导符本身；LEAD+'0' 还原成 NUL；落单的引导符原样留着，
+        // 宁可多留一个字符，也不要把不认识的序列吞掉。
+        out += next === LEAD ? LEAD : next === '0' ? NUL : LEAD + (next ?? '');
+    }
+    return out;
+}
+/** 测试与诊断用：这段文本经过 SQLite 的 TEXT 列会不会被截断。 */
+export function wouldTruncate(value) {
+    return value.includes(NUL);
+}

package/dist/src/store/read.js

@@ -1,3 +1,4 @@
+import { decodeText } from './nul.js';
 import { turnStartsFrom } from '../turns.js';
 import { emptyProviderStats, } from '../types.js';
 export function sessionRow(db, id) {
@@ -70,7 +71,7 @@ export function refOf(row) {
         id: row.native_id,
         provider: row.provider,
         path: row.source_path,
-        ...(row.title === null ? {} : { title: row.title }),
+        ...(row.title === null ? {} : { title: decodeText(row.title) }),
         ...(row.workspace === null ? {} : { workspace: row.workspace }),
         ...(row.started_at === null ? {} : { createdAt: row.started_at }),
         ...(row.ended_at === null ? {} : { updatedAt: row.ended_at }),
@@ -89,12 +90,12 @@ function eventsOf(db, id, nativeId) {
         id: `${nativeId}#${row.idx}`,
         index: row.idx,
         kind: row.kind,
-        ...(row.text === null ? {} : { text: row.text }),
+        ...(row.text === null ? {} : { text: decodeText(row.text) }),
         ...(row.tool_name === null ? {} : { toolName: row.tool_name }),
         ...(row.tool_args_json === null
             ? {}
             : { toolArgs: JSON.parse(row.tool_args_json) }),
-        ...(row.tool_result === null ? {} : { toolResult: row.tool_result }),
+        ...(row.tool_result === null ? {} : { toolResult: decodeText(row.tool_result) }),
         ...(row.is_error === null ? {} : { isError: row.is_error === 1 }),
         ...(row.ts === null ? {} : { timestamp: row.ts }),
         ...(row.source_index === null ? {} : { sourceIndex: row.source_index }),

package/dist/src/store/schema.d.ts

@@ -7,11 +7,11 @@
  * the behaviour — never derive them from a git hash, `dist` ships without git.
  */
 /** DDL layout. A bump drops and rebuilds the whole database. */
-export declare const SCHEMA_VERSION = 1;
+export declare const SCHEMA_VERSION = 2;
 /** L1 semantics — anything in `parsers/` that changes normalized events. */
-export declare const PARSER_VERSION = 2;
+export declare const PARSER_VERSION = 3;
 /** L2 rules — `writes.ts` / `ledger.ts`. Re-derives facts from stored events. */
-export declare const EXTRACTOR_VERSION = 1;
+export declare const EXTRACTOR_VERSION = 2;
 /** L3 rules — `store/edges.ts`. Re-derives edges from stored events. */
 export declare const EDGE_VERSION = 1;
 export declare const DDL = "\nCREATE TABLE IF NOT EXISTS meta (\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS sessions (\n  id                TEXT PRIMARY KEY,          -- canonical \"provider:native_id\"\n  provider          TEXT NOT NULL,\n  native_id         TEXT NOT NULL,\n  source_path       TEXT NOT NULL,\n  workspace         TEXT,\n  title             TEXT,\n  started_at        TEXT,\n  ended_at          TEXT,\n  event_count       INTEGER NOT NULL DEFAULT 0,\n  turn_count        INTEGER NOT NULL DEFAULT 0,\n  source_size       INTEGER NOT NULL DEFAULT 0,\n  source_mtime_ms   INTEGER NOT NULL DEFAULT 0,\n  head_hash         TEXT,\n  aux_fingerprint   TEXT,\n  indexed_bytes     INTEGER NOT NULL DEFAULT 0, -- reserved for resumable parse\n  parser_version    INTEGER NOT NULL DEFAULT 0,\n  extractor_version INTEGER NOT NULL DEFAULT 0,\n  edge_version      INTEGER NOT NULL DEFAULT 0,\n  indexed_at        TEXT,\n  artifacts_json    TEXT,\n  stats_json        TEXT\n);\n\nCREATE TABLE IF NOT EXISTS events (\n  session_id     TEXT NOT NULL,\n  idx            INTEGER NOT NULL,\n  kind           TEXT NOT NULL,\n  text           TEXT,\n  tool_name      TEXT,\n  tool_args_json TEXT,\n  tool_result    TEXT,\n  is_error       INTEGER,\n  ts             TEXT,\n  source_index   INTEGER,\n  exit_code      INTEGER,\n  pid            TEXT,\n  duration_ms    INTEGER,\n  provider_truncated INTEGER,                 -- the provider's own \"shortened copy\" flag\n  PRIMARY KEY (session_id, idx)\n) WITHOUT ROWID;\n\nCREATE TABLE IF NOT EXISTS file_ops (\n  session_id  TEXT NOT NULL,\n  path        TEXT NOT NULL,\n  host        TEXT,\n  operation   TEXT NOT NULL,\n  turn        INTEGER NOT NULL,\n  event_index INTEGER NOT NULL,\n  ts          TEXT,\n  provenance  TEXT NOT NULL,\n  extractor   TEXT NOT NULL,\n  file_group  TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS commands (\n  session_id  TEXT NOT NULL,\n  event_index INTEGER NOT NULL,\n  turn        INTEGER NOT NULL,\n  command     TEXT NOT NULL,\n  host        TEXT,\n  cwd         TEXT,\n  exit_code   INTEGER,\n  duration_ms INTEGER,\n  pid         TEXT,\n  stderr      TEXT,\n  ts          TEXT,\n  provenance  TEXT NOT NULL,\n  extractor   TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS jobs (\n  session_id     TEXT NOT NULL,\n  job_id         TEXT NOT NULL,\n  command        TEXT,\n  pid            TEXT,\n  host           TEXT,\n  log            TEXT,\n  started_at     TEXT,\n  discovered_from INTEGER,\n  status         TEXT NOT NULL,\n  provenance     TEXT NOT NULL,\n  extractor      TEXT NOT NULL,\n  evidence_json  TEXT\n);\n\nCREATE TABLE IF NOT EXISTS session_edges (\n  id             INTEGER PRIMARY KEY AUTOINCREMENT,\n  from_session   TEXT NOT NULL,\n  to_session     TEXT NOT NULL,\n  relation       TEXT NOT NULL,\n  first_seen_at  TEXT,\n  last_seen_at   TEXT,\n  evidence_count INTEGER NOT NULL DEFAULT 0,\n  UNIQUE (from_session, to_session, relation)\n);\n\nCREATE TABLE IF NOT EXISTS edge_evidence (\n  edge_id       INTEGER NOT NULL,\n  source_session TEXT NOT NULL,\n  event_index   INTEGER NOT NULL,\n  operation     TEXT NOT NULL,\n  command       TEXT,\n  ts            TEXT,\n  provenance    TEXT NOT NULL,\n  extractor     TEXT NOT NULL,\n  UNIQUE (edge_id, source_session, event_index)\n);\n\nCREATE INDEX IF NOT EXISTS idx_events_kind      ON events (session_id, kind);\nCREATE INDEX IF NOT EXISTS idx_fileops_path     ON file_ops (path);\nCREATE INDEX IF NOT EXISTS idx_fileops_session  ON file_ops (session_id);\nCREATE INDEX IF NOT EXISTS idx_commands_session ON commands (session_id, exit_code);\nCREATE INDEX IF NOT EXISTS idx_jobs_session     ON jobs (session_id);\nCREATE INDEX IF NOT EXISTS idx_sessions_ws      ON sessions (workspace, ended_at);\nCREATE INDEX IF NOT EXISTS idx_sessions_native  ON sessions (native_id);\nCREATE INDEX IF NOT EXISTS idx_edges_to         ON session_edges (to_session);\n";

package/dist/src/store/schema.js

@@ -7,11 +7,11 @@
  * the behaviour — never derive them from a git hash, `dist` ships without git.
  */
 /** DDL layout. A bump drops and rebuilds the whole database. */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 /** L1 semantics — anything in `parsers/` that changes normalized events. */
-export const PARSER_VERSION = 2;
+export const PARSER_VERSION = 3;
 /** L2 rules — `writes.ts` / `ledger.ts`. Re-derives facts from stored events. */
-export const EXTRACTOR_VERSION = 1;
+export const EXTRACTOR_VERSION = 2;
 /** L3 rules — `store/edges.ts`. Re-derives edges from stored events. */
 export const EDGE_VERSION = 1;
 export const DDL = `

package/dist/src/store/write.js

@@ -1,3 +1,4 @@
+import { encodeText } from './nul.js';
 import fs from 'node:fs';
 import crypto from 'node:crypto';
 import { PARSER_VERSION } from './schema.js';
@@ -51,7 +52,7 @@ export function writeSession(db, session, fingerprint, turnCount) {
          id, provider, native_id, source_path, workspace, title, started_at, ended_at,
          event_count, turn_count, source_size, source_mtime_ms, head_hash, aux_fingerprint,
          parser_version, extractor_version, edge_version, indexed_at, artifacts_json, stats_json
-       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 0, ?, ?, ?)`).run(id, session.ref.provider, session.ref.id, session.ref.path, session.ref.workspace ?? null, session.ref.title ?? null, session.ref.createdAt ?? null, session.ref.updatedAt ?? null, session.turns.length, turnCount, fingerprint.sourceSize, fingerprint.sourceMtimeMs, fingerprint.headHash, fingerprint.auxFingerprint ?? null, PARSER_VERSION, new Date().toISOString(), JSON.stringify(session.artifacts), JSON.stringify(session.stats));
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 0, ?, ?, ?)`).run(id, session.ref.provider, session.ref.id, session.ref.path, session.ref.workspace ?? null, encodeText(session.ref.title), session.ref.createdAt ?? null, session.ref.updatedAt ?? null, session.turns.length, turnCount, fingerprint.sourceSize, fingerprint.sourceMtimeMs, fingerprint.headHash, fingerprint.auxFingerprint ?? null, PARSER_VERSION, new Date().toISOString(), JSON.stringify(session.artifacts), JSON.stringify(session.stats));
         const insert = db.prepare(`INSERT INTO events (
          session_id, idx, kind, text, tool_name, tool_args_json, tool_result, is_error,
          ts, source_index, exit_code, pid, duration_ms, provider_truncated
@@ -60,7 +61,7 @@ export function writeSession(db, session, fingerprint, turnCount) {
         // 0.08% and silently dropped search hits from long build logs — exactly
         // the kind of "looks complete, isn't" answer this store exists to remove.
         for (const event of session.turns) {
-            insert.run(id, event.index, event.kind, event.text ?? null, event.toolName ?? null, event.toolArgs ? JSON.stringify(event.toolArgs) : null, event.toolResult ?? null, event.isError === undefined ? null : event.isError ? 1 : 0, event.timestamp ?? null, event.sourceIndex ?? null, event.exitCode ?? null, event.processId ?? null, event.durationMs ?? null, event.truncated === undefined ? null : event.truncated ? 1 : 0);
+            insert.run(id, event.index, event.kind, encodeText(event.text), event.toolName ?? null, event.toolArgs ? JSON.stringify(event.toolArgs) : null, encodeText(event.toolResult), event.isError === undefined ? null : event.isError ? 1 : 0, event.timestamp ?? null, event.sourceIndex ?? null, event.exitCode ?? null, event.processId ?? null, event.durationMs ?? null, event.truncated === undefined ? null : event.truncated ? 1 : 0);
         }
         db.exec('COMMIT');
     }

package/dist/src/types.d.ts

@@ -1,5 +1,5 @@
 /** Canonical domain types shared by every provider parser. */
-export type AgentProvider = 'antigravity' | 'claude' | 'codex' | 'cursor' | 'unknown';
+export type AgentProvider = 'antigravity' | 'claude' | 'codex' | 'dsh' | 'grok' | 'cursor' | 'unknown';
 /** Cheap metadata about a discovered session, obtained without a full parse. */
 export interface SessionRef {
     id: string;

package/dist/src/util/text.js

@@ -43,6 +43,9 @@ export function looksLikeInstructions(text) {
         /<user_instructions>/.test(head) ||
         /<environment_context>/.test(head) ||
         /^<permissions instructions>/.test(head) ||
+        // Grok opens every session with an ambient `<user_info>/<git_status>/<rules>`
+        // block; the real prompt arrives as its own message right after it.
+        /^<user_info>/.test(head) ||
         /^<recommended_plugins>/.test(head) ||
         /^Caveat: The messages below were generated/.test(head));
 }

package/dist/src/util/zstd.d.ts

@@ -0,0 +1,14 @@
+/** Every complete frame in the buffer, in order. */
+export declare function frameRanges(buf: Buffer): [number, number][];
+/** Concatenated payload of every frame that decompresses. */
+export declare function decodeZstd(buf: Buffer): string;
+export interface ZstdJsonlOptions {
+    /**
+     * Read only this many bytes from the head of the file. Frames are
+     * self-delimiting, so a prefix decodes to a prefix of the session — which is
+     * all `scanRef` ever needs.
+     */
+    headBytes?: number;
+}
+/** Streams a zstd-framed `.jsonl`, silently skipping malformed lines. */
+export declare function readZstdJsonl(file: string, options?: ZstdJsonlOptions): AsyncGenerator<Record<string, unknown>>;

package/dist/src/util/zstd.js

@@ -0,0 +1,129 @@
+import fs from 'node:fs/promises';
+import zlib from 'node:zlib';
+/**
+ * Reading zstd-framed JSONL.
+ *
+ * Agents that compress their transcripts append one frame per flush, so a
+ * session file is a *concatenation* of complete frames. Node's zstd APIs —
+ * both the sync call and the stream — stop after the first one, which silently
+ * yields a session with a single line. The walker below therefore finds every
+ * frame boundary from the frame headers alone (no decompression), so the whole
+ * file is read and a truncated tail frame is dropped instead of poisoning it.
+ */
+/** zstd reached `node:zlib` in Node 22.15 / 23.8; `engines` asks for at least that. */
+const SUPPORTED = typeof zlib.zstdDecompressSync === 'function';
+const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+const FRAME_MAGIC = 0xfd2fb528;
+const SKIPPABLE_LOW = 0x184d2a50;
+const SKIPPABLE_HIGH = 0x184d2a5f;
+const DICTIONARY_ID_BYTES = [0, 1, 2, 4];
+const CONTENT_SIZE_BYTES = [0, 2, 4, 8];
+/**
+ * Offset just past the frame starting at `at`, or nothing when the bytes run
+ * out or the header is not one we understand. RFC 8878 §3.1: a frame is a
+ * header followed by blocks, each block announcing its own size, so the end
+ * can be found without inflating anything.
+ */
+function frameEnd(buf, at) {
+    let i = at + 4;
+    if (i >= buf.length)
+        return undefined;
+    const descriptor = buf[i++];
+    const contentSizeFlag = descriptor >> 6;
+    const singleSegment = (descriptor >> 5) & 1;
+    const hasChecksum = (descriptor >> 2) & 1;
+    i += singleSegment ? 0 : 1; // Window_Descriptor
+    i += DICTIONARY_ID_BYTES[descriptor & 3];
+    // The one asymmetric case: flag 0 means "1 byte" for a single-segment frame
+    // and "absent" otherwise.
+    i += contentSizeFlag === 0 ? singleSegment : CONTENT_SIZE_BYTES[contentSizeFlag];
+    for (;;) {
+        if (i + 3 > buf.length)
+            return undefined;
+        const header = buf[i] | (buf[i + 1] << 8) | (buf[i + 2] << 16);
+        i += 3;
+        const blockType = (header >> 1) & 3;
+        if (blockType === 3)
+            return undefined; // reserved — we are off the rails
+        i += blockType === 1 ? 1 : header >>> 3; // RLE stores a single byte
+        if (i > buf.length)
+            return undefined;
+        if (header & 1)
+            break; // Last_Block
+    }
+    return i + (hasChecksum ? 4 : 0) <= buf.length ? i + (hasChecksum ? 4 : 0) : undefined;
+}
+/** Every complete frame in the buffer, in order. */
+export function frameRanges(buf) {
+    const ranges = [];
+    let at = 0;
+    while (at + 4 <= buf.length) {
+        const magic = buf.readUInt32LE(at);
+        if (magic >= SKIPPABLE_LOW && magic <= SKIPPABLE_HIGH) {
+            if (at + 8 > buf.length)
+                break;
+            at += 8 + buf.readUInt32LE(at + 4);
+            continue;
+        }
+        const end = magic === FRAME_MAGIC ? frameEnd(buf, at) : undefined;
+        if (end === undefined) {
+            // Either not a frame start or a truncated one; resynchronize on the next
+            // magic rather than giving up on the rest of the file.
+            const next = buf.indexOf(MAGIC, at + 1);
+            if (next < 0)
+                break;
+            at = next;
+            continue;
+        }
+        ranges.push([at, end]);
+        at = end;
+    }
+    return ranges;
+}
+/** Concatenated payload of every frame that decompresses. */
+export function decodeZstd(buf) {
+    // Saying so is the point: a silent empty session would read as "that agent
+    // has no history", which is exactly the wrong thing to believe.
+    if (!SUPPORTED) {
+        throw new Error(`reading zstd-compressed sessions needs node:zlib zstd support (Node >= 22.15); this is ${process.version}`);
+    }
+    const parts = [];
+    for (const [start, end] of frameRanges(buf)) {
+        try {
+            parts.push(zlib.zstdDecompressSync(buf.subarray(start, end)));
+        }
+        catch {
+            /* a frame written mid-flush is not worth failing the whole session for */
+        }
+    }
+    return Buffer.concat(parts).toString('utf8');
+}
+/** Streams a zstd-framed `.jsonl`, silently skipping malformed lines. */
+export async function* readZstdJsonl(file, options = {}) {
+    const handle = await fs.open(file, 'r');
+    let buf;
+    try {
+        const size = (await handle.stat()).size;
+        const length = Math.min(options.headBytes ?? size, size);
+        buf = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buf, 0, length, 0);
+        buf = buf.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+    for (const line of decodeZstd(buf).split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed && typeof parsed === 'object')
+            yield parsed;
+    }
+}

package/dist/src/writes.js

@@ -11,9 +11,26 @@ const EDIT_TOOLS = new Set([
     'create_file',
     'apply_patch',
     'str_replace_editor',
+    'search_replace',
+]);
+const FILE_ARGS = [
+    'file_path',
+    'filePath',
+    'notebook_path',
+    'target_file',
+    'TargetFile',
+    'AbsolutePath',
+    'path',
+];
+const SHELL_TOOLS = new Set([
+    'bash',
+    'run_command',
+    'run_terminal_command',
+    'shell',
+    'exec',
+    'local_shell',
+    'execute_command',
 ]);
-const FILE_ARGS = ['file_path', 'filePath', 'notebook_path', 'TargetFile', 'AbsolutePath', 'path'];
-const SHELL_TOOLS = new Set(['bash', 'run_command', 'shell', 'exec', 'local_shell', 'execute_command']);
 const COMMAND_ARGS = ['command', 'CommandLine', 'cmd', 'input'];
 const PATCH_FILE = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm;
 /** Extensions we accept on a bare token. Without this, `a.name` looks like a file. */

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@1agents/session-reader",
-  "version": "0.5.1",
+  "version": "0.6.2",
   "description": "Read Plane: cross-agent session discovery, turn inspection, workspace aggregation and distillation from raw local session files.",
   "keywords": [
     "claude-code",
     "codex",
     "antigravity",
+    "grok",
+    "deepseek",
     "session",
     "transcript",
     "jsonl",
@@ -49,7 +51,7 @@
     "1session": "tsx bin/1session.ts"
   },
   "engines": {
-    "node": ">=22.5"
+    "node": ">=22.15"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
@@ -58,6 +60,6 @@
   },
   "dependencies": {
     "@1agents/dreammate-network": "^0.3.0",
-    "@1agents/dreammate-node": "^0.2.0"
+    "@1agents/dreammate-node": "^0.4.0"
   }
 }

package/skills/1session/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: 1session
-description: Search and read the user's past AI coding sessions across Claude Code, Codex and Antigravity from their raw local session files, using the `1session` CLI. Use this whenever the user refers to work they did in an earlier session rather than in this conversation — "上次/之前/昨天我们改了什么", "那个报错后来怎么解决的", "我在哪个会话里提过 X", "这个功能是哪一轮加的", "codex 那边做到哪了", "跨项目找一下", "整理一下最近几天的会话/写个周报". Also reach for it proactively, before asking the user to re-explain context they have obviously already established with some agent on this machine — the answer is usually already on disk. Read-only: it never modifies or resumes a session.
+description: Search and read the user's past AI coding sessions across Claude Code, Codex, Antigravity, Grok and DeepSeek Harness (dsh) from their raw local session files, using the `1session` CLI. Use this whenever the user refers to work they did in an earlier session rather than in this conversation — "上次/之前/昨天我们改了什么", "那个报错后来怎么解决的", "我在哪个会话里提过 X", "这个功能是哪一轮加的", "codex 那边做到哪了", "grok/dsh 那边呢", "跨项目找一下", "整理一下最近几天的会话/写个周报". Also reach for it proactively, before asking the user to re-explain context they have obviously already established with some agent on this machine — the answer is usually already on disk. Read-only: it never modifies or resumes a session. This skill also covers getting itself running and spreading to other agents: when the `1session` CLI is missing it falls back to `npx` on the spot, and it knows how to install the package globally and push the skill into all five agents at once — so use it too when the user asks to install, upgrade, uninstall, share or distribute 1session / session-reader, or reports that the `1session` command is not found.
 ---
 
 # 1session — the cross-agent Read Plane
 
-Three agents write sessions to this machine in three different formats. `1session`
+Five agents write sessions to this machine in five different formats. `1session`
 normalizes all of them and answers questions about what actually happened.
 
 | Provider | On disk | Covered |
@@ -13,19 +13,58 @@ normalizes all of them and answers questions about what actually happened.
 | `claude` | `~/.claude/projects/<slug>/<id>.jsonl` | prompts, tools, commands, files, tokens, git branch |
 | `codex` | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | same, plus structured `exit_code` / `stderr` / `pid` |
 | `antigravity` | `~/.gemini/antigravity/brain/<uuid>/.../transcript.jsonl` | same, plus plan/walkthrough artifacts |
+| `grok` | `~/.grok/sessions/<encoded cwd>/<uuid>/chat_history.jsonl` | same, plus tool durations/outcomes, background-task receipts, goal plans |
+| `dsh` | `~/.dsh/sessions/<slug>/session-<uuid>/session.v2.jsonl.zstd` | same, plus native turn/step boundaries and per-message usage |
 
 Everything is derived from the raw files at read time. Nothing is written back to
 them, no daemon is involved, and no session is ever resumed or modified.
 
-## Before the first call
+## Bootstrap: get the CLI, then answer the question
 
-Run `1session help`. If the command is missing, fall back to
-`npx -y @1agents/session-reader` in place of `1session` everywhere below, and
-mention the one-time fix once: `npm i -g @1agents/session-reader`.
+This skill travels on its own. Someone may have dropped `SKILL.md` into an agent
+on a machine where the `1session` CLI does not exist, so the first call is a
+probe rather than an assumption:
 
-The first run on a machine parses every session (~10s for a few hundred); after
-that an index makes each call sub-second. If a call feels slow, it is that first
-build, not a hang.
+```bash
+1session help
+```
+
+If that fails, **do not stop to install before answering.** `npx` runs the same
+CLI with nothing installed:
+
+```bash
+npx -y @1agents/session-reader@latest list --global --limit 10
+```
+
+Substitute `npx -y @1agents/session-reader@latest` for `1session` everywhere
+below, answer the question the user actually asked, and offer the permanent
+install once, afterwards. Someone asking where last week's bug got fixed wants
+the bug, not a setup errand.
+
+The permanent install, when they want it:
+
+```bash
+npm i -g @1agents/session-reader   # requires Node >= 22.15
+1session skill install             # put this skill into every agent on the machine
+```
+
+Node below 22.15 is a hard stop rather than a warning — the reader needs
+`node:sqlite` for the index and `node:zlib`'s zstd to read dsh's compressed
+sessions, and `npx` does not rescue an old runtime either. Check `node -v`, say
+plainly that Node needs upgrading, and don't improvise around it.
+
+That second command is what makes this spread: one run installs the skill into
+Claude Code, Codex, Antigravity, Grok and dsh at once, so whichever agent the
+user opens next already knows their history is readable. Run it after a global
+install, **not** through `npx` — npx installs the package into a cache directory
+that npm later garbage-collects, and the skill links would dangle with it.
+
+`references/install.md` has the rest: PATH and permission failures, link vs copy,
+upgrading, uninstalling, and what to hand someone who wants this on their own
+machine. Read it when an install misbehaves or the user asks how to share this.
+
+The first real run parses every session (~10s for a few hundred); an index makes
+each call after that sub-second. A slow first call is that build, not a hang.
 
 ## Pick the command from the question
 

package/skills/1session/evals/evals.json

@@ -42,6 +42,48 @@
         "Gives a drill-down handle — a turn/event number or an exact command the user can run to see the evidence",
         "Reports how it was verified (tests green / the commit) rather than only describing the change"
       ]
+    },
+    {
+      "id": 3,
+      "name": "missing-cli-still-answers",
+      "prompt": "上周我在这台机器上调一个超时的问题，后来是怎么解决的？（顺便说一句，我这台机器上好像没装过什么 1session，`1session` 这个命令敲下去是 command not found）",
+      "expected_output": "Recognizes the CLI is absent, immediately falls back to `npx -y @1agents/session-reader@latest ...` to actually answer the timeout question, and only then mentions the permanent install as a one-time follow-up — rather than stopping to install first or declaring it cannot help.",
+      "files": [],
+      "assertions": [
+        "Falls back to npx (`npx -y @1agents/session-reader@latest ...`) instead of stopping at the missing command",
+        "Actually attempts to answer the user's timeout question rather than turning the turn into a setup errand",
+        "Mentions the permanent install (`npm i -g @1agents/session-reader`) as an optional follow-up, not as a precondition",
+        "Does not run a global npm install without the user agreeing to it first",
+        "Does not claim the question is unanswerable because the CLI is missing"
+      ]
+    },
+    {
+      "id": 4,
+      "name": "distribute-to-a-colleague",
+      "prompt": "同事看我能翻出以前会话的记录，也想在他 mac 上用。我要发给他什么？他那边只装了 claude code 和 codex，另外他 node 好像还是 20。",
+      "expected_output": "Gives the two-line install (npm i -g, then `1session skill install`), explains that the second line is what puts the skill into Claude Code and Codex, and flags that Node 20 is below the 22.15 floor so he must upgrade Node first — npx will not work around it either.",
+      "files": [],
+      "assertions": [
+        "Gives `npm i -g @1agents/session-reader` as the install command",
+        "Includes `1session skill install` and explains it is what puts the skill into the colleague's agents, not just the CLI",
+        "Flags Node 20 as below the >= 22.15 requirement and says it must be upgraded",
+        "Does not suggest npx as a way around the old Node version (it runs on the same runtime and fails identically)",
+        "Does not invent an install path that does not exist (no curl|sh script, no brew formula, no manual git clone as the primary route)"
+      ]
+    },
+    {
+      "id": 5,
+      "name": "npx-skill-install-trap",
+      "prompt": "我不想全局装东西，能不能直接用 npx 把这个 skill 装到我的 claude 和 codex 里就好？",
+      "expected_output": "Warns that `skill install` in its default link mode would point at the npx cache directory, which npm garbage-collects — the skill would silently vanish later. Offers `--copy` as the npx-compatible route, or a global install as the robust one.",
+      "files": [],
+      "assertions": [
+        "Warns that a link-mode install via npx points into the npx cache (~/.npm/_npx/...) which npm later prunes",
+        "Names the consequence concretely: the skill silently disappears from the agents afterwards",
+        "Offers `--copy` as the way to make an npx-based install survive, and/or a global install as the robust alternative",
+        "Mentions `--agent claude,codex` or otherwise respects that the user only wants those two",
+        "Does not simply tell the user to run `npx ... skill install` with no caveat"
+      ]
     }
   ]
-}
+}

package/skills/1session/references/cli.md

@@ -26,7 +26,7 @@ session file (size + mtime + head hash) and reparses only changed bytes, so
 
 ```
 1session list [--limit n] [--scope <path>|cwd|global] [--global]
-              [--provider claude|codex|antigravity] [--since 24h] [--json]
+              [--provider claude|codex|antigravity|grok|dsh] [--since 24h] [--json]
 ```
 
 Most recently updated sessions first. Columns: provider, 8-char id, updated-at,