@1agents/session-reader 0.1.1

package/dist/src/util/paths.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function expandHome(p) {
+    if (p === '~')
+        return os.homedir();
+    if (p.startsWith('~/'))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+/**
+ * Normalizes anything a session file may contain into one comparable absolute
+ * path: `~`, relative paths, `file://` URIs, percent-encoding and symlinks.
+ */
+export function canonicalizePath(input) {
+    let p = (input ?? '').trim();
+    if (!p)
+        return '';
+    if (p.startsWith('file://')) {
+        try {
+            p = fileURLToPath(p);
+        }
+        catch {
+            p = decodeURIComponent(p.slice('file://'.length));
+        }
+    }
+    else if (/%[0-9A-Fa-f]{2}/.test(p)) {
+        try {
+            p = decodeURIComponent(p);
+        }
+        catch {
+            /* keep as-is */
+        }
+    }
+    p = path.resolve(expandHome(p));
+    try {
+        p = fs.realpathSync.native(p);
+    }
+    catch {
+        /* path may not exist any more; the lexical form is still comparable */
+    }
+    return p.length > 1 ? p.replace(/\/+$/, '') : p;
+}
+/** True when `child` is `parent` itself or lives under it. */
+export function isInside(parent, child) {
+    if (!parent || !child)
+        return false;
+    if (parent === child)
+        return true;
+    return child.startsWith(parent.endsWith('/') ? parent : `${parent}/`);
+}
+/**
+ * Claude Code names its project directories by replacing every non-alphanumeric
+ * character of the cwd with `-` (lossy, so we only ever slugify forwards).
+ */
+export function slugifyWorkspace(p) {
+    return p.replace(/[^a-zA-Z0-9]/g, '-');
+}
+/** Walks up from a file to the closest directory holding `.git`. */
+export function findRepoRoot(from) {
+    let dir = path.dirname(canonicalizePath(from));
+    for (let i = 0; i < 40 && dir && dir !== '/'; i++) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return dir;
+        dir = path.dirname(dir);
+    }
+    return undefined;
+}

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

@@ -0,0 +1,7 @@
+/** Collapses whitespace and clips to `max` characters. */
+export declare function oneLine(text: string | undefined, max?: number): string;
+export declare function clip(text: string | undefined, max: number): string;
+/** Strips the wrapper tags and ambient blocks agents inject around a real request. */
+export declare function stripPromptEnvelope(text: string): string;
+/** Boilerplate the agents prepend to the first turn — never a real request. */
+export declare function looksLikeInstructions(text: string): boolean;

package/dist/src/util/text.js

