pi-extensions 0.1.9

package/files-widget/viewer.ts

@@ -0,0 +1,424 @@
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+
+import {
+  DEFAULT_VIEWER_HEIGHT,
+  MAX_VIEWER_HEIGHT,
+  MIN_PANEL_HEIGHT,
+  SEARCH_SCROLL_OFFSET,
+  VIEWER_SCROLL_MARGIN,
+} from "./constants";
+import { loadFileContent } from "./file-viewer";
+import type { FileNode } from "./types";
+import { isUntrackedStatus } from "./utils";
+import { isPrintableChar } from "./input-utils";
+
+export interface CommentPayload {
+  relPath: string;
+  lineRange: string;
+  ext: string;
+  selectedText: string;
+}
+
+export type ViewerAction =
+  | { type: "none" }
+  | { type: "close" }
+  | { type: "navigate"; direction: 1 | -1 };
+
+type ViewerMode = "normal" | "select" | "search" | "comment";
+
+interface ViewerState {
+  file: FileNode | null;
+  content: string[];
+  rawContent: string;
+  scroll: number;
+  diffMode: boolean;
+  mode: ViewerMode;
+  selectStart: number;
+  selectEnd: number;
+  commentText: string;
+  searchQuery: string;
+  searchMatches: number[];
+  searchIndex: number;
+  lastRenderWidth: number;
+  height: number;
+}
+
+export interface ViewerController {
+  isOpen(): boolean;
+  getFile(): FileNode | null;
+  setFile(file: FileNode): void;
+  updateFileRef(file: FileNode | null): void;
+  close(): void;
+  render(width: number): string[];
+  handleInput(data: string): ViewerAction;
+}
+
+export function createViewer(
+  cwd: string,
+  theme: Theme,
+  requestComment: (payload: CommentPayload, comment: string) => void
+): ViewerController {
+  const state: ViewerState = {
+    file: null,
+    content: [],
+    rawContent: "",
+    scroll: 0,
+    diffMode: false,
+    mode: "normal",
+    selectStart: 0,
+    selectEnd: 0,
+    commentText: "",
+    searchQuery: "",
+    searchMatches: [],
+    searchIndex: 0,
+    lastRenderWidth: 0,
+    height: DEFAULT_VIEWER_HEIGHT,
+  };
+
+  function resetSearch(): void {
+    state.searchQuery = "";
+    state.searchMatches = [];
+    state.searchIndex = 0;
+  }
+
+  function resetComment(): void {
+    state.commentText = "";
+  }
+
+  function clearSelection(): void {
+    state.selectStart = 0;
+    state.selectEnd = 0;
+  }
+
+  function setMode(mode: ViewerMode): void {
+    state.mode = mode;
+    if (mode !== "search") resetSearch();
+    if (mode !== "comment") resetComment();
+    if (mode === "normal") {
+      clearSelection();
+    }
+  }
+
+  function reloadContent(width: number): void {
+    if (!state.file) return;
+    const hasChanges = !!state.file.gitStatus;
+    state.content = loadFileContent(state.file.path, cwd, state.diffMode, hasChanges, width);
+    state.lastRenderWidth = width;
+  }
+
+  function updateSearchMatches(): void {
+    state.searchMatches = [];
+    if (!state.searchQuery) return;
+
+    const q = state.searchQuery.toLowerCase();
+    const rawLines = state.rawContent.split("\n");
+    for (let i = 0; i < rawLines.length; i++) {
+      if (rawLines[i].toLowerCase().includes(q)) {
+        state.searchMatches.push(i);
+      }
+    }
+    state.searchIndex = 0;
+
+    if (state.searchMatches.length > 0) {
+      state.scroll = Math.max(0, state.searchMatches[0] - SEARCH_SCROLL_OFFSET);
+    }
+  }
+
+  function jumpToNextMatch(direction: 1 | -1): void {
+    if (state.searchMatches.length === 0) return;
+    state.searchIndex += direction;
+    if (state.searchIndex < 0) state.searchIndex = state.searchMatches.length - 1;
+    if (state.searchIndex >= state.searchMatches.length) state.searchIndex = 0;
+    state.scroll = Math.max(0, state.searchMatches[state.searchIndex] - SEARCH_SCROLL_OFFSET);
+  }
+
+  function buildCommentPayload(): CommentPayload | null {
+    if (!state.file) return null;
+
+    const rawLines = state.rawContent.split("\n");
+    const selectedText = rawLines.slice(state.selectStart, state.selectEnd + 1).join("\n");
+    const relPath = relative(cwd, state.file.path);
+    const lineRange = state.selectStart === state.selectEnd
+      ? `line ${state.selectStart + 1}`
+      : `lines ${state.selectStart + 1}-${state.selectEnd + 1}`;
+    const ext = state.file.name.split(".").pop() || "";
+
+    return { relPath, lineRange, ext, selectedText };
+  }
+
+  function sendComment(comment: string): void {
+    const payload = buildCommentPayload();
+    if (!payload) return;
+
+    requestComment(payload, comment);
+    setMode("normal");
+  }
+
+  function renderHeader(width: number): string {
+    if (!state.file) return "";
+    const isUntracked = isUntrackedStatus(state.file.gitStatus);
+
+    let header = theme.bold(state.file.name);
+    if (isUntracked) {
+      header += theme.fg("dim", " [UNTRACKED]");
+    } else if (state.diffMode) {
+      header += theme.fg("warning", " [DIFF]");
+    }
+    if (state.mode === "select" || state.mode === "comment") {
+      header += theme.fg("accent", ` [SELECT ${state.selectStart + 1}-${state.selectEnd + 1}]`);
+    }
+
+    if (state.file.diffStats) {
+      if (state.file.diffStats.additions > 0) {
+        header += theme.fg("success", ` +${state.file.diffStats.additions}`);
+      }
+      if (state.file.diffStats.deletions > 0) {
+        header += theme.fg("error", ` -${state.file.diffStats.deletions}`);
+      }
+    } else if (isUntracked && state.file.lineCount !== undefined) {
+      header += theme.fg("success", ` +${state.file.lineCount}`);
+    }
+
+    if (state.file.lineCount !== undefined) {
+      header += theme.fg("dim", ` ${state.file.lineCount}L`);
+    }
+
+    if (state.mode === "search") {
+      header += theme.fg("accent", `  /${state.searchQuery}█`);
+    } else if (state.searchQuery && state.searchMatches.length > 0) {
+      header += theme.fg("dim", ` [${state.searchIndex + 1}/${state.searchMatches.length}]`);
+    }
+
+    return truncateToWidth(header, width);
+  }
+
+  function renderFooter(width: number): string[] {
+    const lines: string[] = [];
+    const pct = state.content.length > 0
+      ? Math.round((state.scroll / Math.max(1, state.content.length - state.height)) * 100)
+      : 0;
+
+    if (state.mode === "comment") {
+      const prompt = theme.fg("accent", `Comment: ${state.commentText}█`);
+      lines.push(truncateToWidth(prompt, width));
+      lines.push(theme.fg("borderMuted", "─".repeat(width)));
+    }
+
+    let help: string;
+    if (state.mode === "comment") {
+      help = theme.fg("dim", "Enter: send  Esc: cancel");
+    } else if (state.mode === "select") {
+      help = theme.fg("dim", "j/k: extend  c: comment  Esc: cancel");
+    } else if (state.mode === "search") {
+      help = theme.fg("dim", "Type to search  Enter: confirm  Esc: cancel");
+    } else {
+      const isUntracked = state.file && isUntrackedStatus(state.file.gitStatus);
+      help = theme.fg(
+        "dim",
+        `j/k: scroll  /: search  n/N: next/prev match  []: files  ${state.file?.gitStatus && !isUntracked ? "d: diff  " : ""}q: back  ${pct}%`
+      );
+    }
+    lines.push(truncateToWidth(help, width));
+
+    return lines;
+  }
+
+  return {
+    isOpen(): boolean {
+      return !!state.file;
+    },
+
+    getFile(): FileNode | null {
+      return state.file;
+    },
+
+    setFile(file: FileNode): void {
+      state.file = file;
+      state.scroll = 0;
+      state.diffMode = !!file.gitStatus && !isUntrackedStatus(file.gitStatus);
+      setMode("normal");
+      state.content = [];
+      state.lastRenderWidth = 0;
+
+      try {
+        state.rawContent = readFileSync(file.path, "utf-8");
+        file.lineCount = state.rawContent.split("\n").length;
+      } catch {
+        state.rawContent = "";
+        file.lineCount = undefined;
+      }
+    },
+
+    updateFileRef(file: FileNode | null): void {
+      state.file = file;
+    },
+
+    close(): void {
+      state.file = null;
+      state.content = [];
+      setMode("normal");
+    },
+
+    render(width: number): string[] {
+      if (!state.file) return [];
+
+      if (state.lastRenderWidth !== width || state.content.length === 0) {
+        reloadContent(width);
+      }
+
+      const lines: string[] = [];
+      lines.push(renderHeader(width));
+      lines.push(theme.fg("borderMuted", "─".repeat(width)));
+
+      const visible = state.content.slice(state.scroll, state.scroll + state.height);
+      for (let i = 0; i < state.height; i++) {
+        if (i < visible.length) {
+          const lineIdx = state.scroll + i;
+          let line = truncateToWidth(visible[i] || "", width);
+          if ((state.mode === "select" || state.mode === "comment") && lineIdx >= state.selectStart && lineIdx <= state.selectEnd) {
+            line = theme.bg("selectedBg", line);
+          }
+          lines.push(line);
+        } else {
+          lines.push(theme.fg("dim", "~"));
+        }
+      }
+
+      lines.push(theme.fg("borderMuted", "─".repeat(width)));
+      lines.push(...renderFooter(width));
+
+      return lines;
+    },
+
+    handleInput(data: string): ViewerAction {
+      if (!state.file) return { type: "none" };
+
+      if (state.mode === "comment") {
+        if (matchesKey(data, Key.enter)) {
+          const comment = state.commentText.trim();
+          if (comment) {
+            sendComment(comment);
+          } else {
+            setMode("normal");
+          }
+        } else if (matchesKey(data, Key.escape)) {
+          setMode("normal");
+        } else if (matchesKey(data, Key.backspace)) {
+          state.commentText = state.commentText.slice(0, -1);
+        } else if (isPrintableChar(data)) {
+          state.commentText += data;
+        }
+        return { type: "none" };
+      }
+
+      if (state.mode === "search") {
+        if (matchesKey(data, Key.enter)) {
+          setMode("normal");
+        } else if (matchesKey(data, Key.escape)) {
+          setMode("normal");
+        } else if (matchesKey(data, Key.backspace)) {
+          state.searchQuery = state.searchQuery.slice(0, -1);
+          updateSearchMatches();
+        } else if (isPrintableChar(data)) {
+          state.searchQuery += data;
+          updateSearchMatches();
+        }
+        return { type: "none" };
+      }
+
+      if (matchesKey(data, "q") && state.mode !== "select") {
+        return { type: "close" };
+      }
+      if (matchesKey(data, Key.escape)) {
+        if (state.mode === "select") {
+          setMode("normal");
+        } else if (state.searchQuery) {
+          resetSearch();
+        } else {
+          return { type: "close" };
+        }
+        return { type: "none" };
+      }
+      if (matchesKey(data, "/") && state.mode !== "select") {
+        setMode("search");
+        return { type: "none" };
+      }
+      if (matchesKey(data, "n") && state.mode !== "select" && state.searchMatches.length > 0) {
+        jumpToNextMatch(1);
+        return { type: "none" };
+      }
+      if (matchesKey(data, "N") && state.mode !== "select" && state.searchMatches.length > 0) {
+        jumpToNextMatch(-1);
+        return { type: "none" };
+      }
+      if (matchesKey(data, "j") || matchesKey(data, Key.down)) {
+        if (state.mode === "select") {
+          state.selectEnd = Math.min(state.content.length - 1, state.selectEnd + 1);
+        } else {
+          state.scroll = Math.min(Math.max(0, state.content.length - VIEWER_SCROLL_MARGIN), state.scroll + 1);
+        }
+        return { type: "none" };
+      }
+      if (matchesKey(data, "k") || matchesKey(data, Key.up)) {
+        if (state.mode === "select") {
+          state.selectEnd = Math.max(state.selectStart, state.selectEnd - 1);
+        } else {
+          state.scroll = Math.max(0, state.scroll - 1);
+        }
+        return { type: "none" };
+      }
+      if (matchesKey(data, Key.pageDown)) {
+        state.scroll = Math.min(Math.max(0, state.content.length - state.height), state.scroll + state.height);
+        return { type: "none" };
+      }
+      if (matchesKey(data, Key.pageUp)) {
+        state.scroll = Math.max(0, state.scroll - state.height);
+        return { type: "none" };
+      }
+      if (matchesKey(data, "g")) {
+        state.scroll = 0;
+        return { type: "none" };
+      }
+      if (matchesKey(data, "G")) {
+        state.scroll = Math.max(0, state.content.length - state.height);
+        return { type: "none" };
+      }
+      if (matchesKey(data, "+") || matchesKey(data, "=")) {
+        state.height = Math.min(MAX_VIEWER_HEIGHT, state.height + 5);
+        return { type: "none" };
+      }
+      if (matchesKey(data, "-") || matchesKey(data, "_")) {
+        state.height = Math.max(MIN_PANEL_HEIGHT, state.height - 5);
+        return { type: "none" };
+      }
+      if (matchesKey(data, "d") && state.mode !== "select" && state.file.gitStatus && !isUntrackedStatus(state.file.gitStatus)) {
+        state.diffMode = !state.diffMode;
+        state.lastRenderWidth = 0;
+        state.scroll = 0;
+        return { type: "none" };
+      }
+      if (matchesKey(data, "v") && state.mode !== "select") {
+        state.mode = "select";
+        state.selectStart = state.scroll;
+        state.selectEnd = state.scroll;
+        return { type: "none" };
+      }
+      if (matchesKey(data, "c") && state.mode === "select") {
+        state.mode = "comment";
+        state.commentText = "";
+        return { type: "none" };
+      }
+      if (matchesKey(data, "]") && state.mode !== "select") {
+        return { type: "navigate", direction: 1 };
+      }
+      if (matchesKey(data, "[") && state.mode !== "select") {
+        return { type: "navigate", direction: -1 };
+      }
+
+      return { type: "none" };
+    },
+  };
+}

