pi-remote-control 1.0.0

package/tests/session-index.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { projectIdForPath } from "../src/session-index.js";
+
+describe("session identifiers", () => {
+  it("creates stable project ids from paths", () => {
+    expect(projectIdForPath("/repo/example")).toBe(projectIdForPath("/repo/example"));
+    expect(projectIdForPath("/repo/example")).toMatch(/^proj_[0-9a-f]{16}$/);
+    expect(projectIdForPath("/repo/example")).not.toBe(projectIdForPath("/repo/other"));
+  });
+});

package/tests/session-transcript.test.ts

@@ -0,0 +1,75 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { readSessionTranscriptMessages } from "../src/session-transcript.js";
+
+let root: string;
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), "pi-remote-control-transcript-"));
+});
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true });
+});
+
+describe("session transcript files", () => {
+  it("reads message entries from Pi JSONL session files", async () => {
+    const sessionFile = join(root, "session.jsonl");
+    await writeFile(sessionFile, [
+      JSON.stringify({ type: "message", id: "msg_1", timestamp: "2026-05-09T00:00:01.000Z", message: { role: "user", content: "hello" } }),
+      JSON.stringify({ type: "tool_execution_start", toolCallId: "call_1" }),
+      JSON.stringify({ type: "message", id: "msg_2", timestamp: "2026-05-09T00:00:02.000Z", message: { role: "assistant", content: [{ type: "text", text: "hi" }] } }),
+      "not-json",
+      "",
+    ].join("\n"));
+
+    expect(readSessionTranscriptMessages(sessionFile)).toEqual([
+      { id: "msg_1", role: "user", content: [{ type: "text", text: "hello" }], text: "hello", createdAt: "2026-05-09T00:00:01.000Z", isStreaming: false },
+      { id: "msg_2", role: "assistant", content: [{ type: "text", text: "hi" }], text: "hi", createdAt: "2026-05-09T00:00:02.000Z", isStreaming: false },
+    ]);
+  });
+
+  it("preserves thinking, tool calls, and tool result metadata", async () => {
+    const sessionFile = join(root, "structured-session.jsonl");
+    await writeFile(sessionFile, [
+      JSON.stringify({ type: "message", id: "msg_1", timestamp: "2026-05-09T00:00:01.000Z", message: { role: "assistant", content: [
+        { type: "thinking", thinking: "checking" },
+        { type: "toolCall", id: "call_1", name: "bash", arguments: { command: "ls" } },
+        { type: "text", text: "done" },
+      ] } }),
+      JSON.stringify({ type: "message", id: "msg_2", timestamp: "2026-05-09T00:00:02.000Z", message: { role: "toolResult", toolCallId: "call_1", toolName: "bash", isError: false, content: [{ type: "text", text: "file.txt" }] } }),
+    ].join("\n"));
+
+    expect(readSessionTranscriptMessages(sessionFile)).toEqual([
+      {
+        id: "msg_1",
+        role: "assistant",
+        content: [
+          { type: "thinking", thinking: "checking" },
+          { type: "toolCall", id: "call_1", name: "bash", arguments: { command: "ls" } },
+          { type: "text", text: "done" },
+        ],
+        text: "done",
+        createdAt: "2026-05-09T00:00:01.000Z",
+        isStreaming: false,
+      },
+      {
+        id: "msg_2",
+        role: "toolResult",
+        content: [{ type: "text", text: "file.txt" }],
+        text: "file.txt",
+        createdAt: "2026-05-09T00:00:02.000Z",
+        toolCallId: "call_1",
+        toolName: "bash",
+        isError: false,
+        isStreaming: false,
+      },
+    ]);
+  });
+
+  it("returns an empty transcript when the session file is missing", () => {
+    expect(readSessionTranscriptMessages(join(root, "missing.jsonl"))).toEqual([]);
+  });
+});

