@herbertgao/pi-extensions 2026.8.9 → 2026.8.11

package/node_modules/@herbertgao/resume-from/dist/adapters/codex/write.js

@@ -0,0 +1,141 @@
+/**
+ * The target role: a canonical session becomes a new Codex thread file.
+ *
+ * C-7 measured what does not work: the injection API writes `response_item` entries, and the
+ * resulting thread is absent from `thread/list` and shows zero turns on resume. C-8 measured what
+ * does: a file with session metadata and one `event_msg` entry per turn is listed, previewed and
+ * resumed with native turns. This module writes that file, and never calls that API.
+ */
+import { basename, isAbsolute } from "node:path";
+import { CODEX_CLI_VERSION, CODEX_ENTRY_EVENT_MSG, CODEX_ENTRY_SESSION_META, CODEX_EVENT_AGENT_MESSAGE, CODEX_EVENT_USER_MESSAGE, CODEX_ORIGINATOR, CODEX_SOURCE_CLI, isMessageEvent, rolloutFilePath, sessionIdFromRolloutFileName, stringifyRollout, } from "./rollout.js";
+import { inspectCodexRollout } from "./validation.js";
+export function serializeCodex(session, target, marker, deps) {
+    const importedAt = resolveStamp(marker.importedAt, session.provenance);
+    const sessionId = deps.newSessionId();
+    const stamp = importedAt.toISOString();
+    const entries = [sessionMetaEntry(sessionId, stamp, deps.cwd(), session)];
+    // Codex has no verified durable, out-of-context transcript entry. Do not encode
+    // provenance as an agent message: that would make imported metadata look like
+    // conversation and could send it back to the model on resume.
+    for (const turn of session.turns) {
+        const entry = turnEntry(turn, stamp);
+        if (entry !== null)
+            entries.push(entry);
+    }
+    return {
+        sessionId,
+        files: [
+            {
+                absolutePath: rolloutFilePath(target.home, sessionId, importedAt),
+                bytes: Buffer.from(stringifyRollout(entries), "utf8"),
+            },
+        ],
+        itemCount: entries.filter(isMessageEvent).length,
+    };
+}
+/**
+ * FR-50, read against C-7's symptoms: a thread without metadata or without a non-empty first
+ * user message is invisible to the picker, and a `response_item` entry is the shape C-8 replaced.
+ */
+export function validateCodex(serialized) {
+    const defects = [];
+    const file = serialized.files[0];
+    if (serialized.files.length !== 1 || file === undefined) {
+        defects.push({
+            path: "files",
+            message: "a Codex thread is exactly one rollout file",
+        });
+        return defects;
+    }
+    if (!isAbsolute(file.absolutePath) || !file.absolutePath.endsWith(".jsonl")) {
+        defects.push({
+            path: "files/0/absolutePath",
+            message: `Codex reads rollouts as absolute .jsonl paths, not ${file.absolutePath}`,
+        });
+    }
+    if (sessionIdFromRolloutFileName(basename(file.absolutePath)) !== serialized.sessionId) {
+        defects.push({
+            path: "files/0/absolutePath",
+            message: "the rollout filename names a different session",
+        });
+    }
+    const inspection = inspectCodexRollout(file.bytes.toString("utf8"), serialized.sessionId);
+    defects.push(...inspection.defects);
+    const written = inspection.itemCount;
+    if (written !== serialized.itemCount) {
+        defects.push({
+            path: "itemCount",
+            message: `itemCount says ${serialized.itemCount}, the rollout holds ${written} items`,
+        });
+    }
+    return defects;
+}
+function sessionMetaEntry(sessionId, stamp, cwd, session) {
+    const repo = session.provenance.repo;
+    const git = repo.commit !== null || repo.branch !== null
+        ? { git: { commit_hash: repo.commit, branch: repo.branch } }
+        : {};
+    return {
+        timestamp: stamp,
+        type: CODEX_ENTRY_SESSION_META,
+        payload: {
+            id: sessionId,
+            session_id: sessionId,
+            timestamp: stamp,
+            // Where the user is now. `codex resume` filters the picker by cwd by default.
+            cwd,
+            originator: CODEX_ORIGINATOR,
+            cli_version: CODEX_CLI_VERSION,
+            source: CODEX_SOURCE_CLI,
+            thread_source: "user",
+            model_provider: "openai",
+            ...git,
+        },
+    };
+}
+function turnEntry(turn, fallbackStamp) {
+    const text = turn.kind === "tool-call" ? (turn.toolCall?.outcomeLine ?? "") : turn.text;
+    if (text.trim() === "")
+        return null;
+    const stamp = turn.timestamp ?? fallbackStamp;
+    return turn.role === "user" ? userMessageEntry(text, stamp) : agentMessageEntry(text, stamp);
+}
+function userMessageEntry(message, stamp) {
+    return {
+        timestamp: stamp,
+        type: CODEX_ENTRY_EVENT_MSG,
+        payload: {
+            type: CODEX_EVENT_USER_MESSAGE,
+            message,
+            images: [],
+            local_images: [],
+            text_elements: [],
+        },
+    };
+}
+function agentMessageEntry(message, stamp) {
+    return {
+        timestamp: stamp,
+        type: CODEX_ENTRY_EVENT_MSG,
+        payload: {
+            type: CODEX_EVENT_AGENT_MESSAGE,
+            message,
+            phase: "commentary",
+            memory_citation: null,
+        },
+    };
+}
+/**
+ * Resolve the stamp for the serialized file without reading the clock.
+ * Chain: marker.importedAt → session.provenance.updatedAt → session.provenance.startedAt.
+ * If none parse, fall back to the Unix epoch so serialize stays deterministic (write design
+ * constraint: the preview and the commit of one request must agree, and no ambient state is read).
+ */
+function resolveStamp(importedAt, provenance) {
+    for (const candidate of [importedAt, provenance.updatedAt, provenance.startedAt]) {
+        const t = Date.parse(candidate);
+        if (!Number.isNaN(t))
+            return new Date(t);
+    }
+    return new Date(0);
+}

