@herbertgao/pi-extensions 2026.8.8 → 2026.8.10

package/node_modules/resume-from/dist/adapters/claude-code/entries.js

@@ -0,0 +1,107 @@
+/**
+ * The Claude Code session file: one JSON object per line.
+ *
+ * The store holds ten entry types (C-3). This module reads the few that carry turns and writes
+ * exactly two, `user` and `assistant` (C-9) — fewer types, fewer ways to corrupt the store.
+ */
+export const ENTRY_TYPE_USER = "user";
+export const ENTRY_TYPE_ASSISTANT = "assistant";
+export const ENTRY_TYPE_SUMMARY = "summary";
+/** The only entry types `serialize` writes (C-9). */
+export const WRITTEN_ENTRY_TYPES = [ENTRY_TYPE_USER, ENTRY_TYPE_ASSISTANT];
+/** Parse a session file. A line that is not a complete entry makes the whole file unreadable. */
+export function parseJsonl(text) {
+    const entries = [];
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (line.trim() === "")
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            return { entries, unreadable: `line ${i + 1} is not a complete entry` };
+        }
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            return { entries, unreadable: `line ${i + 1} is not an entry object` };
+        }
+        entries.push(value);
+    }
+    return { entries, unreadable: null };
+}
+/** Follow the last non-sidechain UUID record to the root of Claude's active transcript. */
+export function resolveActiveEntryPath(entries) {
+    const byUuid = new Map();
+    const mainEntries = [];
+    for (const entry of entries) {
+        if (entry.isSidechain === true || entry.uuid === undefined)
+            continue;
+        const uuid = asString(entry.uuid);
+        if (uuid === null)
+            return { entries: [], unreadable: "entry has a malformed uuid" };
+        if (byUuid.has(uuid)) {
+            return { entries: [], unreadable: `duplicate entry uuid ${uuid}` };
+        }
+        if (entry.parentUuid !== null && typeof entry.parentUuid !== "string") {
+            return {
+                entries: [],
+                unreadable: `entry ${uuid} has a malformed parentUuid`,
+            };
+        }
+        byUuid.set(uuid, entry);
+        mainEntries.push(entry);
+    }
+    const leaf = mainEntries[mainEntries.length - 1];
+    if (leaf === undefined)
+        return { entries: [], unreadable: null };
+    const reversed = [];
+    const visited = new Set();
+    let current = leaf;
+    while (current !== undefined) {
+        const uuid = asString(current.uuid);
+        if (uuid === null)
+            return { entries: [], unreadable: "active entry has no uuid" };
+        if (visited.has(uuid)) {
+            return {
+                entries: [],
+                unreadable: `entry graph contains a cycle at ${uuid}`,
+            };
+        }
+        visited.add(uuid);
+        reversed.push(current);
+        if (current.parentUuid === null)
+            break;
+        const parent = byUuid.get(current.parentUuid);
+        if (parent === undefined) {
+            return {
+                entries: [],
+                unreadable: `entry ${uuid} refers to missing parent ${String(current.parentUuid)}`,
+            };
+        }
+        current = parent;
+    }
+    return { entries: reversed.reverse(), unreadable: null };
+}
+export function asString(value) {
+    return typeof value === "string" && value !== "" ? value : null;
+}
+export function asObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    return value;
+}
+export function asArray(value) {
+    return Array.isArray(value) ? value : null;
+}
+/** ISO-8601 UTC, the vocabulary every timestamp of the canonical model uses. */
+export function toIsoUtc(value) {
+    const text = asString(value);
+    if (text === null)
+        return null;
+    const parsed = Date.parse(text);
+    if (!Number.isFinite(parsed))
+        return null;
+    return new Date(parsed).toISOString();
+}

package/node_modules/resume-from/dist/adapters/claude-code/index.d.ts

@@ -0,0 +1,3 @@
+/** The Claude Code adapter. Building it is the only thing this module offers (FR-57). */
+export { claudeCodeAdapter } from "./adapter.js";
+export type { ClaudeCodeAdapterFactory } from "./contract.js";

package/node_modules/resume-from/dist/adapters/claude-code/index.js

@@ -0,0 +1,2 @@
+/** The Claude Code adapter. Building it is the only thing this module offers (FR-57). */
+export { claudeCodeAdapter } from "./adapter.js";

