@pontia/pi-client-plugin 0.2.0 → 0.2.1

package/src/live-output.ts

@@ -0,0 +1,339 @@
+import { randomUUID } from "node:crypto";
+import type { TurnContext } from "./context.js";
+import { RpcError, type PiConnection } from "./control-socket.js";
+import { asRecord, optionalString } from "./values.js";
+
+const DEFAULT_BATCH_DELAY_MS = 75;
+const RETRY_DELAY_MS = 500;
+
+export type ManagedToolUse = {
+  tool_name: string;
+  input:
+    | { type: "read"; path: string; start_line?: number; end_line?: number }
+    | { type: "edit"; path: string; edits_count: number }
+    | { type: "write"; path: string }
+    | { type: "bash"; command: string; timeout?: number };
+};
+
+export type LiveOutputItem =
+  | { kind: "assistant_text"; item_id: string; text: string }
+  | {
+      kind: "tool_call";
+      item_id: string;
+      call_id: string;
+      tool_name: string;
+      arguments: unknown;
+      managed_tool_use?: ManagedToolUse;
+    };
+
+export type LiveOutputUpdate =
+  | { type: "assistant_text_delta"; item_id: string; delta: string }
+  | {
+      type: "tool_call";
+      item_id: string;
+      call_id: string;
+      tool_name: string;
+      arguments: unknown;
+      managed_tool_use?: ManagedToolUse;
+    };
+
+export interface CompleteToolCall {
+  callId: string;
+  toolName: string;
+  arguments: unknown;
+}
+
+export interface LiveOutputPublisherLike {
+  appendText(delta: string): void;
+  appendToolCall(toolCall: CompleteToolCall): void;
+  close(): Promise<void>;
+}
+
+interface PendingUpdate {
+  sequence: number;
+  update: LiveOutputUpdate;
+}
+
+interface LiveOutputResponse {
+  accepted: boolean;
+  accepted_sequence: number;
+  resync_required: boolean;
+}
+
+export interface LiveOutputPublisherOptions {
+  connection: Pick<PiConnection, "request">;
+  streamId?: string;
+  batchDelayMs?: number;
+}
+
+export class LiveOutputPublisher implements LiveOutputPublisherLike {
+  private readonly connection: Pick<PiConnection, "request">;
+  private readonly context: TurnContext & { turnId: string };
+  private readonly streamId: string;
+  private readonly batchDelayMs: number;
+  private readonly items: LiveOutputItem[] = [];
+  private readonly pending: PendingUpdate[] = [];
+  private sequence = 0;
+  private itemSequence = 0;
+  private needsSnapshot = true;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private retryTimer: ReturnType<typeof setTimeout> | undefined;
+  private flushing: Promise<boolean> | undefined;
+  private closing = false;
+  private disabled = false;
+
+  constructor(context: TurnContext & { turnId: string }, options: LiveOutputPublisherOptions) {
+    this.context = context;
+    this.connection = options.connection;
+    this.streamId = options.streamId ?? `stream_${randomUUID()}`;
+    this.batchDelayMs = options.batchDelayMs ?? DEFAULT_BATCH_DELAY_MS;
+  }
+
+  appendText(delta: string): void {
+    if (this.closing || this.disabled || delta.length === 0) return;
+    let item = this.items.at(-1);
+    if (item?.kind !== "assistant_text") {
+      item = { kind: "assistant_text", item_id: this.nextItemId("text"), text: "" };
+      this.items.push(item);
+    }
+    item.text += delta;
+    this.enqueue({ type: "assistant_text_delta", item_id: item.item_id, delta });
+  }
+
+  appendToolCall(toolCall: CompleteToolCall): void {
+    if (
+      this.closing ||
+      this.disabled ||
+      this.items.some((item) => item.kind === "tool_call" && item.call_id === toolCall.callId)
+    )
+      return;
+    const managedToolUse = managedToolUseFor(toolCall);
+    const item: LiveOutputItem = {
+      kind: "tool_call",
+      item_id: this.nextItemId("tool"),
+      call_id: toolCall.callId,
+      tool_name: toolCall.toolName,
+      arguments: toolCall.arguments,
+      ...(managedToolUse ? { managed_tool_use: managedToolUse } : {}),
+    };
+    this.items.push(item);
+    this.enqueue({
+      type: "tool_call",
+      item_id: item.item_id,
+      call_id: item.call_id,
+      tool_name: item.tool_name,
+      arguments: item.arguments,
+      ...(item.managed_tool_use ? { managed_tool_use: item.managed_tool_use } : {}),
+    });
+  }
+
+  async close(): Promise<void> {
+    if (this.closing || this.disabled) return;
+    this.closing = true;
+    this.clearTimers();
+    if (this.flushing) await this.flushing;
+    const synchronized = await this.flushCurrent();
+    if (!synchronized || this.sequence === 0) return;
+
+    const closeSequence = this.sequence + 1;
+    const response = await this.publish({
+      ...this.baseRequest(),
+      type: "stream_closed",
+      sequence: closeSequence,
+    });
+    if (response?.accepted) this.sequence = closeSequence;
+  }
+
+  private enqueue(update: LiveOutputUpdate): void {
+    this.sequence += 1;
+    this.pending.push({ sequence: this.sequence, update });
+    this.scheduleFlush(this.batchDelayMs);
+  }
+
+  private nextItemId(prefix: string): string {
+    this.itemSequence += 1;
+    return `${prefix}_${this.itemSequence}`;
+  }
+
+  private clearTimers(): void {
+    if (this.timer) clearTimeout(this.timer);
+    if (this.retryTimer) clearTimeout(this.retryTimer);
+    this.timer = undefined;
+    this.retryTimer = undefined;
+  }
+
+  private scheduleFlush(delay: number): void {
+    if (this.closing || this.disabled || this.timer || this.retryTimer) return;
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      void this.flush().then((synchronized) => {
+        if (!synchronized && !this.closing) this.scheduleRetry();
+      });
+    }, delay);
+  }
+
+  private scheduleRetry(): void {
+    if (this.closing || this.disabled || this.retryTimer) return;
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = undefined;
+      void this.flush().then((synchronized) => {
+        if (!synchronized && !this.closing) this.scheduleRetry();
+      });
+    }, RETRY_DELAY_MS);
+  }
+
+  private async flush(): Promise<boolean> {
+    if (this.flushing) return this.flushing;
+    this.flushing = this.flushCurrent().finally(() => {
+      this.flushing = undefined;
+    });
+    return this.flushing;
+  }
+
+  private async flushCurrent(): Promise<boolean> {
+    if (this.sequence === 0) return true;
+    const targetSequence = this.sequence;
+    const response = this.needsSnapshot
+      ? await this.publish({
+          ...this.baseRequest(),
+          type: "snapshot",
+          sequence: targetSequence,
+          items: this.items,
+        })
+      : await this.publishAppend(targetSequence);
+
+    if (!response?.accepted) {
+      this.needsSnapshot = true;
+      return false;
+    }
+
+    const firstUnaccepted = this.pending.findIndex(
+      (entry) => entry.sequence > response.accepted_sequence,
+    );
+    this.pending.splice(0, firstUnaccepted === -1 ? this.pending.length : firstUnaccepted);
+    this.needsSnapshot = response.resync_required;
+    if (this.pending.length > 0 && !this.closing) this.scheduleFlush(this.batchDelayMs);
+    return !this.needsSnapshot;
+  }
+
+  private async publishAppend(targetSequence: number): Promise<LiveOutputResponse | undefined> {
+    const updates = this.pending.filter((entry) => entry.sequence <= targetSequence);
+    if (updates.length === 0)
+      return {
+        accepted: true,
+        accepted_sequence: targetSequence,
+        resync_required: false,
+      };
+    return this.publish({
+      ...this.baseRequest(),
+      type: "append",
+      first_sequence: updates[0].sequence,
+      updates: updates.map((entry) => entry.update),
+    });
+  }
+
+  private baseRequest() {
+    return {
+      session_id: this.context.sessionId,
+      turn_id: this.context.turnId,
+      runtime_instance_id: this.context.runtimeInstanceId,
+      stream_id: this.streamId,
+    };
+  }
+
+  private async publish(body: Record<string, unknown>): Promise<LiveOutputResponse | undefined> {
+    try {
+      // Freeze the batch before a reconnect can delay its serialization.
+      const response = await this.connection.request("liveOutput.publish", structuredClone(body));
+      const parsed = asRecord(response);
+      const acceptedSequence = parsed?.accepted_sequence;
+      const accepted = parsed?.accepted;
+      const resyncRequired = parsed?.resync_required;
+      if (
+        typeof acceptedSequence !== "number" ||
+        !Number.isSafeInteger(acceptedSequence) ||
+        acceptedSequence < 0 ||
+        typeof accepted !== "boolean" ||
+        typeof resyncRequired !== "boolean"
+      ) {
+        return undefined;
+      }
+      return {
+        accepted,
+        accepted_sequence: acceptedSequence,
+        resync_required: resyncRequired,
+      };
+    } catch (error) {
+      if (error instanceof RpcError && error.code !== -32603) this.disabled = true;
+      return undefined;
+    }
+  }
+}
+
+function managedToolUseFor(toolCall: CompleteToolCall): ManagedToolUse | undefined {
+  const input = asRecord(toolCall.arguments);
+  if (!input) return undefined;
+
+  switch (toolCall.toolName) {
+    case "read": {
+      const path = optionalString(input.path);
+      if (!path) return undefined;
+      const startLine = optionalNonNegativeInteger(input.start_line);
+      const endLine = optionalNonNegativeInteger(input.end_line);
+      return {
+        tool_name: toolCall.toolName,
+        input: {
+          type: "read",
+          path,
+          ...(startLine !== undefined ? { start_line: startLine } : {}),
+          ...(endLine !== undefined ? { end_line: endLine } : {}),
+        },
+      };
+    }
+    case "edit": {
+      const path = optionalString(input.path);
+      if (!path || !Array.isArray(input.edits)) return undefined;
+      return {
+        tool_name: toolCall.toolName,
+        input: {
+          type: "edit",
+          path,
+          edits_count: input.edits.length,
+        },
+      };
+    }
+    case "write": {
+      const path = optionalString(input.path);
+      return path ? { tool_name: toolCall.toolName, input: { type: "write", path } } : undefined;
+    }
+    case "bash": {
+      const command = optionalString(input.command);
+      if (!command) return undefined;
+      const timeout = optionalNonNegativeInteger(input.timeout);
+      return {
+        tool_name: toolCall.toolName,
+        input: {
+          type: "bash",
+          command,
+          ...(timeout !== undefined ? { timeout } : {}),
+        },
+      };
+    }
+    default:
+      return undefined;
+  }
+}
+
+function optionalNonNegativeInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+export function completeToolCallFromMessageUpdate(event: unknown): CompleteToolCall | undefined {
+  const streamEvent = asRecord(asRecord(event)?.assistantMessageEvent);
+  if (streamEvent?.type !== "toolcall_end") return undefined;
+  const toolCall = asRecord(streamEvent.toolCall);
+  const callId = optionalString(toolCall?.id);
+  const toolName = optionalString(toolCall?.name);
+  if (!callId || !toolName || !("arguments" in (toolCall ?? {}))) return undefined;
+  return { callId, toolName, arguments: toolCall!.arguments };
+}