package/node_modules/@herbertgao/resume-from/dist/adapters/contract.d.ts

@@ -0,0 +1,74 @@
+import type { Bytes, PendingFile } from "../platform/store/contract.js";
+export type { Bytes, PendingFile };
+import type { AgentId, CanonicalSession, CanonicalTurn, HomePath, ProvenanceMarker, RepoSnapshot, SessionDescriptor, SessionId, SessionRef, SourceProvenance, TargetProfile, ToolCallRecord, ToolEffect, TurnKind, TurnRole } from "../session/contract.js";
+export type { AgentId, CanonicalSession, CanonicalTurn, HomePath, ProvenanceMarker, RepoSnapshot, SessionDescriptor, SessionId, SessionRef, SourceProvenance, TargetProfile, ToolCallRecord, ToolEffect, TurnKind, TurnRole, };
+/** How the agent lets the user choose a source session (FR-9, FR-10, FR-58). */
+export type SelectionLevel = "interactive-picker" | "numbered-list";
+/** How far the adapter can take the landing (FR-42). */
+export type LandingLevel = "create-and-switch" | "create-only";
+/** Which roles the adapter fills (FR-59). */
+export type AdapterRole = "source" | "target";
+/** How the agent can show the marker outside the model context (FR-47, FR-48). */
+export type ProvenanceSupport = "out-of-context-entry" | "host-output-only";
+/** Everything the rest of the system may know about one agent (FR-58). */
+export interface AgentCapabilities {
+    agent: AgentId;
+    roles: AdapterRole[];
+    selection: SelectionLevel;
+    landing: LandingLevel;
+    provenance: ProvenanceSupport;
+    /** Home used when the user names none (FR-3). */
+    defaultHome: HomePath;
+    /** Context window assumed for this agent when configuration overrides none (FR-18). */
+    defaultWindowTokens: number;
+}
+/**
+ * An opaque handle supplied by the host of the same agent, for example Pi's
+ * command context. Nothing outside the adapter of that agent inspects it.
+ */
+export type AgentRuntime = unknown;
+/** A structural defect found before placement (FR-50). */
+export interface ValidationDefect {
+    /** Pointer into the offending item, for example "items/3/usage". */
+    path: string;
+    /** What is missing or malformed, and why the agent would fail on it. */
+    message: string;
+}
+/** What serializing a canonical session into the target format produced. */
+export interface SerializedSession {
+    sessionId: SessionId;
+    /** The files to create. The adapter never writes them itself (FR-49, FR-53). */
+    files: PendingFile[];
+    /** Items the adapter expects the target to store (FR-52). */
+    itemCount: number;
+}
+/** What the target actually holds, read back after the commit (FR-51, FR-52). */
+export interface StoredSessionFacts {
+    sessionId: SessionId;
+    /** Items the target stored. A difference from itemCount is an error (FR-52). */
+    itemCount: number;
+    /** True when the target's own commands can open the session (FR-51). */
+    openable: boolean;
+}
+/** The outcome of asking the agent to move the user into the new session (FR-44). */
+export interface SwitchOutcome {
+    switched: boolean;
+    /** True when the agent asked the user and the user declined. */
+    cancelled: boolean;
+}
+/** What every agent adapter provides. One folder per agent implements it (FR-57). */
+export interface AgentAdapter {
+    capabilities(): AgentCapabilities;
+    /** Source role. Opens source files for reading only (FR-8, NG-1, AC-4). */
+    listSessions(home: HomePath): Promise<SessionDescriptor[]>;
+    /** Source role. Reads one session into the neutral vocabulary. Drops every result body. */
+    loadSession(descriptor: SessionDescriptor): Promise<CanonicalSession>;
+    /** Target role. Produces bytes only. It never creates a file (FR-49, FR-53). */
+    serialize(session: CanonicalSession, target: TargetProfile, marker: ProvenanceMarker): SerializedSession;
+    /** Target role. Checks the structure before placement. Empty means valid (FR-50). */
+    validate(serialized: SerializedSession): ValidationDefect[];
+    /** Target role. Reads the committed session back, to compare item counts (FR-51, FR-52). */
+    readBack(home: HomePath, sessionId: SessionId): Promise<StoredSessionFacts>;
+    /** Target role, only when capabilities().landing is "create-and-switch" (FR-43, FR-44). */
+    switchTo(home: HomePath, sessionId: SessionId, runtime: AgentRuntime): Promise<SwitchOutcome>;
+}

