pi-remote-control 1.0.0 → 1.0.1

package/docs/adr/0024-count-public-transcript-messages.md

@@ -0,0 +1,31 @@
+# Count visible conversation messages
+
+## Title
+
+Count visible conversation messages
+
+## Status
+
+Accepted
+
+## Context
+
+The iOS app displays the `messageCount` field returned by project-session and session-state APIs as a user-facing conversation message count. The current daemon value can come from the TUI registration payload, where it is based on Pi session entries. Pi session entries include internal/tool/system records that are not one-to-one with the public transcript messages shown in the app conversation page.
+
+This causes the session list count to be noticeably larger than the message count users infer from the conversation page. The iOS app does not use `messageCount` for pagination, cursors, synchronization, or raw Pi-entry accounting.
+
+## Decision
+
+Change the daemon-owned public meaning of `messageCount` to the count of visible conversation messages derived from the session's Pi JSONL `sessionFile`.
+
+A visible conversation message is a top-level public transcript message with role `user` or `assistant`. Assistant thinking and tool-use blocks are content within an assistant message and do not increment the count separately. Top-level `toolResult`, `system`, internal tool execution, lifecycle, and other non-conversation records are excluded.
+
+For active TUI sessions, the daemon treats `messageCount` in TUI registration as an initial hint only. Public session summaries and session-state responses use the daemon-computed visible conversation count when the session file is readable.
+
+## Consequences
+
+The session list count matches the app's conversation-page message model instead of raw Pi session-entry counts or tool/system activity counts.
+
+Changing `messageCount` semantics is acceptable because the app only uses it for display. Clients that need raw Pi entry counts should use a separate future field rather than overloading `messageCount`.
+
+Computing the count may require reading the session file when building session summaries. Active remote-control session counts are expected to be small enough for this to be acceptable; if needed, the daemon can cache the computed count while preserving the public semantics.

package/docs/adr/0025-count-assistant-tool-use-messages.md

@@ -0,0 +1,29 @@
+# Count assistant tool-use messages
+
+## Title
+
+Count assistant tool-use messages
+
+## Status
+
+Accepted
+
+## Context
+
+ADR 0024 narrowed `messageCount` from raw Pi session-entry count toward the app's conversation display. A real session showed `messageCount` of 79, composed of 6 user messages plus 73 assistant messages. Of those assistant messages, 67 had `stopReason: "toolUse"` and represented assistant tool-call steps; excluding them would produce 12 messages.
+
+The iOS app also shows tool-call activity and can display tool-call details, so counting assistant tool-use messages in the session-list count is acceptable.
+
+## Decision
+
+Keep `messageCount` as the count of top-level public transcript messages whose role is `user` or `assistant`, including assistant messages whose `stopReason` is `"toolUse"`.
+
+Do not count top-level `toolResult`, `system`, tool execution, lifecycle, or other non-message records. Tool-call details remain associated with assistant/tool events in the transcript UI.
+
+This ADR supersedes ADR 0024 only for whether assistant tool-use messages are included.
+
+## Consequences
+
+The session-list count can be larger than a manually counted user/final-answer exchange count because assistant tool-use steps are included.
+
+The count remains useful as an activity-oriented transcript message count and aligns with the app's ability to display tool-call details.

package/docs/data-model.md

@@ -140,7 +140,7 @@ type ActiveTuiSession = {
 };
 ```
 
-An active TUI session is owned by one Pi extension control channel. It is removed when `/remote-control` disables it, the TUI session shuts down, or the control channel closes. If the daemon removes it because heartbeats stopped but the same TUI process still has local remote-control state active, the TUI extension can recreate the active session by re-registering on the next heartbeat miss. Its `sessionFile` points to the Pi JSONL transcript used for HTTP transcript reads. Its `runtimeStatus` is the latest structured runtime-status snapshot reported by the owning TUI extension.
+An active TUI session is owned by one Pi extension control channel. It is removed when `/remote-control` disables it, the TUI session shuts down, or the control channel closes. If the daemon removes it because heartbeats stopped but the same TUI process still has local remote-control state active, the TUI extension can recreate the active session by re-registering on the next heartbeat miss. Its `sessionFile` points to the Pi JSONL transcript used for HTTP transcript reads. Its `runtimeStatus` is the latest structured runtime-status snapshot reported by the owning TUI extension. Public `messageCount` values are daemon-computed counts of top-level `user` and `assistant` transcript messages. Assistant messages whose `stopReason` is `"toolUse"` are included because they represent visible tool-call activity in the app. Thinking and tool-use blocks count as part of their containing assistant message, not as separate messages; top-level `toolResult`, `system`, tool execution, lifecycle, and other non-message records are excluded.
 
 ## Runtime status
 

package/docs/interfaces.md

@@ -89,11 +89,13 @@ Response:
 }
 ```
 