package/node_modules/resume-from/dist/adapters/claude-code/layout.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where Claude Code keeps its sessions inside a home.
+ *
+ * A home holds `projects/<encoded repository path>/<session id>.jsonl`. The encoding and the
+ * default home are facts about the installed version, not assumptions: the live boundary test
+ * T-CC-16 lands a real session and compares it with what this file computes.
+ */
+import type { HomePath, SessionId } from "./contract.js";
+/** Session files live one directory per repository, under this directory of the home. */
+export declare const PROJECTS_DIR = "projects";
+export declare const SESSION_FILE_SUFFIX = ".jsonl";
+/** Claude Code reads this before falling back to ~/.claude. It is how `~/.claude-team` is named. */
+export declare const CONFIG_DIR_ENV = "CLAUDE_CONFIG_DIR";
+export declare const DEFAULT_HOME_BASENAME = ".claude";
+/** The home used when the user names none (FR-3). Absolute, resolved. */
+export declare function resolveDefaultHome(env?: Record<string, string | undefined>, userHome?: string): HomePath;
+/**
+ * The project directory name of a repository: the absolute path with every character that is
+ * not a letter or a digit replaced by a dash.
+ */
+export declare function encodeProjectPath(repoPath: string): string;
+export declare function projectsDir(home: HomePath): string;
+export declare function projectDir(home: HomePath, repoPath: string): string;
+export declare function sessionFilePath(home: HomePath, repoPath: string, id: SessionId): string;
+export declare function sessionIdOf(filePath: string): SessionId;
+/** Every session file of a home, across all of its project directories. */
+export declare function listSessionFiles(home: HomePath): Promise<string[]>;
+/** The file of one session id, or null when the home does not hold it. */
+export declare function findSessionFile(home: HomePath, id: SessionId): Promise<string | null>;

package/node_modules/resume-from/dist/adapters/claude-code/layout.js

@@ -0,0 +1,80 @@
+/**
+ * Where Claude Code keeps its sessions inside a home.
+ *
+ * A home holds `projects/<encoded repository path>/<session id>.jsonl`. The encoding and the
+ * default home are facts about the installed version, not assumptions: the live boundary test
+ * T-CC-16 lands a real session and compares it with what this file computes.
+ */
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+/** Session files live one directory per repository, under this directory of the home. */
+export const PROJECTS_DIR = "projects";
+export const SESSION_FILE_SUFFIX = ".jsonl";
+/** Claude Code reads this before falling back to ~/.claude. It is how `~/.claude-team` is named. */
+export const CONFIG_DIR_ENV = "CLAUDE_CONFIG_DIR";
+export const DEFAULT_HOME_BASENAME = ".claude";
+/** The home used when the user names none (FR-3). Absolute, resolved. */
+export function resolveDefaultHome(env = process.env, userHome = homedir()) {
+    const configured = env[CONFIG_DIR_ENV];
+    if (configured !== undefined && configured !== "" && path.isAbsolute(configured)) {
+        return path.resolve(configured);
+    }
+    return path.join(path.resolve(userHome), DEFAULT_HOME_BASENAME);
+}
+/**
+ * The project directory name of a repository: the absolute path with every character that is
+ * not a letter or a digit replaced by a dash.
+ */
+export function encodeProjectPath(repoPath) {
+    return path.resolve(repoPath).replace(/[^a-zA-Z0-9]/g, "-");
+}
+export function projectsDir(home) {
+    return path.join(home, PROJECTS_DIR);
+}
+export function projectDir(home, repoPath) {
+    return path.join(projectsDir(home), encodeProjectPath(repoPath));
+}
+export function sessionFilePath(home, repoPath, id) {
+    return path.join(projectDir(home, repoPath), `${id}${SESSION_FILE_SUFFIX}`);
+}
+export function sessionIdOf(filePath) {
+    return path.basename(filePath, SESSION_FILE_SUFFIX);
+}
+/** Every session file of a home, across all of its project directories. */
+export async function listSessionFiles(home) {
+    const root = projectsDir(home);
+    let projects;
+    try {
+        projects = (await readdir(root, { withFileTypes: true }))
+            .filter((item) => item.isDirectory())
+            .map((item) => item.name);
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const project of projects) {
+        const dir = path.join(root, project);
+        try {
+            for (const item of await readdir(dir, { withFileTypes: true })) {
+                if (item.isFile() && item.name.endsWith(SESSION_FILE_SUFFIX)) {
+                    files.push(path.join(dir, item.name));
+                }
+            }
+        }
+        catch {
+            // A project directory that cannot be read holds no session this tool can offer.
+        }
+    }
+    return files;
+}
+/** The file of one session id, or null when the home does not hold it. */
+export async function findSessionFile(home, id) {
+    const wanted = `${id}${SESSION_FILE_SUFFIX}`;
+    for (const file of await listSessionFiles(home)) {
+        if (path.basename(file) === wanted)
+            return file;
+    }
+    return null;
+}