package/node_modules/@herbertgao/resume-from/dist/adapters/contract.js

@@ -0,0 +1,4 @@
+// GENERATED from src/adapters/module.md — the Public Contract section is the normative home.
+// Declarations only: no behaviour, no defaults. If this file and module.md disagree,
+// the document wins and this file is corrected.
+export {};

package/node_modules/@herbertgao/resume-from/dist/adapters/pi/adapter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The Pi adapter. It fills both roles of the port: it reads Pi sessions into the canonical
+ * vocabulary, and it writes canonical sessions back into files Pi can open.
+ *
+ * It never writes a file — `serialize` hands `PendingFile` values to `src/import/landing/`
+ * (FR-49, FR-53) — never opens a source session for writing (NG-1, AC-4), never calls Pi's
+ * model, and never opens a network connection (FR-8).
+ */
+import type { AgentAdapter } from "./contract.js";
+import { type PiSerializeDeps } from "./serialize.js";
+export interface PiAdapterDeps extends PiSerializeDeps {
+    /** Pi's own default agent directory. Overridden only by tests. */
+    defaultHome(): string;
+}
+export declare function createPiAdapter(overrides?: Partial<PiAdapterDeps>): AgentAdapter;

package/node_modules/@herbertgao/resume-from/dist/adapters/pi/adapter.js