+`messageCount` is the daemon-computed count of top-level `user` and `assistant` transcript messages derived from the session file. Assistant messages whose `stopReason` is `"toolUse"` are included, because the app can show tool-call activity and details. Assistant thinking and tool-use blocks are content within an assistant message and do not increment the count separately. Top-level `toolResult`, `system`, internal tool execution, lifecycle, and other non-message records are excluded.
+
 `POST /v1/projects/{projectId}/sessions` returns `405 method_not_allowed`. New sessions are created in the Pi TUI, then made visible by running `/remote-control`.
 
 `GET /v1/sessions/{sessionId}?messageLimit={limit}`
 
-Returns the daemon's current state for an active remote-control TUI session with a bounded recent transcript window read from the session's Pi JSONL `sessionFile`. If `messageLimit` is absent, the daemon uses its default recent-message limit. The daemon enforces a maximum page size. Invalid non-positive limits return `400` with `invalid_limit`.
+Returns the daemon's current state for an active remote-control TUI session with a bounded recent transcript window read from the session's Pi JSONL `sessionFile`. `session.messageCount` uses the transcript message count semantics described above. If `messageLimit` is absent, the daemon uses its default recent-message limit. The daemon enforces a maximum page size. Invalid non-positive limits return `400` with `invalid_limit`.
 
 Response:
 
@@ -406,7 +408,7 @@ Response payload:
 
 ### Session registration
 
-When `/remote-control` enables a session, the extension registers the current TUI session:
+When `/remote-control` enables a session, the extension registers the current TUI session. The registration `messageCount` is an initial hint from the TUI; public HTTP responses use daemon-computed transcript message counts from `sessionFile` when available:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-remote-control",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Authenticated remote control for Pi sessions.",
   "keywords": ["pi-package"],

package/src/active-session-registry.ts

@@ -1,4 +1,5 @@
-import { readSessionTranscriptMessages } from "./session-transcript.js";
+import { existsSync } from "node:fs";
+import { readSessionTranscriptMessages, visibleConversationMessageCount } from "./session-transcript.js";
 import { DEFAULT_TRANSCRIPT_PAGE_LIMIT, olderTranscriptPage, recentTranscriptWindow, type TranscriptPage } from "./transcript-pagination.js";
 import type { RuntimeStatus, ToolCallStatus } from "./types.js";
 
@@ -133,7 +134,7 @@ export function createActiveSessionRegistry(options: ActiveSessionRegistryOption
       pruneInactiveSessions();
       return [...sessions.values()]
         .filter((session) => session.project.id === projectId)
-        .map((session) => session.summary)
+        .map((session) => currentSummary(session))
         .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
     },
 