package/tests/transcript-pagination.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import type { TranscriptMessage } from "../src/types.js";
+import { decodeTranscriptCursor, encodeTranscriptCursor, olderTranscriptPage, recentTranscriptWindow } from "../src/transcript-pagination.js";
+
+function message(id: string, createdAt: string): TranscriptMessage {
+  return { id, role: "user", content: [{ type: "text", text: id }], text: id, createdAt, isStreaming: false };
+}
+
+describe("transcript pagination", () => {
+  const messages = [
+    message("msg_1", "2026-05-09T00:00:01.000Z"),
+    message("msg_2", "2026-05-09T00:00:02.000Z"),
+    message("msg_2", "2026-05-09T00:00:02.000Z"),
+    message("msg_3", "2026-05-09T00:00:03.000Z"),
+    message("msg_4", "2026-05-09T00:00:04.000Z"),
+    message("msg_5", "2026-05-09T00:00:05.000Z"),
+  ];
+
+  it("returns a bounded recent window with a timestamp-only older cursor", () => {
+    const page = recentTranscriptWindow(messages, 2);
+
+    expect(page.messages.map((item) => item.id)).toEqual(["msg_4", "msg_5"]);
+    expect(page.hasOlderMessages).toBe(true);
+    expect(decodeTranscriptCursor(page.olderMessagesCursor ?? "")).toBe("2026-05-09T00:00:04.000Z");
+  });
+
+  it("returns older pages before an exclusive timestamp cursor", () => {
+    const first = recentTranscriptWindow(messages, 2);
+    const older = olderTranscriptPage(messages, first.olderMessagesCursor ?? "", 2);
+    const oldest = olderTranscriptPage(messages, older.olderMessagesCursor ?? "", 2);
+
+    expect(older.messages.map((item) => item.id)).toEqual(["msg_2", "msg_3"]);
+    expect(older.hasOlderMessages).toBe(true);
+    expect(decodeTranscriptCursor(older.olderMessagesCursor ?? "")).toBe("2026-05-09T00:00:02.000Z");
+    expect(oldest.messages.map((item) => item.id)).toEqual(["msg_1"]);
+    expect(oldest.hasOlderMessages).toBe(false);
+    expect(oldest.olderMessagesCursor).toBeNull();
+  });
+
+  it("rejects malformed cursors", () => {
+    expect(() => olderTranscriptPage(messages, "not-a-cursor", 2)).toThrow("invalid_cursor");
+  });
+
+  it("rejects timestamp cursors that do not match the transcript", () => {
+    expect(() => olderTranscriptPage(messages, encodeTranscriptCursor("2026-05-09T00:00:30.000Z"), 2)).toThrow("invalid_cursor");
+  });
+
+  it("encodes cursors without message ids", () => {
+    const cursor = encodeTranscriptCursor("2026-05-09T00:00:04.000Z");
+
+    expect(decodeTranscriptCursor(cursor)).toBe("2026-05-09T00:00:04.000Z");
+    expect(Buffer.from(cursor, "base64url").toString("utf8")).toBe("2026-05-09T00:00:04.000Z");
+  });
+});

package/tests/transcript-preview.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { INITIAL_WEBSOCKET_SESSION_MESSAGE_LIMIT, INITIAL_WEBSOCKET_STRING_PREVIEW_BYTES, previewInitialSessionState } from "../src/transcript-preview.js";
+import type { TranscriptMessage } from "../src/types.js";
+
+function message(id: string, text = id): TranscriptMessage {
+  return {
+    id,
+    role: "assistant",
+    content: [{ type: "text", text }],
+    text,
+    createdAt: `2026-05-09T00:00:${id.padStart(2, "0")}.000Z`,
+    isStreaming: false,
+  };
+}
+
+describe("initial WebSocket session state preview", () => {
+  it("keeps at most the newest 20 messages", () => {
+    const state = { messages: Array.from({ length: 25 }, (_, index) => message(String(index + 1))) };
+
+    expect(previewInitialSessionState(state).messages.map((item) => item.id)).toEqual(
+      Array.from({ length: INITIAL_WEBSOCKET_SESSION_MESSAGE_LIMIT }, (_, index) => String(index + 6)),
+    );
+  });
+
+  it("truncates oversized transcript message strings to the first 10 KiB", () => {
+    const oversized = "a".repeat(INITIAL_WEBSOCKET_STRING_PREVIEW_BYTES + 5);
+    const state = { messages: [{ ...message("1", oversized), content: [{ type: "text", text: oversized }, { type: "thinking", thinking: oversized }] }] };
+
+    expect(previewInitialSessionState(state).messages[0]).toEqual({
+      id: "1",
+      role: "assistant",
+      content: [
+        { type: "text", text: "a".repeat(INITIAL_WEBSOCKET_STRING_PREVIEW_BYTES), truncated: true, originalBytes: INITIAL_WEBSOCKET_STRING_PREVIEW_BYTES + 5 },
+        { type: "thinking", thinking: "a".repeat(INITIAL_WEBSOCKET_STRING_PREVIEW_BYTES), truncated: true, originalBytes: INITIAL_WEBSOCKET_STRING_PREVIEW_BYTES + 5 },
+      ],
+      text: "a".repeat(INITIAL_WEBSOCKET_STRING_PREVIEW_BYTES),
+      textTruncated: true,
+      textOriginalBytes: INITIAL_WEBSOCKET_STRING_PREVIEW_BYTES + 5,
+      createdAt: "2026-05-09T00:00:01.000Z",
+      isStreaming: false,
+    });
+  });
+
+  it("truncates oversized tool call argument strings and marks argument previews", () => {
+    const oversized = "x".repeat(INITIAL_WEBSOCKET_STRING_PREVIEW_BYTES + 1);
+    const state = {
+      messages: [{
+        ...message("1", ""),
+        content: [{ type: "toolCall", id: "call_1", name: "write", arguments: { path: "file.ts", content: oversized } }],
+      }],
+    };
+
+    const result = previewInitialSessionState(state).messages[0]?.content[0];
+
+    expect(result).toEqual({
+      type: "toolCall",
+      id: "call_1",
+      name: "write",
+      arguments: { path: "file.ts", content: "x".repeat(INITIAL_WEBSOCKET_STRING_PREVIEW_BYTES) },
+      argumentsTruncated: true,
+      argumentsOriginalBytes: Buffer.byteLength(JSON.stringify({ path: "file.ts", content: oversized }), "utf8"),
+    });
+  });
+});