@@ -0,0 +1,209 @@
+/**
+ * The Pi adapter. It fills both roles of the port: it reads Pi sessions into the canonical
+ * vocabulary, and it writes canonical sessions back into files Pi can open.
+ *
+ * It never writes a file — `serialize` hands `PendingFile` values to `src/import/landing/`
+ * (FR-49, FR-53) — never opens a source session for writing (NG-1, AC-4), never calls Pi's
+ * model, and never opens a network connection (FR-8).
+ */
+import { randomUUID } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { DEFAULT_WINDOW_TOKENS, defaultPiHome, sessionIdFromFileName, sessionsRoot, shortTitle, toIsoUtc, UNREADABLE_TITLE_PREFIX, } from "./format.js";
+import { changedPathsFromEntries, entriesToTurns, lastTimestamp, parseSessionText, resolveActiveEntries, titleFromEntries, } from "./parse.js";
+import { serializeSession } from "./serialize.js";
+import { validateSerialized } from "./validate.js";
+const DEFAULT_DEPS = {
+    cwd: () => process.cwd(),
+    now: () => new Date(),
+    newSessionId: () => randomUUID(),
+    newEntryId: () => randomUUID().slice(0, 8),
+    defaultHome: defaultPiHome,
+};
+/** Every `.jsonl` below `<home>/sessions/`. Pi keeps one directory per repository. */
+async function sessionFilesIn(home) {
+    const root = sessionsRoot(home);
+    const files = [];
+    const walk = async (dir, depth) => {
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const full = join(dir, name);
+            let isDirectory;
+            try {
+                isDirectory = (await stat(full)).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDirectory) {
+                if (depth > 0)
+                    await walk(full, depth - 1);
+                continue;
+            }
+            if (name.endsWith(".jsonl"))
+                files.push(full);
+        }
+    };
+    await walk(root, 2);
+    return files;
+}
+async function findSessionFile(home, sessionId) {
+    const suffix = `_${sessionId}.jsonl`;
+    for (const file of await sessionFilesIn(home)) {
+        const name = basename(file);
+        if (name.endsWith(suffix) || sessionIdFromFileName(name) === sessionId)
+            return file;
+    }
+    return null;
+}
+function describe(home, filePath, text, fileTime) {
+    const parsed = parseSessionText(text);
+    const id = parsed.header?.id ?? sessionIdFromFileName(basename(filePath)) ?? basename(filePath);
+    const ref = { agent: "pi", home, id };
+    const startedAt = toIsoUtc(parsed.header?.timestamp) ?? fileTime;
+    const resolved = resolveActiveEntries(parsed.entries);
+    if (!parsed.header || parsed.truncated || resolved.unreadable !== null) {
+        return {
+            ref,
+            title: `${UNREADABLE_TITLE_PREFIX}${basename(filePath)}`,
+            startedAt,
+            updatedAt: lastTimestamp(resolved.activePath) ?? fileTime,
+            turnCount: 0,
+            repoPath: null,
+            filePath,
+        };
+    }
+    const loaded = entriesToTurns(parsed.entries);
+    const title = titleFromEntries(resolved.activePath);
+    return {
+        ref,
+        title: title ? shortTitle(title) : `${basename(filePath)}`,
+        startedAt,
+        updatedAt: lastTimestamp(resolved.activePath) ?? startedAt,
+        turnCount: loaded.turns.length,
+        repoPath: parsed.header.cwd.length > 0 ? parsed.header.cwd : null,
+        filePath,
+    };
+}
+/** The part of a Pi command context this module uses, and nothing else (C-10). */
+function asSwitchContext(runtime) {
+    if (typeof runtime !== "object" || runtime === null) {
+        throw new TypeError("the Pi adapter needs a PiSwitchContext with a switchSession function, and got " +
+            `${runtime === null ? "null" : typeof runtime}`);
+    }
+    const candidate = runtime;
+    if (typeof candidate.switchSession !== "function") {
+        throw new TypeError("the Pi adapter needs a PiSwitchContext with a switchSession function, and the runtime handle has none");
+    }
+    return runtime;
+}
+export function createPiAdapter(overrides = {}) {
+    const deps = { ...DEFAULT_DEPS, ...overrides };
+    return {
+        capabilities() {
+            return {
+                agent: "pi",
+                // Pi is the only agent of the three that can move the user itself (C-10).
+                roles: ["source", "target"],
+                selection: "interactive-picker",
+                landing: "create-and-switch",
+                provenance: "out-of-context-entry",
+                defaultHome: deps.defaultHome(),
+                defaultWindowTokens: DEFAULT_WINDOW_TOKENS,
+            };
+        },
+        async listSessions(home) {
+            const descriptors = [];
+            // Whole-file read and full parse per file: title, turn count, and updatedAt all require
+            // parsing the entire JSONL (FR-11). Same approach as the claude-code adapter (not
+            // separately benchmarked for Pi files); revisit if a home with thousands of sessions
+            // makes the listing noticeably slow to users.
+            for (const filePath of await sessionFilesIn(home)) {
+                let text;
+                let fileTime;
+                try {
+                    text = await readFile(filePath, "utf8");
+                    fileTime = new Date((await stat(filePath)).mtimeMs).toISOString();
+                }
+                catch {
+                    continue;
+                }
+                descriptors.push(describe(home, filePath, text, fileTime));
+            }
+            return descriptors.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+        },
+        async loadSession(descriptor) {
+            const text = await readFile(descriptor.filePath, "utf8");
+            const parsed = parseSessionText(text);
+            const resolved = resolveActiveEntries(parsed.entries);
+            if (!parsed.header || parsed.truncated || resolved.unreadable !== null) {
+                throw new Error(`the Pi session file ${descriptor.filePath} cannot be read: it is truncated or not a Pi session`);
+            }
+            const loaded = entriesToTurns(parsed.entries);
+            const startedAt = toIsoUtc(parsed.header.timestamp) ?? descriptor.startedAt;
+            return {
+                provenance: {
+                    ref: { agent: "pi", home: descriptor.ref.home, id: parsed.header.id },
+                    title: descriptor.title,
+                    startedAt,
+                    updatedAt: lastTimestamp(resolved.activePath) ?? startedAt,
+                    repo: {
+                        // Pi records neither the commit nor the branch of a session.
+                        commit: null,
+                        branch: null,
+                        changedPaths: changedPathsFromEntries(resolved.activePath),
+                    },
+                },
+                turns: loaded.turns,
+            };
+        },
+        serialize(session, target, marker) {
+            return serializeSession(session, target, marker, deps);
+        },
+        validate(serialized) {
+            return validateSerialized(serialized);
+        },
+        async readBack(home, sessionId) {
+            const filePath = await findSessionFile(home, sessionId);
+            if (!filePath)
+                return { sessionId, itemCount: 0, openable: false };
+            let parsed;
+            try {
+                parsed = parseSessionText(await readFile(filePath, "utf8"));
+            }
+            catch {
+                return { sessionId, itemCount: 0, openable: false };
+            }
+            return {
+                sessionId,
+                itemCount: parsed.entries.length,
+                openable: parsed.header?.id === sessionId &&
+                    !parsed.truncated &&
+                    resolveActiveEntries(parsed.entries).unreadable === null,
+            };
+        },
+        async switchTo(home, sessionId, runtime) {
+            const context = asSwitchContext(runtime);
+            const filePath = await findSessionFile(home, sessionId);
+            if (!filePath) {
+                throw new Error(`the Pi home ${home} holds no session ${sessionId} to switch to`);
+            }
+            // Called from a Pi command handler only. The deleted design documents claimed a call
+            // from an event handler deadlocks; the claim was never tested, so this module only
+            // uses the path C-10 proved. `src/host/pi-extension/` guarantees the call site.
+            const result = await context.switchSession(filePath, {
+                withSession: () => undefined,
+            });
+            const cancelled = result?.cancelled === true;
+            // A cancelled switch is not a failure: the session stays committed and the user opens
+            // it later with Pi's own command.
+            return { switched: !cancelled, cancelled };
+        },
+    };
+}