@@ -145,7 +146,7 @@ export function createActiveSessionRegistry(options: ActiveSessionRegistryOption
       return {
         session: {
           ...session.summary,
-          messageCount: messages.length,
+          messageCount: sessionFileExists(session) ? visibleConversationMessageCount(messages) : session.summary.messageCount,
           updatedAt: messages.at(-1)?.createdAt ?? session.summary.updatedAt,
         },
         ...recentTranscriptWindow(messages, options?.messageLimit ?? DEFAULT_TRANSCRIPT_PAGE_LIMIT),
@@ -191,6 +192,19 @@ export function createActiveSessionRegistry(options: ActiveSessionRegistryOption
   };
 }
 
+function currentSummary(session: StoredActiveSession): ActiveSessionSummary {
+  const messages = readSessionTranscriptMessages(session.sessionFile);
+  return {
+    ...session.summary,
+    messageCount: sessionFileExists(session) ? visibleConversationMessageCount(messages) : session.summary.messageCount,
+    updatedAt: messages.at(-1)?.createdAt ?? session.summary.updatedAt,
+  };
+}
+
+function sessionFileExists(session: Pick<ActiveSessionRegistration, "sessionFile">): boolean {
+  return session.sessionFile.length > 0 && existsSync(session.sessionFile);
+}
+
 function toSummary(session: ActiveSessionRegistration): ActiveSessionSummary {
   return {
     id: session.id,

package/src/session-transcript.ts

@@ -2,6 +2,10 @@ import { readFileSync } from "node:fs";
 import { asRecord, readString, transcriptMessageFromPiMessage } from "./transcript-message.js";
 import type { TranscriptMessage } from "./types.js";
 
+export function visibleConversationMessageCount(messages: TranscriptMessage[]): number {
+  return messages.filter((message) => message.role === "user" || message.role === "assistant").length;
+}
+
 export function readSessionTranscriptMessages(sessionFile: string): TranscriptMessage[] {
   let text: string;
   try {

package/tests/active-session-registry.test.ts

@@ -108,6 +108,35 @@ describe("active TUI session registry", () => {
     expect(registry.takeCommands("sess_1")).toEqual([]);
   });
 
+  it("uses visible conversation message counts for active session summaries", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-remote-control-registry-count-"));
+    const sessionFile = join(root, "session.jsonl");
+    const registry = createActiveSessionRegistry();
+    try {
+      await writeFile(sessionFile, [
+        JSON.stringify({ type: "message", id: "msg_1", timestamp: "2026-05-09T00:00:00.000Z", message: { role: "user", content: "hello" } }),
+        JSON.stringify({ type: "message", id: "msg_2", 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_3", timestamp: "2026-05-09T00:00:02.000Z", message: { role: "toolResult", toolCallId: "call_1", toolName: "bash", content: [{ type: "text", text: "file.txt" }] } }),
+        JSON.stringify({ type: "message", id: "msg_4", timestamp: "2026-05-09T00:00:03.000Z", message: { role: "system", content: "system" } }),
+      ].join("\n"));
+      registry.registerSession({
+        id: "sess_1",
+        piSessionId: "pi_1",
+        project: { id: "proj_1", name: "Example", path: "/repo/example" },
+        sessionFile,
+        pid: 1234,
+        messageCount: 999,
+        isStreaming: false,
+        updatedAt: "2026-05-09T00:00:00.000Z",
+      });
+
+      expect(registry.listProjectSessions("proj_1")[0]?.messageCount).toBe(2);
+      expect(registry.getSessionState("sess_1")?.session.messageCount).toBe(2);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   it("returns snapshots for active sessions", async () => {
     const root = await mkdtemp(join(tmpdir(), "pi-remote-control-registry-"));
     const sessionFile = join(root, "session.jsonl");

package/tests/session-transcript.test.ts

@@ -2,7 +2,7 @@ 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";
+import { readSessionTranscriptMessages, visibleConversationMessageCount } from "../src/session-transcript.js";
 
 let root: string;
 
@@ -69,6 +69,15 @@ describe("session transcript files", () => {
     ]);
   });
 
+  it("counts only visible user and assistant conversation messages", () => {
+    expect(visibleConversationMessageCount([
+      { 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: "thinking", thinking: "checking" }, { type: "toolCall", id: "call_1", name: "bash", arguments: { command: "ls" } }, { type: "text", text: "done" }], text: "done", createdAt: "2026-05-09T00:00:02.000Z", isStreaming: false },
+      { id: "msg_3", role: "toolResult", content: [{ type: "text", text: "file.txt" }], text: "file.txt", createdAt: "2026-05-09T00:00:03.000Z", isStreaming: false },
+      { id: "msg_4", role: "system", content: [{ type: "text", text: "system" }], text: "system", createdAt: "2026-05-09T00:00:04.000Z", isStreaming: false },
+    ])).toBe(2);
+  });
+
   it("returns an empty transcript when the session file is missing", () => {
     expect(readSessionTranscriptMessages(join(root, "missing.jsonl"))).toEqual([]);
   });