@pontia/pi-client-plugin 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pontia/pi-client-plugin",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Pi extension that connects coding-agent sessions to Pontia.",
   "keywords": [
     "pi-package",

package/src/control-socket.ts

@@ -1,3 +1,6 @@
+import { RpcError } from "./rpc-error.js";
+export { RpcError } from "./rpc-error.js";
+import { readHistory, type HistoryContext } from "./history.js";
 import { createConnection, type Socket } from "node:net";
 import { isAbsolute, join } from "node:path";
 
@@ -35,13 +38,6 @@ export interface PiConnection {
   registered(identity: ControlIdentity): void;
   close(): Promise<void>;
 }
-export class RpcError extends Error {
-  readonly code: number;
-  constructor(code: number, message: string) {
-    super(message);
-    this.code = code;
-  }
-}
 
 export function piSocketPath(pontiaHome: string): string {
   const path = join(pontiaHome, "state", "pi", "rpc.sock");
@@ -68,6 +64,7 @@ class RpcSocket {
   private onSubmit: (input: ControlInput) => void;
   private models?: ModelControl;
   private lifecycle?: LifecycleControl;
+  private history?: () => HistoryContext;
   private onReplay?: (inboxMessageId: string) => void;
 
   constructor(
@@ -76,12 +73,14 @@ class RpcSocket {
     models?: ModelControl,
     onReplay?: (inboxMessageId: string) => void,
     lifecycle?: LifecycleControl,
+    history?: () => HistoryContext,
   ) {
     this.socket = socket;
     this.onSubmit = onSubmit;
     this.models = models;
     this.onReplay = onReplay;
     this.lifecycle = lifecycle;
+    this.history = history;
     socket.on("data", (chunk: Buffer) => this.receive(chunk));
     socket.on("error", (error) => this.fail(error));
     socket.on("close", () =>
@@ -181,6 +180,17 @@ class RpcSocket {
         error(-32602, "Expected named parameters");
         return;
       }
+      if (message.method === "history.read" && this.history) {
+        try {
+          respond({ result: readHistory(this.history(), params) });
+        } catch (failure) {
+          error(
+            failure instanceof RpcError ? failure.code : -32009,
+            failure instanceof Error ? failure.message : String(failure),
+          );
+        }
+        return;
+      }
       if (message.method === "ping") {
         respond({ result: { pong: true } });
         return;
@@ -299,6 +309,7 @@ export async function connectPi(
   models?: ModelControl,
   onReplay?: (inboxMessageId: string) => void,
   lifecycle?: LifecycleControl,
+  history?: () => HistoryContext,
 ): Promise<PiConnection> {
   const path = piSocketPath(pontiaHome);
   let identity: ControlIdentity | undefined;
@@ -369,6 +380,7 @@ export async function connectPi(
       reportingOnly ? undefined : models,
       reportingOnly ? undefined : onReplay,
       reportingOnly ? undefined : lifecycle,
+      reportingOnly ? undefined : history,
     );
     peers.add(peer);
     socket.once("close", () => {

package/src/events.ts

@@ -8,7 +8,6 @@ export type InternalEventType =
   | "session.ready"
   | "session.exited"
   | "session.model_updated"
-  | "session.message_updated"
   | "session.context_usage_updated"
   | "turn.started"
   | "turn.output"
@@ -32,8 +31,6 @@ export interface ContextUsageObservation {
   model: string | null;
 }
 
-export type SessionMessageUpdatedReason = "append" | "update" | "final";
-
 export type PiTopologyEntryKind =
   | "user_message"
   | "assistant_message"
@@ -76,17 +73,6 @@ function turnFact(
   return { session_id: context.sessionId, turn_id: context.turnId, type, data };
 }
 
-export function buildSessionMessageUpdatedEvent(
-  context: TurnContext,
-  reason: SessionMessageUpdatedReason,
-): InternalEvent {
-  return {
-    session_id: context.sessionId,
-    type: "session.message_updated",
-    data: { reason },
-  };
-}
-
 export function buildSessionContextUsageUpdatedEvent(
   context: TurnContext,
   usage: ContextUsagePayload,

package/src/history.ts

@@ -0,0 +1,143 @@
+import { RpcError } from "./rpc-error.js";
+
+const PAGE_BYTES = 1024 * 1024;
+export const MAX_HISTORY_ENTRIES = 100_000;
+export interface HistoryContext {
+  generation: number;
+  sessionManager: {
+    getSessionId(): string;
+    getEntries(): unknown[];
+    getLeafId(): string | null;
+  };
+}
+interface Snapshot {
+  session_id: string;
+  generation: number;
+  entry_count: number;
+  upper_entry_id: string | null;
+  leaf_id: string | null;
+}
+const invalid = (message: string): never => {
+  throw new RpcError(-32602, message);
+};
+const token = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString("base64url");
+function decode(value: unknown): Record<string, unknown> {
+  if (typeof value !== "string" || value.length > 4096)
+    return invalid("Invalid history continuation");
+  try {
+    const parsed = JSON.parse(Buffer.from(value, "base64url").toString());
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || token(parsed) !== value)
+      return invalid("Invalid history continuation");
+    return parsed;
+  } catch {
+    return invalid("Invalid history continuation");
+  }
+}
+const identity = (value: unknown): value is string =>
+  typeof value === "string" && !!value.trim() && value.length <= 512;
+
+/** Reads the current canonical manager; tokens contain identities, never file positions. */
+export function readHistory(context: HistoryContext, params: Record<string, unknown>): object {
+  if (Object.keys(params).some((key) => !["page_size", "snapshot", "continuation"].includes(key)))
+    return invalid("Unknown history parameter");
+  const size = params.page_size === undefined ? 64 : params.page_size;
+  if (!Number.isInteger(size) || (size as number) < 1 || (size as number) > 128)
+    return invalid("Invalid history page size");
+  const manager = context.sessionManager;
+  const sessionId = manager.getSessionId();
+  if (!identity(sessionId)) return invalid("Invalid native Session identity");
+  const entries = manager.getEntries() as Record<string, unknown>[];
+  if (!Array.isArray(entries) || entries.length > MAX_HISTORY_ENTRIES)
+    return invalid("History snapshot exceeds entry limit");
+  let snapshot: Snapshot;
+  if (params.snapshot === undefined) {
+    if (params.continuation !== undefined) return invalid("Continuation requires snapshot");
+    snapshot = {
+      session_id: sessionId,
+      generation: context.generation,
+      entry_count: entries.length,
+      upper_entry_id: entries.length ? (entries[entries.length - 1].id as string) : null,
+      leaf_id: manager.getLeafId(),
+    };
+  } else {
+    const parsed = decode(params.snapshot);
+    if (
+      Object.keys(parsed).sort().join() !==
+        "entry_count,generation,leaf_id,session_id,upper_entry_id" ||
+      !Number.isInteger(parsed.entry_count) ||
+      (parsed.entry_count as number) < 0 ||
+      (parsed.entry_count as number) > MAX_HISTORY_ENTRIES ||
+      parsed.session_id !== sessionId ||
+      parsed.generation !== context.generation ||
+      !(parsed.upper_entry_id === null || identity(parsed.upper_entry_id)) ||
+      !(parsed.leaf_id === null || identity(parsed.leaf_id))
+    )
+      return invalid("History snapshot identity changed");
+    snapshot = parsed as unknown as Snapshot;
+  }
+  const upper =
+    snapshot.upper_entry_id === null
+      ? -1
+      : entries.findIndex((entry) => entry?.id === snapshot.upper_entry_id);
+  if (
+    snapshot.upper_entry_id !== null &&
+    entries.filter((entry) => entry?.id === snapshot.upper_entry_id).length !== 1
+  )
+    return invalid("Duplicate history upper identity");
+  if (snapshot.upper_entry_id !== null && upper < 0) return invalid("Invalid history upper bound");
+  if (upper + 1 !== snapshot.entry_count) return invalid("History snapshot entry count changed");
+  const ids = new Set<string>();
+  for (let index = 0; index <= upper; index++) {
+    const entry = entries[index];
+    if (
+      !entry ||
+      !identity(entry.id) ||
+      ids.has(entry.id) ||
+      !identity(entry.type) ||
+      !identity(entry.timestamp) ||
+      !(entry.parentId === null || identity(entry.parentId)) ||
+      (entry.parentId !== null && !ids.has(entry.parentId as string))
+    )
+      return invalid("Invalid history entry identity or parent");
+    ids.add(entry.id);
+  }
+  if (snapshot.leaf_id !== null && !ids.has(snapshot.leaf_id))
+    return invalid("History leaf is outside snapshot");
+  const snapshotToken = token(snapshot);
+  let start = 0;
+  if (params.continuation !== undefined) {
+    const continuation = decode(params.continuation);
+    if (
+      Object.keys(continuation).sort().join() !== "after,snapshot" ||
+      continuation.snapshot !== snapshotToken ||
+      !identity(continuation.after)
+    )
+      return invalid("Invalid history continuation");
+    const after = entries.findIndex((entry) => entry?.id === continuation.after);
+    if (after < 0 || after >= upper) return invalid("History continuation outside snapshot");
+    start = after + 1;
+  } else if (params.snapshot !== undefined) return invalid("Snapshot requires continuation");
+  const page: unknown[] = [];
+  let bytes = 0;
+  for (let index = start; index <= upper && page.length < (size as number); index++) {
+    const entry = entries[index];
+    const encoded = JSON.stringify(entry);
+    const length = Buffer.byteLength(encoded);
+    if (length > PAGE_BYTES - 8192) return invalid("History entry exceeds response budget");
+    if (bytes + length > PAGE_BYTES - 8192) break;
+    page.push(entry);
+    bytes += length + 1;
+  }
+  const end = start + page.length;
+  const continuation =
+    end <= upper ? token({ snapshot: snapshotToken, after: entries[end - 1].id }) : null;
+  return {
+    session_id: sessionId,
+    snapshot: snapshotToken,
+    entry_count: snapshot.entry_count,
+    upper_entry_id: snapshot.upper_entry_id,
+    leaf_id: snapshot.leaf_id,
+    entries: page,
+    continuation,
+  };
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { HistoryContext } from "./history.js";
 import { connectPi, RpcError, type PiConnection, type ControlInput } from "./control-socket.js";
 import { defaultHookLogFile, type EnvLike, type TurnContext } from "./context.js";
 import { appendDiagnostic, type DiagnosticEntry } from "./diagnostics.js";
@@ -7,7 +8,6 @@ import { pontiaHomeFromEnv } from "./discovery.js";
 import {
   buildSessionContextUsageUpdatedEvent,
   buildSessionExitedEvent,
-  buildSessionMessageUpdatedEvent,
   buildSessionReadyEvent,
   buildTurnCompletedEvent,
   buildTurnFailedEvent,
@@ -18,7 +18,6 @@ import {
   type InternalEvent,
   type PiTopologyContext,
   type PiTopologyEntryKind,
-  type SessionMessageUpdatedReason,
 } from "./events.js";
 import { asRecord, optionalString } from "./values.js";
 import {
@@ -37,7 +36,6 @@ import {
   assistantDeltaFromEvent,
   assistantTextFromMessage,
   errorMessageFromAgentEnd,
-  isTranscriptBoundaryMessageUpdate,
   lastAssistantTextFromMessages,
 } from "./pi-message.js";
 import { loadProfileSystemPrompt } from "./profile.js";
@@ -340,6 +338,13 @@ export function createPontiaPiExtension(
           ctx.shutdown();
         },
       },
+      () => {
+        lifecycleContext();
+        const manager = piContext!.sessionManager;
+        if (manager.getSessionId() !== boundSessionContext?.clientSessionKey)
+          throw new Error("Pi history native Session identity changed");
+        return { generation, sessionManager: manager } satisfies HistoryContext;
+      },
     );
     if (generation !== controlGeneration) {
       await socket.close();
@@ -475,21 +480,6 @@ export function createPontiaPiExtension(
     },
   });
 
-  async function scheduleMessageRefresh(reason: SessionMessageUpdatedReason): Promise<void> {
-    if (!activeTurn || activeTurn.ended) return;
-    await activeTurn.reporter.report(
-      activeTurn.context,
-      buildSessionMessageUpdatedEvent(activeTurn.context, reason),
-    );
-  }
-
-  async function reportFinalMessageRefresh(state: ActiveTurnState): Promise<void> {
-    await state.reporter.report(
-      state.context,
-      buildSessionMessageUpdatedEvent(state.context, "final"),
-    );
-  }
-
   async function reportContextUsageFromHookEvent(event: unknown, ctx?: unknown): Promise<void> {
     if (!activeTurn || activeTurn.ended) return;
     const observation = contextUsageFromPiHook(event, ctx);
@@ -836,16 +826,6 @@ export function createPontiaPiExtension(
     } else if (delta) {
       activeTurn.output += delta;
     }
-
-    if (isTranscriptBoundaryMessageUpdate(event)) await scheduleMessageRefresh("update");
-  });
-
-  pi.on("tool_execution_start", async (event) => {
-    if (!event.parentToolCallId) await scheduleMessageRefresh("update");
-  });
-
-  pi.on("tool_execution_end", async (event) => {
-    if (!event.parentToolCallId) await scheduleMessageRefresh("update");
   });
 
   pi.on("message_end", async (event, ctx) => {
@@ -855,7 +835,6 @@ export function createPontiaPiExtension(
       (event as unknown as Record<string, unknown> | undefined)?.message,
     );
     if (fullText) activeTurn.output = fullText;
-    await scheduleMessageRefresh("append");
   });
 
   pi.on("agent_settled", (_event, ctx) => {
@@ -878,7 +857,6 @@ export function createPontiaPiExtension(
           state.context,
           buildTurnInterruptedEvent(state.context, terminalLeafId),
         );
-        await reportFinalMessageRefresh(state);
         return;
       }
 
@@ -888,7 +866,6 @@ export function createPontiaPiExtension(
           state.context,
           buildTurnFailedEvent(state.context, failureMessage, terminalLeafId),
         );
-        await reportFinalMessageRefresh(state);
         return;
       }
 
@@ -912,7 +889,6 @@ export function createPontiaPiExtension(
         state.context,
         buildTurnCompletedEvent(state.context, terminalLeafId),
       );
-      await reportFinalMessageRefresh(state);
     } finally {
       await state.liveOutput.close();
     }

package/src/pi-message.ts

@@ -36,23 +36,6 @@ export function assistantDeltaFromEvent(event: unknown): string | undefined {
   return undefined;
 }
 
-const transcriptBoundaryStreamEventTypes = new Set([
-  "thinking_start",
-  "thinking_end",
-  "text_start",
-  "text_end",
-  "toolcall_start",
-  "toolcall_end",
-]);
-
-export function isTranscriptBoundaryMessageUpdate(event: unknown): boolean {
-  if (!event || typeof event !== "object") return false;
-  const streamEvent = (event as Record<string, unknown>).assistantMessageEvent;
-  if (!streamEvent || typeof streamEvent !== "object") return false;
-  const type = (streamEvent as Record<string, unknown>).type;
-  return typeof type === "string" && transcriptBoundaryStreamEventTypes.has(type);
-}
-
 interface PiAgentEndEventLike {
   messages: unknown[];
 }

package/src/rpc-error.ts

@@ -0,0 +1,7 @@
+export class RpcError extends Error {
+  readonly code: number;
+  constructor(code: number, message: string) {
+    super(message);
+    this.code = code;
+  }
+}