package/import-cc-codex/research/import-chats-from-other-agents.md

@@ -0,0 +1,135 @@
+# Importing Claude Code + Codex conversations into Pi — findings
+
+## Pi session format and storage
+
+- **Location:** `~/.pi/agent/sessions/--<cwd>--/<timestamp>_<uuid>.jsonl` (cwd is encoded by replacing `/` with `-`).
+- **Format:** JSONL with a header line (`type: "session"`, `version: 3`, `id`, `timestamp`, `cwd`, optional `parentSession`).
+- **Entries:** Each entry is a `SessionEntry` with `id`, `parentId`, `timestamp`. Messages are stored as:
+  - `user` message with `content` (string or `[{type:"text"|"image", ...}]`) and `timestamp` (ms).
+  - `assistant` message with `api`, `provider`, `model`, `usage`, `stopReason`, `content` blocks (`text`, `thinking`, `toolCall`).
+  - `toolResult` messages with `toolCallId`, `toolName`, `content` blocks (`text`/`image`), `isError`.
+- **Tree structure:** Each entry has `parentId`; linear sessions use previous entry ID. `/tree` works off this structure.
+- **Session display name:** `session_info` entries set a display name shown in `/resume`.
+
+## Usage accounting (import shouldn’t count)
+
+- `/session` and footer usage totals sum **all assistant message usage** in the session entries (not just post-compaction).
+- Context % in the footer is computed from **the last assistant message’s usage** (input + output + cache read/write).
+- There is **no built‑in “imported” flag** on messages or entries; to exclude imports you’d need to:
+  - Set imported assistant `usage` to zero **and** accept that context % will show 0 until a new assistant message arrives, **or**
+  - Add a new marker (e.g., `custom` entry or message field) and update footer + stats code to skip imported entries.
+
+## Claude Code transcripts (local)
+
+- **User history only:** `~/.claude/history.jsonl` (user commands/prompts; no assistant output).
+- **Full transcripts:** `~/.claude/projects/<project>/<session>.jsonl`.
+  - Lines include `type: "user"` and `type: "assistant"` entries with `message` objects plus metadata (`cwd`, `sessionId`, `timestamp`, etc.).
+  - Assistant `message.content` can include blocks: `text`, `thinking`, `tool_use` (id, name, input).
+  - Tool results show up as **user entries** whose `message.content` contains `tool_result` blocks (with `tool_use_id` and `content`).
+  - Other line types include `summary` and `file-history-snapshot` (can be ignored for a v0 importer).
+
+## Codex transcripts (local)
+
+- **User history only:** `~/.codex/history.jsonl` (session_id, ts, text; no assistant output).
+- **Full transcripts:** `~/.codex/sessions/YYYY/MM/DD/*.jsonl`.
+  - Lines are event records: `{ timestamp, type, payload }`.
+  - `type: "response_item"` with `payload.type: "message"` contains `role: "user"|"assistant"` and content blocks (`input_text` / `output_text`).
+  - Tool calls appear as `response_item` with `payload.type: "function_call"` (name, arguments, call_id).
+  - Tool outputs appear as `response_item` with `payload.type: "function_call_output"` (call_id, output JSON).
+  - Many other record types (`event_msg`, `turn_context`, `reasoning`) can be ignored for basic import.
+
+## Mapping notes for a v0 importer
+
+- **Create a Pi session JSONL** with a valid header (`version: 3`) and a linear chain of `message` entries.
+- **User messages** map directly from CC `message.role == "user"` and Codex `payload.role == "user"`.
+- **Assistant messages** need Pi’s required fields (`api`, `provider`, `model`, `usage`, `stopReason`, `timestamp`).
+  - CC provides model + usage in the assistant `message` payload; Codex logs do **not** provide usage tokens, so you’d likely set them to 0 (unless you add a heuristic).
+- **Tool calls/results:**
+  - CC: convert `tool_use` blocks → Pi `toolCall` blocks; convert `tool_result` blocks → Pi `toolResult` messages. Tool name may need to be looked up via the matching `tool_use_id`.
+  - Codex: map `function_call` → Pi `toolCall`; `function_call_output` → Pi `toolResult`.
+- **Make imports obvious:**
+  - Add a `session_info` entry like `"Imported from Claude Code"` / `"Imported from Codex"` for `/resume` visibility.
+  - Optionally add a `custom` entry (non‑LLM) to store source metadata (file path, original session ID, original tool/event IDs).
+- **Resume + share support:** as long as the file is a valid Pi session JSONL in `~/.pi/agent/sessions`, `/resume`, `/tree`, `/export`, and `/share` should work without special casing.
+
+## Open gaps to resolve if we implement
+
+- **Imported usage vs. context %**: if imported assistant usage is zero, the footer’s context % will be 0 until a new assistant response is produced.
+- **Missing tool names in CC `tool_result` blocks**: may need to build a `tool_use_id → name` index while parsing.
+- **Model restoration warnings**: if the imported `provider/model` aren’t available locally, Pi will log a restore warning and fall back to the configured default model.
+
+## Spec (draft)
+
+### Goals
+- Import a Claude Code or Codex transcript into a valid Pi session JSONL.
+- Clearly mark imported content as imported in UI and on disk.
+- Exclude imported turns from usage totals; subsequent turns should count normally.
+- V0: after import, allow immediate continuation in Pi (new message appends to the imported session).
+- Later: imported sessions should work with `/resume`, `/tree`, `/export`, `/share` without special cases.
+
+### Non-goals
+- Reconstructing exact token usage for Codex transcripts.
+- Replaying tool execution or restoring filesystem state.
+- Guaranteeing identical model/behavior across agents.
+
+### Inputs
+- Claude Code transcript: `~/.claude/projects/<project>/<session>.jsonl`.
+- Codex transcript: `~/.codex/sessions/YYYY/MM/DD/*.jsonl`.
+- Optional user-only histories (`~/.claude/history.jsonl`, `~/.codex/history.jsonl`) are out of scope for v0.
+
+### Output
+- A Pi session JSONL file in `~/.pi/agent/sessions/--<cwd>--/` with version `3` header.
+- A `session_info` entry naming the source (e.g., "Imported from Claude Code").
+- A `custom` entry with import metadata:
+  - `customType: "import"`
+  - `data`: `{ source, sourcePath, sourceSessionId, importedAt, originalCwd, originalModel? }`.
+
+### Message mapping
+- **User**: map to Pi `message` entries with `role: "user"` and text/image content.
+- **Assistant**: map to Pi `message` entries with `role: "assistant"` and content blocks.
+  - Codex: `usage` defaults to zeros unless we add a heuristic.
+  - Claude Code: use `usage`, `provider`, `model` from transcript.
+- **Thinking**: import as `thinking` blocks but hide by default in UI or mark as imported.
+- **Tools**:
+  - CC `tool_use` → Pi `toolCall` blocks.
+  - CC `tool_result` → Pi `toolResult` messages (resolve `tool_use_id → name`; fallback to `unknown:<short-id>`).
+  - Codex `function_call` → Pi `toolCall` blocks.
+  - Codex `function_call_output` → Pi `toolResult` messages (store raw output text; optional JSON parse with raw preserved).
+- **Summaries**: CC `summary` → `custom_message` with a visible "Imported summary" label.
+- **Environment context** (Codex): store as `custom` metadata or drop; do not render as user messages.
+- **Aborted assistant messages**: keep only if they contain tool calls or non-empty content; otherwise drop.
+- **Missing images**: replace with a text placeholder like `[Image missing: <path>]`.
+
+### Usage + context accounting
+- Usage totals (`/session`, footer totals) should ignore imported assistant usage.
+- Context % should avoid showing 0% on import; use a deterministic estimate across imported messages until a new assistant response arrives.
+- Imported usage must not be billed or counted against the user’s usage metrics.
+- Track imported range in a `custom` entry (e.g., `{ importedUpToEntryId, importedEntryIds? }`) rather than per-entry schema changes.
+
+### UX expectations
+- **Phase 1 (testing)**: `pi --import <path>` with optional `--source claude|codex` (auto-detect if omitted). No picker in v0; this is for developer testing.
+- **Phase 2**: add `/import` in-session command that mirrors `/resume` UX (cwd/all toggle, lazy loading, same performance profile).
+- **Picker flow** (Phase 2+): selector of recent CC/Codex sessions with preview (first user message + summary text + timestamp), type-to-filter, and optional `--query` CLI flag for direct search using the same fields as `/resume`.
+- **Source labeling**: mirror `/resume` list UI/formatting/columns as baseline; add a clear Claude/Codex indicator (badge/prefix) in the list and in session name.
+- **Post-import**: immediately open the imported session with a status banner (e.g., "Imported from Claude Code — usage excluded").
+- Continuing the chat is seamless: the next user prompt appends to the imported session.
+- `/resume` lists imported sessions alongside normal sessions.
+
+### Error handling
+- Invalid transcript files should fail fast with actionable error messages.
+- Missing model/provider should fall back gracefully; record fallback in import metadata (not as a model change).
+- If tool result mapping fails, import should still proceed with a placeholder tool name.
+- Default to redacting obvious secrets in tool outputs (tokens/keys/Authorization), with an opt-out flag.
+
+### Ordering + timestamps
+- Preserve original timestamps for provenance.
+- If timestamps are identical or go backwards, adjust stored timestamps minimally (e.g., +1ms) while keeping originals in import metadata to preserve UI order.
+
+### Session placement
+- Store the imported session under the current Pi project’s session directory for `/resume` usability.
+- Preserve original `cwd` in import metadata and surface it in the session display name.
+
+### Source scope
+- V0: one source per session (no CC+Codex merge).
+- No read-only mode; `/tree` is available immediately.
+- Idempotent import is optional via a flag (default is always create a new session).

