@1agents/session-reader 0.5.1 → 0.6.1

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/schema.d.ts

@@ -9,9 +9,9 @@
 /** DDL layout. A bump drops and rebuilds the whole database. */
 export declare const SCHEMA_VERSION = 1;
 /** 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

@@ -9,9 +9,9 @@
 /** DDL layout. A bump drops and rebuilds the whole database. */
 export const SCHEMA_VERSION = 1;
 /** 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/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.1",
   "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.3.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.
 ---
 
 # 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,6 +13,8 @@ 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.

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,