package/tests/transcript-stream.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+import { normalizeTuiEvent } from "../src/transcript-stream.js";
+
+describe("TUI event transcript stream normalization", () => {
+  it("normalizes message lifecycle events to transcript message events", () => {
+    expect(normalizeTuiEvent({
+      type: "message_start",
+      message: { id: "msg_1", role: "assistant", timestamp: 1778284801000, content: [] },
+    })).toEqual([{
+      type: "transcript_message_start",
+      message: {
+        id: "msg_1",
+        role: "assistant",
+        content: [],
+        text: "",
+        createdAt: "2026-05-09T00:00:01.000Z",
+        isStreaming: true,
+      },
+    }]);
+
+    expect(normalizeTuiEvent({
+      type: "message_end",
+      message: { id: "msg_1", role: "assistant", timestamp: 1778284802000, content: [{ type: "text", text: "done" }] },
+    })).toEqual([{
+      type: "transcript_message_end",
+      message: {
+        id: "msg_1",
+        role: "assistant",
+        content: [{ type: "text", text: "done" }],
+        text: "done",
+        createdAt: "2026-05-09T00:00:02.000Z",
+        isStreaming: false,
+      },
+    }]);
+  });
+
+  it("does not emit message_start for non-streaming user messages", () => {
+    expect(normalizeTuiEvent({
+      type: "message_start",
+      message: { id: "msg_user_1", role: "user", timestamp: 1778284801000, content: "hello" },
+    })).toEqual([]);
+
+    expect(normalizeTuiEvent({
+      type: "message_end",
+      message: { id: "msg_user_1", role: "user", timestamp: 1778284801000, content: "hello" },
+    })).toEqual([{
+      type: "transcript_message_end",
+      message: {
+        id: "msg_user_1",
+        role: "user",
+        content: [{ type: "text", text: "hello" }],
+        text: "hello",
+        createdAt: "2026-05-09T00:00:01.000Z",
+        isStreaming: false,
+      },
+    }]);
+  });
+
+  it("normalizes assistant message deltas to transcript message patches", () => {
+    expect(normalizeTuiEvent({
+      type: "message_update",
+      message: { id: "msg_1", role: "assistant" },
+      assistantMessageEvent: { type: "thinking_delta", contentIndex: 0, delta: "checking" },
+    })).toEqual([{ type: "transcript_message_patch", messageId: "msg_1", contentIndex: 0, patch: { type: "thinking_delta", delta: "checking" } }]);
+
+    expect(normalizeTuiEvent({
+      type: "message_update",
+      message: { id: "msg_1", role: "assistant" },
+      assistantMessageEvent: { type: "text_delta", contentIndex: 1, delta: "hello" },
+    })).toEqual([{ type: "transcript_message_patch", messageId: "msg_1", contentIndex: 1, patch: { type: "text_delta", delta: "hello" } }]);
+
+    expect(normalizeTuiEvent({
+      type: "message_update",
+      message: { id: "msg_1", role: "assistant" },
+      assistantMessageEvent: { type: "toolcall_end", contentIndex: 2, toolCall: { type: "toolCall", id: "call_1", name: "bash", arguments: { command: "ls" } } },
+    })).toEqual([{ type: "transcript_message_patch", messageId: "msg_1", contentIndex: 2, patch: { type: "toolCall", toolCall: { type: "toolCall", id: "call_1", name: "bash", arguments: { command: "ls" } } } }]);
+  });
+
+  it("normalizes turn lifecycle events", () => {
+    expect(normalizeTuiEvent({ type: "turn_start", turnIndex: 2, timestamp: 1778284801000 })).toEqual([
+      { type: "turn_start", turnIndex: 2, createdAt: "2026-05-09T00:00:01.000Z" },
+    ]);
+    expect(normalizeTuiEvent({ type: "turn_end", turnIndex: 2, message: { role: "assistant", content: [] }, toolResults: [] })).toEqual([
+      { type: "turn_end", turnIndex: 2 },
+    ]);
+  });
+
+  it("normalizes tool execution events", () => {
+    expect(normalizeTuiEvent({ type: "tool_execution_start", toolCallId: "call_1", toolName: "bash", args: { command: "ls" } })).toEqual([
+      { type: "tool_execution_start", toolCallId: "call_1", toolName: "bash", args: { command: "ls" } },
+    ]);
+    expect(normalizeTuiEvent({ type: "tool_execution_update", toolCallId: "call_1", toolName: "bash", partialResult: { content: [] } })).toEqual([
+      { type: "tool_execution_update", toolCallId: "call_1", toolName: "bash", partialResult: { content: [] } },
+    ]);
+    expect(normalizeTuiEvent({ type: "tool_execution_end", toolCallId: "call_1", toolName: "bash", result: { content: [] }, isError: false })).toEqual([
+      { type: "tool_execution_end", toolCallId: "call_1", toolName: "bash", result: { content: [] }, isError: false },
+    ]);
+  });
+
+  it("ignores events without public stream representation", () => {
+    expect(normalizeTuiEvent({ type: "agent_start" })).toEqual([]);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules", "tests"]
+}