package/node_modules/@herbertgao/resume-from/dist/adapters/pi/contract.d.ts

@@ -0,0 +1,24 @@
+import type { AdapterRole, AgentAdapter, AgentCapabilities, AgentRuntime, Bytes, LandingLevel, PendingFile, ProvenanceSupport, SelectionLevel, SerializedSession, StoredSessionFacts, SwitchOutcome, ValidationDefect } from "../contract.js";
+export type { AdapterRole, AgentAdapter, AgentCapabilities, AgentRuntime, Bytes, LandingLevel, PendingFile, ProvenanceSupport, SelectionLevel, SerializedSession, StoredSessionFacts, SwitchOutcome, ValidationDefect, };
+import type { AgentId, CanonicalSession, CanonicalTurn, HomePath, ProvenanceMarker, RepoSnapshot, SessionDescriptor, SessionId, SessionRef, SourceProvenance, TargetProfile, ToolCallRecord, ToolEffect, TurnKind, TurnRole } from "../../session/contract.js";
+export type { AgentId, CanonicalSession, CanonicalTurn, HomePath, ProvenanceMarker, RepoSnapshot, SessionDescriptor, SessionId, SessionRef, SourceProvenance, TargetProfile, ToolCallRecord, ToolEffect, TurnKind, TurnRole, };
+/** The options Pi's switchSession takes (C-10). */
+export interface PiSwitchOptions {
+    /** Pi calls this once the new session is active. */
+    withSession: () => void;
+}
+/** What Pi's switchSession returns (C-10). */
+export interface PiSwitchResult {
+    cancelled: boolean;
+}
+/**
+ * The part of Pi's command context this module uses. `src/host/pi-extension/`
+ * supplies it as the AgentRuntime handle; nothing else may construct one (C-10).
+ */
+export interface PiSwitchContext {
+    switchSession(path: string, options: PiSwitchOptions): Promise<PiSwitchResult>;
+}
+/** Builds the Pi adapter. The only export of this module (FR-57). */
+export interface PiAdapterFactory {
+    create(): AgentAdapter;
+}