package/node_modules/resume-from/dist/adapters/claude-code/readback.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reading a committed session back.
+ *
+ * C-9's own caution is why this is not optional: a throwaway directory holding one session does
+ * not prove a real store is safe, so the import compares what it wrote with what the store holds
+ * (FR-52) and whether the native resume list can open it (FR-51).
+ */
+import type { HomePath, SessionId, StoredSessionFacts } from "./contract.js";
+export declare function readBack(home: HomePath, sessionId: SessionId): Promise<StoredSessionFacts>;

package/node_modules/resume-from/dist/adapters/claude-code/readback.js

@@ -0,0 +1,39 @@
+/**
+ * Reading a committed session back.
+ *
+ * C-9's own caution is why this is not optional: a throwaway directory holding one session does
+ * not prove a real store is safe, so the import compares what it wrote with what the store holds
+ * (FR-52) and whether the native resume list can open it (FR-51).
+ */
+import { readFile } from "node:fs/promises";
+import { parseJsonl } from "./entries.js";
+import { findSessionFile } from "./layout.js";
+import { readSessionText } from "./reader.js";
+import { isStructurallyOpenable } from "./validation.js";
+export async function readBack(home, sessionId) {
+    const absent = {
+        sessionId,
+        itemCount: 0,
+        openable: false,
+    };
+    const file = await findSessionFile(home, sessionId);
+    if (file === null)
+        return absent;
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch {
+        return absent;
+    }
+    const { entries, unreadable } = parseJsonl(text);
+    const read = unreadable === null ? readSessionText(text) : null;
+    return {
+        sessionId,
+        itemCount: entries.length,
+        openable: unreadable === null &&
+            read?.unreadable === null &&
+            read.turns.length > 0 &&
+            isStructurallyOpenable(entries, sessionId),
+    };
+}

package/node_modules/resume-from/dist/adapters/claude-code/reader.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reading a Claude Code session into the neutral vocabulary.
+ *
+ * Two rules shape everything here: no result body crosses (FR-24) and no system prompt,
+ * environment value, token or hidden reasoning crosses (FR-28, NG-7). Both are enforced by
+ * what this file builds, not by what a caller does with it.
+ */
+import type { CanonicalSession, CanonicalTurn, HomePath, SessionDescriptor } from "./contract.js";
+/** FR-25: every dropped body is marked in text the model can read. */
+export declare const DROPPED_MARKER = "(content dropped: imported session, may be stale)";
+export declare const UNREADABLE_TITLE = "(unreadable session file)";
+export declare const UNTITLED = "(no user message)";
+export interface SessionReadResult {
+    turns: CanonicalTurn[];
+    /**
+     * Entries this adapter does not read: the other entry types of C-3, hidden reasoning, and
+     * everything FR-28 excludes. `AgentAdapter` has no field for this count, so it is reported
+     * here and asserted by T-CC-15.
+     */
+    skipped: number;
+    /** Set when the file is cut mid-entry. Then the session is not readable at all. */
+    unreadable: string | null;
+    title: string;
+    startedAt: string | null;
+    updatedAt: string | null;
+    repoPath: string | null;
+    branch: string | null;
+    changedPaths: string[];
+}
+/** The redacted source arguments, shortened so one call stays one line. */
+export declare function renderArguments(input: unknown): string;
+/** Read a whole session file into canonical turns. Pure: it takes the text, not a path. */
+export declare function readSessionText(text: string): SessionReadResult;
+/** One row per session file of the home, newest first (FR-11, FR-14). */
+export declare function listSessions(home: HomePath): Promise<SessionDescriptor[]>;
+/** One session in the neutral vocabulary. A file cut mid-entry is reported, never guessed at. */
+export declare function loadSession(descriptor: SessionDescriptor): Promise<CanonicalSession>;