package/import-cc-codex/spec.md

@@ -0,0 +1,79 @@
+# Import Claude Code + Codex Sessions into Pi — Spec
+
+## Overview
+We will add an import pipeline that converts Claude Code and Codex transcripts into Pi session JSONL files. Imported sessions must be clearly labeled, excluded from usage totals, and behave like normal Pi sessions (continuable, resumable, tree‑navigable).
+
+## Goals
+- Import Claude Code or Codex transcripts into valid Pi session JSONL (v3).
+- Mark imported content clearly in UI and on disk.
+- Exclude imported turns from usage totals; subsequent turns count normally.
+- Phase 1: `pi --import <path>` for developer testing.
+- Phase 2: `/import` in-session flow mirroring `/resume` UX.
+
+## Non-goals
+- Perfect token reconstruction for Codex transcripts.
+- Replaying tool execution or restoring filesystem state.
+- Guaranteeing identical model behavior across agents.
+
+## Phases
+
+### Phase 1 (CLI path import)
+- CLI: `pi --import <path>` with optional `--source claude|codex` (auto-detect if omitted).
+- Output session saved under current Pi project sessions directory.
+- Immediately open imported session with a banner (e.g., “Imported from Codex — usage excluded”).
+
+### Phase 2 (interactive import)
+- `/import` command in-session.
+- Picker mirrors `/resume` UI/format/columns, with cwd/all toggle and lazy loading.
+- Search uses the same fields as `/resume`: first user message + summary text + timestamp.
+- Clear source indicator (Claude/Codex badge/prefix) in list and session name.
+
+## Data mapping
+
+### Session header
+- `type: "session"`, `version: 3`, new UUID, `timestamp` from first entry.
+- Preserve original `cwd` in import metadata; store session under current cwd for usability.
+
+### Messages
+- **User**: map to Pi `role: "user"` with text/image content.
+- **Assistant**: map to Pi `role: "assistant"` with text/thinking/toolCall blocks.
+  - Claude Code: use provider/model/usage from transcript.
+  - Codex: set usage to zero (optional heuristic later).
+- **Thinking**: import, but mark/hide as imported in UI.
+- **Tools**:
+  - CC `tool_use` → Pi `toolCall`.
+  - CC `tool_result` → Pi `toolResult`, resolve tool name; fallback `unknown:<short-id>`.
+  - Codex `function_call` → Pi `toolCall`.
+  - Codex `function_call_output` → Pi `toolResult` with raw text; optional JSON parse while preserving raw.
+- **Summaries**: CC `summary` → `custom_message` labeled “Imported summary”.
+- **Environment context** (Codex): store in `custom` metadata or drop; never show as a user message.
+- **Aborted assistant messages**: keep only if non-empty or include tool calls.
+- **Missing images**: replace with `[Image missing: <path>]` text block.
+
+### Import metadata
+- Append a `custom` entry: `customType: "import"` with `{ source, sourcePath, sourceSessionId, importedAt, originalCwd, originalModel?, originalTimestamps? }`.
+- Track imported range in metadata (e.g., `importedUpToEntryId` or `importedEntryIds`).
+
+## Usage + context accounting
+- Imported assistant usage does **not** count toward totals.
+- Context % uses deterministic estimate over imported messages until a new assistant response arrives.
+- Imported usage never billed.
+
+## Ordering + timestamps
+- Preserve original timestamps.
+- If timestamps collide/go backward, adjust minimally (e.g., +1ms) to preserve UI order while storing originals in metadata.
+
+## UX + labeling
+- Imported sessions show a clear source indicator in list and session name.
+- `/resume` lists imported sessions alongside normal sessions.
+- No read‑only state: `/tree` works immediately.
+
+## Error handling
+- Fail fast with actionable errors for invalid transcript files.
+- Missing model/provider falls back gracefully; record fallback in import metadata.
+- Tool mapping failures proceed with placeholder tool name.
+- Redact obvious secrets in tool outputs by default (tokens/keys/Authorization), with an opt‑out flag.
+
+## Scope constraints
+- One source per session (no CC+Codex merge) in v0.
+- Idempotent imports optional via flag; default is always create new session.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pi-extensions",
+  "version": "0.1.9",
+  "private": false,
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./agent-guidance/agent-guidance.ts",
+      "./arcade/spice-invaders.ts",
+      "./arcade/picman.ts",
+      "./arcade/ping.ts",
+      "./arcade/tetris.ts",
+      "./arcade/mario-not/mario-not.ts",
+      "./code-actions/index.ts",
+      "./files-widget/index.ts",
+      "./raw-paste/index.ts",
+      "./ralph-wiggum/index.ts",
+      "./relaunch/index.ts",
+      "./tab-status/tab-status.ts",
+      "./usage-extension/index.ts",
+      "./ready-status/ready-status.ts"
+    ],
+    "skills": [
+      "./ralph-wiggum/SKILL.md"
+    ]
+  }
+}

package/ralph-wiggum/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.1 - 2026-01-25
+- Clarified that agents must write the task file themselves (tool does not auto-create it).
+
+## 0.1.0 - 2026-01-13
+- Initial release.