package/src/managed-runtime.ts

@@ -14,7 +14,11 @@ export function hasTmuxPaneEnvironment(env: EnvLike = process.env): boolean {
   return Boolean(socketPath && env.TMUX_PANE?.trim());
 }
 
-async function paneOption(socketPath: string, paneId: string, option: string): Promise<string | undefined> {
+async function paneOption(
+  socketPath: string,
+  paneId: string,
+  option: string,
+): Promise<string | undefined> {
   try {
     const { stdout } = await execFileAsync("tmux", [
       "-S",

package/src/pi-message.ts

@@ -26,6 +26,8 @@ export function assistantDeltaFromEvent(event: unknown): string | undefined {
   const streamEvent = record.assistantMessageEvent;
   if (streamEvent && typeof streamEvent === "object") {
     const streamRecord = streamEvent as Record<string, unknown>;
+    if (typeof streamRecord.type === "string" && streamRecord.type !== "text_delta")
+      return undefined;
     for (const key of ["text_delta", "textDelta", "delta", "text"] as const) {
       const value = streamRecord[key];
       if (typeof value === "string" && value.length > 0) return value;
@@ -55,10 +57,16 @@ interface PiAgentEndEventLike {
   messages: unknown[];
 }
 
-function lastAssistantMessageFromAgentEnd(event: PiAgentEndEventLike): Record<string, unknown> | undefined {
+function lastAssistantMessageFromAgentEnd(
+  event: PiAgentEndEventLike,
+): Record<string, unknown> | undefined {
   for (let index = event.messages.length - 1; index >= 0; index -= 1) {
     const message = event.messages[index];
-    if (message && typeof message === "object" && (message as Record<string, unknown>).role === "assistant") {
+    if (
+      message &&
+      typeof message === "object" &&
+      (message as Record<string, unknown>).role === "assistant"
+    ) {
       return message as Record<string, unknown>;
     }
   }
@@ -66,7 +74,9 @@ function lastAssistantMessageFromAgentEnd(event: PiAgentEndEventLike): Record<st
 }
 
 export function agentEndWasInterrupted(event: PiAgentEndEventLike, signal?: AbortSignal): boolean {
-  return signal?.aborted === true || lastAssistantMessageFromAgentEnd(event)?.stopReason === "aborted";
+  return (
+    signal?.aborted === true || lastAssistantMessageFromAgentEnd(event)?.stopReason === "aborted"
+  );
 }
 
 export function errorMessageFromAgentEnd(event: PiAgentEndEventLike): string | undefined {

package/src/profile.ts

@@ -1,29 +1,21 @@
-import { resolvePontiaConnection } from "./discovery.js";
-import { fetchJson, optionalString, responseDataRecord } from "./internal-api.js";
+import type { PiConnection } from "./control-socket.js";
+import { asRecord, optionalString } from "./values.js";
 
 export async function loadProfileSystemPrompt(
-  pontiaHome: string,
-  fetchImpl: typeof fetch,
+  connection: Pick<PiConnection, "request">,
   sessionId?: string,
 ): Promise<string | undefined> {
-  const connection = await resolvePontiaConnection({ pontiaHome, fetch: fetchImpl });
-  const baseUrl = connection?.externalApiUrl;
-  const token = connection?.externalApiToken;
-  if (!baseUrl || !token || !sessionId) return undefined;
-
-  const sessionBody = await fetchJson(fetchImpl, `${baseUrl}/sessions/${encodeURIComponent(sessionId)}`, token);
-  const session = responseDataRecord(sessionBody)?.session;
-  if (!session || typeof session !== "object" || Array.isArray(session)) return undefined;
-  const sessionRecord = session as Record<string, unknown>;
-  const profileId = optionalString(sessionRecord.execution_profile_id);
-  const profileVersion = optionalString(sessionRecord.execution_profile_version);
+  if (!sessionId) return undefined;
+  const sessionBody = await connection.request("session.get", { session_id: sessionId });
+  const session = asRecord(asRecord(sessionBody)?.session);
+  const profileId = optionalString(session?.execution_profile_id);
+  const profileVersion = optionalString(session?.execution_profile_version);
   if (!profileId) return undefined;
 
-  const profileUrl = profileVersion
-    ? `${baseUrl}/agent-profiles/${encodeURIComponent(profileId)}/versions/${encodeURIComponent(profileVersion)}`
-    : `${baseUrl}/agent-profiles/${encodeURIComponent(profileId)}`;
-  const profileBody = await fetchJson(fetchImpl, profileUrl, token);
-  const profile = responseDataRecord(profileBody)?.agent_profile;
-  if (!profile || typeof profile !== "object" || Array.isArray(profile)) return undefined;
-  return optionalString((profile as Record<string, unknown>).system_prompt_template);
+  const profileBody = await connection.request("profile.get", {
+    profile_id: profileId,
+    ...(profileVersion ? { version: profileVersion } : {}),
+  });
+  const profile = asRecord(asRecord(profileBody)?.agent_profile);
+  return optionalString(profile?.system_prompt_template);
 }

package/src/reporter.ts

@@ -1,8 +1,7 @@
 import { appendDiagnostic } from "./diagnostics.js";
+import { RpcError, type PiConnection } from "./control-socket.js";
 import type { InternalEvent } from "./events.js";
 
-type FetchLike = typeof fetch;
-
 export interface EventReportResult {
   accepted: boolean;
   eventId?: string;
@@ -10,58 +9,89 @@ export interface EventReportResult {
 }
 
 export interface EventReporterOptions {
-  fetch?: FetchLike;
+  connection: Pick<PiConnection, "request">;
   logFile: string;
 }
 
 export class EventReporter {
-  private readonly fetchImpl: FetchLike;
+  private readonly connection: Pick<PiConnection, "request">;
   private readonly logFile: string;
 
   constructor(options: EventReporterOptions) {
-    this.fetchImpl = options.fetch ?? fetch;
+    this.connection = options.connection;
     this.logFile = options.logFile;
   }
 
-  async report(context: { internalEventUrl: string }, event: InternalEvent): Promise<EventReportResult> {
+  async report(
+    context: { runtimeInstanceId: string },
+    event: InternalEvent,
+  ): Promise<EventReportResult> {
     try {
-      const response = await this.fetchImpl(context.internalEventUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(event),
+      const body = await this.connection.request("event.report", {
+        runtime_instance_id: context.runtimeInstanceId,
+        event,
       });
-
-      const body = await response.text().catch(() => "");
-      if (!response.ok) {
-        await appendDiagnostic(this.logFile, {
-          level: "error",
-          code: "internal_event_post_failed",
-          message: `Internal Event API rejected ${event.type}: ${response.status} ${response.statusText}`,
-          details: { event_type: event.type, status: response.status, body },
-        });
+      const record =
+        body && typeof body === "object" ? (body as Record<string, unknown>) : undefined;
+      if (
+        event.type === "turn.started" &&
+        (record?.accepted !== true || typeof record?.turn_id !== "string" || !record.turn_id)
+      ) {
+        await this.reportStartFailure(event, "missing_turn_id");
         return { accepted: false };
       }
-
-      let responseBody: unknown;
-      try {
-        responseBody = body ? JSON.parse(body) : null;
-      } catch {
-        responseBody = null;
-      }
-      const record = responseBody && typeof responseBody === "object" ? responseBody as Record<string, unknown> : undefined;
+      if (record?.accepted !== true)
+        throw new Error("Pi event RPC returned an invalid acknowledgement");
       return {
         accepted: true,
-        eventId: typeof record?.event_id === "string" ? record.event_id : undefined,
-        turnId: typeof record?.turn_id === "string" ? record.turn_id : undefined,
+        eventId: typeof record.event_id === "string" ? record.event_id : undefined,
+        turnId: typeof record.turn_id === "string" ? record.turn_id : undefined,
       };
     } catch (error) {
       await appendDiagnostic(this.logFile, {
         level: "error",
-        code: "internal_event_post_exception",
-        message: `Internal Event API POST failed for ${event.type}`,
-        details: { event_type: event.type, error: error instanceof Error ? error.message : String(error) },
+        code: "pi_event_report_failed",
+        message: `Pi event RPC failed for ${event.type}`,
+        details: {
+          event_type: event.type,
+          error: error instanceof Error ? error.message : String(error),
+        },
       });
+      await this.reportStartFailure(
+        event,
+        error instanceof RpcError ? "event_rejected" : "transport_failed",
+      );
       return { accepted: false };
     }
   }
+
+  private async reportStartFailure(
+    event: InternalEvent,
+    reason: "event_rejected" | "transport_failed" | "missing_turn_id",
+  ): Promise<void> {
+    if (event.type !== "turn.started" || typeof event.data.runtime_instance_id !== "string") return;
+    // A lost turn.started response is ambiguous: retrying it could create a
+    // second Turn. Only this fenced, idempotent failure notification is retried.
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (attempt > 0) await new Promise((resolve) => setTimeout(resolve, 100 * attempt));
+      try {
+        const result = (await this.connection.request("turn.startFailure", {
+          session_id: event.session_id,
+          runtime_instance_id: event.data.runtime_instance_id,
+          reason,
+        })) as { accepted?: unknown } | null;
+        if (result?.accepted === true) return;
+      } catch (error) {
+        if (error instanceof RpcError && error.code !== -32603) break;
+        // Exhaustion is visible locally; an unreachable server cannot persist
+        // a state transition. Never claim that this notification succeeded.
+      }
+    }
+    await appendDiagnostic(this.logFile, {
+      level: "error",
+      code: "turn_start_failure_report_failed",
+      message: "could not persist turn.started reporting failure; workflow state is unconfirmed",
+      details: { session_id: event.session_id, reason },
+    });
+  }
 }