package/node_modules/@herbertgao/resume-from/dist/adapters/pi/contract.js

@@ -0,0 +1,4 @@
+// GENERATED from src/adapters/pi/module.md — the Public Contract section is the normative home.
+// Declarations only: no behaviour, no defaults. If this file and module.md disagree,
+// the document wins and this file is corrected.
+export {};

package/node_modules/@herbertgao/resume-from/dist/adapters/pi/format.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Everything this tool knows about Pi's session file layout.
+ *
+ * Verified against the installed Pi 0.83.0 (`dist/core/session-manager.js`,
+ * `dist/config.js`), not assumed:
+ *
+ * - the home is Pi's agent directory: `$PI_CODING_AGENT_DIR`, else `~/.pi/agent`;
+ * - sessions live in `<home>/sessions/<encoded cwd>/<timestamp>_<id>.jsonl`;
+ * - a file is JSONL: one `session` header, then entries with `id`/`parentId`/`timestamp`;
+ * - an assistant message without a numeric `usage` object crashes Pi (C-11).
+ *
+ * When Pi changes, this file changes. Nothing outside this folder holds these facts.
+ */
+import type { ToolEffect } from "./contract.js";
+/** Pi's current session file version (`CURRENT_SESSION_VERSION`). */
+export declare const PI_SESSION_VERSION = 3;
+export declare const SESSIONS_DIR_NAME = "sessions";
+/**
+ * The customType of the provenance entry. It is written as a `custom` entry, which Pi's
+ * `buildSessionContext` drops on the floor: the marker is stored and shown, never sent to
+ * the model (FR-47, FR-48). `src/host/pi-extension/` registers the renderer that shows it.
+ */
+export declare const MARKER_CUSTOM_TYPE = "resume-from-provenance";
+/** Prefix of the title of a session file that cannot be read (T-PI-13). */
+export declare const UNREADABLE_TITLE_PREFIX = "(unreadable) ";
+/** What replaces a tool result body (FR-24, FR-25). */
+export declare const DROPPED_BODY_NOTE = "(content dropped: imported session, may be stale)";
+/** Context window assumed for Pi when configuration overrides none (FR-18). */
+export declare const DEFAULT_WINDOW_TOKENS = 200000;
+/** What an imported assistant turn declares about itself. It cost nothing to import. */
+export declare const IMPORTED_API = "resume-from";
+export declare const IMPORTED_PROVIDER = "resume-from";
+export declare const IMPORTED_MODEL = "imported-session";
+/** Pi's default agent directory. Mirrors Pi's own `getAgentDir()`. */
+export declare function defaultPiHome(): string;
+/** Pi's encoding of a working directory into one directory name. */
+export declare function encodeCwd(cwd: string): string;
+export declare function sessionsRoot(home: string): string;
+export declare function sessionDirFor(home: string, cwd: string): string;
+/** Pi's own file naming: the ISO timestamp with `:` and `.` replaced, then the id. */
+export declare function sessionFileName(isoTimestamp: string, sessionId: string): string;
+/** The session id Pi would read out of a session file name, or null. */
+export declare function sessionIdFromFileName(fileName: string): string | null;
+export interface PiSessionHeader {
+    type: "session";
+    version?: number;
+    id: string;
+    timestamp: string;
+    cwd: string;
+}
+export interface PiEntryBase {
+    type: string;
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+}
+export type PiEntry = PiEntryBase & Record<string, unknown>;
+export interface PiTextBlock {
+    type: "text";
+    text: string;
+    textSignature?: string;
+}
+export interface PiThinkingBlock {
+    type: "thinking";
+    thinking: string;
+    thinkingSignature?: string;
+}
+export interface PiImageBlock {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export interface PiToolCallBlock {
+    type: "toolCall";
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export type PiContentBlock = PiTextBlock | PiThinkingBlock | PiToolCallBlock | PiImageBlock;
+/** The six numbers Pi dereferences without a guard. Missing any of them is C-11. */
+export interface PiUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    reasoning?: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+export interface PiUserMessage {
+    role: "user";
+    content: string | PiContentBlock[];
+    timestamp: number;
+}
+export interface PiAssistantMessage {
+    role: "assistant";
+    content: PiContentBlock[];
+    api: string;
+    provider: string;
+    model: string;
+    usage: PiUsage;
+    stopReason: string;
+    timestamp: number;
+}
+export interface PiToolResultMessage {
+    role: "toolResult";
+    toolCallId: string;
+    toolName: string;
+    content: PiContentBlock[];
+    isError: boolean;
+    timestamp: number;
+}
+export type PiMessage = PiUserMessage | PiAssistantMessage | PiToolResultMessage;
+export interface PiMessageEntry extends PiEntryBase {
+    type: "message";
+    message: PiMessage;
+}
+export interface PiCompactionEntry extends PiEntryBase {
+    type: "compaction";
+    summary: string;
+    firstKeptEntryId?: string;
+    retainedTail?: PiMessage[];
+    tokensBefore: number;
+}
+export interface PiCustomEntry extends PiEntryBase {
+    type: "custom";
+    customType: string;
+    data?: unknown;
+}
+/**
+ * Entry types Pi writes that carry no turn: settings, bookmarks, and extension state.
+ * They are known, so they are not reported as skipped.
+ *
+ * `custom_message` is deliberately absent. Pi's `sessionEntryToContextMessages` turns it
+ * into a real context message, so an extension can put conversation content there. This
+ * adapter does not know that content's shape, so it is skipped — and counted, so the skip
+ * is visible rather than a silent shortening of the session.
+ */
+export declare const NON_TURN_ENTRY_TYPES: ReadonlySet<string>;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function asHeader(value: unknown): PiSessionHeader | null;
+export declare function asEntry(value: unknown): PiEntry | null;
+export declare function entryMessage(entry: PiEntry): Record<string, unknown> | null;
+/** The visible text of a message content, hidden reasoning excluded (FR-28). */
+export declare function visibleText(content: unknown): string;
+export declare function toolCallBlocks(content: unknown): PiToolCallBlock[];
+/** Did the call change the repository? (FR-26) A shell is never assumed either way. */
+export declare function toolEffectFor(toolName: string): ToolEffect;
+/** One line, whatever the input contained. */
+export declare function oneLine(text: string): string;
+export declare function truncate(text: string, limit: number): string;
+export declare function shortArguments(argumentsText: string): string;
+export declare function shortTitle(text: string): string;
+/** ISO-8601 UTC, or null when the source recorded nothing usable. */
+export declare function toIsoUtc(value: unknown): string | null;
+export declare function emptyUsage(): PiUsage;