@@ -0,0 +1,48 @@
+/** Collapses whitespace and clips to `max` characters. */
+export function oneLine(text, max = 160) {
+    const flat = (text ?? '').replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+export function clip(text, max) {
+    const value = (text ?? '').trim();
+    return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}
+/** Strips the wrapper tags and ambient blocks agents inject around a real request. */
+export function stripPromptEnvelope(text) {
+    let out = text;
+    const request = out.match(/<USER_REQUEST>([\s\S]*?)<\/USER_REQUEST>/);
+    if (request?.[1])
+        out = request[1];
+    // Codex answers to its own clarifying questions carry the reply in `answer`.
+    if (out.includes('<send_user_message_question_reply>')) {
+        const answers = [...out.matchAll(/"answer"\s*:\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => (m[1] ?? '').replace(/\\"/g, '"').replace(/\\n/g, ' '));
+        if (answers.length)
+            return answers.join('\n').trim();
+    }
+    out = out
+        .replace(/<in-app-browser-context[\s\S]*?<\/in-app-browser-context>/g, '')
+        .replace(/<image\s[^>]*>[\s\S]*?<\/image>/g, '');
+    // Attachment/ambient preambles keep the actual prompt behind a `## My request:` heading.
+    const marker = out.lastIndexOf('## My request:');
+    if (marker !== -1)
+        out = out.slice(marker + '## My request:'.length);
+    out = out
+        .replace(/<ADDITIONAL_METADATA>[\s\S]*?<\/ADDITIONAL_METADATA>/g, '')
+        .replace(/<USER_SETTINGS_CHANGE>[\s\S]*?<\/USER_SETTINGS_CHANGE>/g, '')
+        .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '')
+        .replace(/<environment_context>[\s\S]*?<\/environment_context>/g, '')
+        .replace(/<user_instructions>[\s\S]*?<\/user_instructions>/g, '')
+        .replace(/<INSTRUCTIONS>[\s\S]*?<\/INSTRUCTIONS>/g, '');
+    return out.trim();
+}
+/** Boilerplate the agents prepend to the first turn — never a real request. */
+export function looksLikeInstructions(text) {
+    const head = text.slice(0, 400);
+    return (/^#\s*AGENTS\.md/i.test(head) ||
+        /<INSTRUCTIONS>/.test(head) ||
+        /<user_instructions>/.test(head) ||
+        /<environment_context>/.test(head) ||
+        /^<permissions instructions>/.test(head) ||
+        /^<recommended_plugins>/.test(head) ||
+        /^Caveat: The messages below were generated/.test(head));
+}

package/dist/src/writes.d.ts

@@ -0,0 +1,35 @@
+import type { Provenance, TurnEvent } from './types.js';
+export interface FileWrite {
+    path: string;
+    /** `observed` from a dedicated edit tool, `derived` from a shell command. */
+    provenance: Provenance;
+    /** The rule that produced it: `tool:Write`, `shell:redirect`, … */
+    extractor: string;
+    /** Set when the write happened inside `ssh user@host '…'`. */
+    host?: string;
+    event?: number;
+}
+/**
+ * Drops here-document bodies before scanning. Their content is data being
+ * written, not commands — and when the payload is source code, its arrow
+ * functions and string literals otherwise masquerade as redirects and hosts.
+ */
+export declare function stripHeredocs(command: string): string;
+/** The untruncated shell command a tool call carries, if it is a shell tool. */
+export declare function rawCommand(turn: TurnEvent): string | undefined;
+/**
+ * The command as it should be analysed: here-doc payloads removed, so that
+ * data being written never gets mistaken for commands being run.
+ */
+export declare function analyzableCommand(turn: TurnEvent): string | undefined;
+/**
+ * Files a single tool call wrote. Explicit writes come from dedicated edit
+ * tools; inferred ones are parsed out of shell commands (heuristic — agents
+ * that write through the shell would otherwise leave no trace at all).
+ */
+export declare function fileWrites(turn: TurnEvent): FileWrite[];
+/**
+ * Stable identity for a write: `host:path` when remote, otherwise an absolute
+ * local path (relative ones resolved against the session's workspace).
+ */
+export declare function resolveWritePath(write: FileWrite, workspace?: string): string;

package/dist/src/writes.js

@@ -0,0 +1,204 @@
+import path from 'node:path';
+import { canonicalizePath } from './util/paths.js';
+const EDIT_TOOLS = new Set([
+    'write',
+    'edit',
+    'multiedit',
+    'notebookedit',
+    'write_to_file',
+    'replace_file_content',
+    'edit_file',
+    'create_file',
+    'apply_patch',
+    'str_replace_editor',
+]);
+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. */
+const KNOWN_EXT = /\.(?:ts|tsx|js|jsx|mjs|cjs|json|jsonl|md|markdown|txt|csv|tsv|ya?ml|toml|ini|conf|cfg|sh|bash|zsh|fish|py|rb|go|rs|java|c|h|cpp|hpp|sql|html|css|scss|sql|log|png|jpe?g|gif|webp|svg|pdf|zip|tar|gz|safetensors|pt|pth|bin|lock|env|gitignore|dockerfile|patch|diff)$/i;
+/**
+ * Drops here-document bodies before scanning. Their content is data being
+ * written, not commands — and when the payload is source code, its arrow
+ * functions and string literals otherwise masquerade as redirects and hosts.
+ */
+export function stripHeredocs(command) {
+    return command.replace(/<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[\s\S]*?^\s*\2\s*$/gm, (match) => match.slice(0, match.indexOf('\n') + 1));
+}
+/** `user@host` in an ssh/scp invocation — the bare `-o opt` forms carry no host. */
+const SSH_HOST = /\b(?:ssh|scp|rsync)\b[^\n;|]*?\b[\w.-]+@([\w.-]+)/;
+/** Shell constructs that create or overwrite a file, in order of specificity. */
+const SHELL_PATTERNS = [
+    { via: 'tee', re: /\btee\s+(?:-a\s+)?(?:'([^']+)'|"([^"]+)"|([^\s'";|&)]+))/g },
+    { via: 'sed-i', re: /\bsed\b[^\n;|]*?\s-i(?:\.\w+)?\s[^\n;|]*?\s(?:'([^']+)'|"([^"]+)"|([^\s'";|&)]+))\s*(?=$|[;|&\n'"])/g },
+    { via: 'write-text', re: /(?:'([^']+)'|"([^"]+)")\s*\)?\s*\.write_text\(/g },
+    { via: 'open-w', re: /\bopen\(\s*(?:'([^']+)'|"([^"]+)")\s*,\s*['"][wa]/g },
+    // `=>` and `>=` are code, not redirection.
+    { via: 'redirect', re: /(?<![0-9&=<>])>>?\s*(?:'([^']+)'|"([^"]+)"|([^\s'";|&<>)]+))/g },
+];
+function firstGroup(match) {
+    return match[1] ?? match[2] ?? match[3];
+}
+/** Resolves only what is already absolute; relative paths stay verbatim. */
+function absolutize(candidate) {
+    const value = candidate.trim();
+    return path.isAbsolute(value) || value.startsWith('~') || value.startsWith('file://')
+        ? canonicalizePath(value)
+        : value;
+}
+/** Rejects device files, globs, flags, URLs and file descriptors. */
+function looksWritable(candidate) {
+    if (!candidate || candidate.length < 2)
+        return false;
+    if (candidate.startsWith('-') || candidate.startsWith('$'))
+        return false;
+    if (/^\/dev\//.test(candidate) || candidate === '/dev/null')
+        return false;
+    if (/[*?]/.test(candidate))
+        return false;
+    if (/^\d+$/.test(candidate) || /^&/.test(candidate))
+        return false;
+    if (/^[a-z]+:\/\//i.test(candidate))
+        return false;
+    // Shell commands are often embedded in JSON/JS blobs; anything carrying
+    // structural punctuation is a fragment of the wrapper, not a real path.
+    if (/["`{}()<>,;|&$\n]/.test(candidate))
+        return false;
+    if (/\[|\]/.test(candidate))
+        return false;
+    // A bare token must carry a real file extension; `r.source` is a property.
+    return candidate.includes('/') || KNOWN_EXT.test(candidate);
+}
+/**
+ * Target of `cp`/`mv`/`install`/`scp`/`rsync` — always the last operand.
+ * `scp remote:src local_dst` writes locally, so transfer tools only ever take
+ * the host spelled on the target itself, never the one elsewhere in the line.
+ */
+function copyTargets(command) {
+    const out = [];
+    for (const match of command.matchAll(/\b(cp|mv|install|scp|rsync)\b([^\n;|&]*)/g)) {
+        const via = match[1];
+        const operands = (match[2] ?? '')
+            .split(/\s+/)
+            .map((token) => token.replace(/^['"]+|['"]+$/g, ''))
+            .filter((token) => token && !token.startsWith('-'));
+        const target = operands.at(-1);
+        if (!target || operands.length < 2)
+            continue;
+        const transfer = via === 'scp' || via === 'rsync';
+        const remote = /^([\w.-]+)@([\w.-]+):(.+)$/.exec(target);
+        if (remote)
+            out.push({ path: remote[3], via, host: remote[2], hostFromTargetOnly: transfer });
+        else if (looksWritable(target))
+            out.push({ path: target, via, hostFromTargetOnly: transfer });
+    }
+    return out;
+}
+/** The untruncated shell command a tool call carries, if it is a shell tool. */
+export function rawCommand(turn) {
+    if (turn.kind !== 'tool_call' || !SHELL_TOOLS.has((turn.toolName ?? '').toLowerCase()))
+        return undefined;
+    const args = turn.toolArgs ?? {};
+    for (const key of COMMAND_ARGS) {
+        const value = args[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+        if (Array.isArray(value) && value.length)
+            return value.join(' ');
+    }
+    return undefined;
+}
+/**
+ * The command as it should be analysed: here-doc payloads removed, so that
+ * data being written never gets mistaken for commands being run.
+ */
+export function analyzableCommand(turn) {
+    const raw = rawCommand(turn);
+    return raw ? stripHeredocs(raw) : undefined;
+}
+/**
+ * Files a single tool call wrote. Explicit writes come from dedicated edit
+ * tools; inferred ones are parsed out of shell commands (heuristic — agents
+ * that write through the shell would otherwise leave no trace at all).
+ */
+export function fileWrites(turn) {
+    if (turn.kind !== 'tool_call')
+        return [];
+    const found = [];
+    const toolName = (turn.toolName ?? '').toLowerCase();
+    const args = turn.toolArgs ?? {};
+    if (EDIT_TOOLS.has(toolName)) {
+        for (const key of FILE_ARGS) {
+            const value = args[key];
+            if (typeof value === 'string' && value.trim()) {
+                found.push({
+                    path: absolutize(value),
+                    provenance: 'observed',
+                    extractor: `tool:${turn.toolName}`,
+                    event: turn.index,
+                });
+            }
+        }
+        const patch = typeof args.input === 'string' ? args.input : '';
+        for (const match of patch.matchAll(PATCH_FILE)) {
+            if (match[1]) {
+                found.push({
+                    path: absolutize(match[1].trim()),
+                    provenance: 'observed',
+                    extractor: 'patch:apply_patch',
+                    event: turn.index,
+                });
+            }
+        }
+    }
+    const raw = rawCommand(turn);
+    if (raw) {
+        // Everything below reads the command, never the here-doc payload.
+        const command = stripHeredocs(raw);
+        const host = SSH_HOST.exec(command)?.[1];
+        const add = (candidate, via, viaHost) => {
+            if (!looksWritable(candidate))
+                return;
+            // Remote paths must not be resolved against the local filesystem, and
+            // relative ones belong to the session's workspace — not to our cwd.
+            found.push({
+                path: viaHost ? candidate : absolutize(candidate),
+                // A shell write is a real action we saw run, just not a typed field.
+                provenance: 'derived',
+                extractor: `shell:${via}`,
+                event: turn.index,
+                ...(viaHost ? { host: viaHost } : {}),
+            });
+        };
+        for (const { via, re } of SHELL_PATTERNS) {
+            for (const match of command.matchAll(re)) {
+                const candidate = firstGroup(match);
+                if (candidate)
+                    add(candidate.trim(), via, host);
+            }
+        }
+        for (const target of copyTargets(command)) {
+            add(target.path, target.via, target.hostFromTargetOnly ? target.host : (target.host ?? host));
+        }
+    }
+    const seen = new Set();
+    return found.filter((write) => {
+        const key = `${write.host ?? ''}|${write.path}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Stable identity for a write: `host:path` when remote, otherwise an absolute
+ * local path (relative ones resolved against the session's workspace).
+ */
+export function resolveWritePath(write, workspace) {
+    if (write.host)
+        return `${write.host}:${write.path}`;
+    if (path.isAbsolute(write.path))
+        return write.path;
+    return workspace ? path.resolve(workspace, write.path) : write.path;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@1agents/session-reader",
+  "version": "0.1.1",
+  "description": "Read Plane: cross-agent session discovery, turn inspection, workspace aggregation and distillation from raw local session files.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "antigravity",
+    "session",
+    "transcript",
+    "jsonl",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scottzx/session-reader.git"
+  },
+  "bugs": {
+    "url": "https://github.com/scottzx/session-reader/issues"
+  },
+  "homepage": "https://github.com/scottzx/session-reader#readme",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "1session": "./dist/bin/1session.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test test/session-reader.test.ts",
+    "prepack": "npm run build",
+    "1session": "tsx bin/1session.ts"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}