@pontia/pi-client-plugin 0.1.0

package/src/pi-message.ts

@@ -0,0 +1,87 @@
+function textFromContent(content: unknown): string | undefined {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return undefined;
+
+  const text = content
+    .map((part) => {
+      if (!part || typeof part !== "object") return "";
+      const record = part as Record<string, unknown>;
+      return record.type === "text" && typeof record.text === "string" ? record.text : "";
+    })
+    .join("");
+
+  return text.length > 0 ? text : undefined;
+}
+
+export function assistantTextFromMessage(message: unknown): string | undefined {
+  if (!message || typeof message !== "object") return undefined;
+  const record = message as Record<string, unknown>;
+  if (record.role !== "assistant") return undefined;
+  return textFromContent(record.content);
+}
+
+export function assistantDeltaFromEvent(event: unknown): string | undefined {
+  if (!event || typeof event !== "object") return undefined;
+  const record = event as Record<string, unknown>;
+  const streamEvent = record.assistantMessageEvent;
+  if (streamEvent && typeof streamEvent === "object") {
+    const streamRecord = streamEvent as Record<string, unknown>;
+    for (const key of ["text_delta", "textDelta", "delta", "text"] as const) {
+      const value = streamRecord[key];
+      if (typeof value === "string" && value.length > 0) return value;
+    }
+  }
+  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[];
+}
+
+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") {
+      return message as Record<string, unknown>;
+    }
+  }
+  return undefined;
+}
+
+export function agentEndWasInterrupted(event: PiAgentEndEventLike): boolean {
+  return lastAssistantMessageFromAgentEnd(event)?.stopReason === "aborted";
+}
+
+export function errorMessageFromAgentEnd(event: PiAgentEndEventLike): string | undefined {
+  const assistant = lastAssistantMessageFromAgentEnd(event);
+  if (assistant?.stopReason !== "error") return undefined;
+  return typeof assistant.errorMessage === "string" && assistant.errorMessage.length > 0
+    ? assistant.errorMessage
+    : "pi agent reported an error";
+}
+
+export function lastAssistantTextFromMessages(messages: unknown): string | undefined {
+  if (!Array.isArray(messages)) return undefined;
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const text = assistantTextFromMessage(messages[index]);
+    if (text) return text;
+  }
+  return undefined;
+}

package/src/profile.ts

@@ -0,0 +1,29 @@
+import { resolvePontiaConnection } from "./discovery.js";
+import { fetchJson, optionalString, responseDataRecord } from "./internal-api.js";
+
+export async function loadProfileSystemPrompt(
+  pontiaHome: string,
+  fetchImpl: typeof fetch,
+  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 (!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);
+}

package/src/reporter.ts

@@ -0,0 +1,67 @@
+import { appendDiagnostic } from "./diagnostics.js";
+import type { InternalEvent } from "./events.js";
+
+type FetchLike = typeof fetch;
+
+export interface EventReportResult {
+  accepted: boolean;
+  eventId?: string;
+  turnId?: string;
+}
+
+export interface EventReporterOptions {
+  fetch?: FetchLike;
+  logFile: string;
+}
+
+export class EventReporter {
+  private readonly fetchImpl: FetchLike;
+  private readonly logFile: string;
+
+  constructor(options: EventReporterOptions) {
+    this.fetchImpl = options.fetch ?? fetch;
+    this.logFile = options.logFile;
+  }
+
+  async report(context: { internalEventUrl: 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 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 },
+        });
+        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;
+      return {
+        accepted: true,
+        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) },
+      });
+      return { accepted: false };
+    }
+  }
+}

package/src/runtime-binding.ts

@@ -0,0 +1,133 @@
+import type { EnvLike } from "./context.js";
+import { resolvePontiaConnection } from "./discovery.js";
+import { asRecord, optionalString, parseJsonResponse } from "./internal-api.js";
+import type { SessionContext } from "./session.js";
+
+export type PiSessionDetails = Pick<SessionContext, "clientSessionKey" | "clientSessionFile" | "clientSessionDir" | "clientCwd">;
+
+function callSessionManagerString(sessionManager: unknown, method: string): string | undefined {
+  if (!sessionManager || typeof sessionManager !== "object") return undefined;
+  const fn = (sessionManager as Record<string, unknown>)[method];
+  if (typeof fn !== "function") return undefined;
+  try {
+    return optionalString(fn.call(sessionManager));
+  } catch {
+    return undefined;
+  }
+}
+
+export function piSessionDetailsFromHookContext(ctx: unknown): PiSessionDetails {
+  const sessionManager = ctx && typeof ctx === "object" ? (ctx as Record<string, unknown>).sessionManager : undefined;
+  return {
+    clientSessionKey: callSessionManagerString(sessionManager, "getSessionId"),
+    clientSessionFile: callSessionManagerString(sessionManager, "getSessionFile"),
+    clientSessionDir: callSessionManagerString(sessionManager, "getSessionDir"),
+    clientCwd: callSessionManagerString(sessionManager, "getCwd"),
+  };
+}
+
+function agentBindingSessionContextUrl(discoveredBindingUpsertUrl?: string): string | undefined {
+  return discoveredBindingUpsertUrl?.replace(
+    /\/runtime-bindings\/upsert\/?$/,
+    "/agent-bindings/session-context",
+  );
+}
+
+function tmuxBindingFromEnv(env: EnvLike): { socket_path: string; pane_id: string } | undefined {
+  const tmux = optionalString(env.TMUX);
+  const paneId = optionalString(env.TMUX_PANE);
+  const socketPath = optionalString(tmux?.split(",", 1)[0]);
+  if (!socketPath || !paneId) return undefined;
+  return { socket_path: socketPath, pane_id: paneId };
+}
+
+export async function bindSession(
+  pontiaHome: string,
+  env: EnvLike,
+  fetchImpl: typeof fetch,
+  sessionDetails: PiSessionDetails,
+  options: { startKind?: "fork"; parentSessionId?: string; runtimeInstanceId?: string } = {},
+): Promise<SessionContext | undefined> {
+  if (!sessionDetails.clientSessionKey) return undefined;
+  const discovered = await resolvePontiaConnection({ pontiaHome, fetch: fetchImpl });
+  const url = discovered?.bindingUpsertUrl;
+  if (!url) return undefined;
+
+  const tmux = tmuxBindingFromEnv(env);
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_type: "pi",
+      client_session_key: sessionDetails.clientSessionKey,
+      client_session_file: sessionDetails.clientSessionFile,
+      client_session_dir: sessionDetails.clientSessionDir,
+      client_cwd: sessionDetails.clientCwd,
+      launch_cwd: sessionDetails.clientCwd,
+      start_command: "pi",
+      ...(options.startKind ? { start_kind: options.startKind } : {}),
+      ...(options.parentSessionId ? { parent_session_id: options.parentSessionId } : {}),
+      ...(options.runtimeInstanceId ? { runtime_instance_id: options.runtimeInstanceId } : {}),
+      ...(tmux ? { tmux } : {}),
+    }),
+  });
+  const body = await parseJsonResponse(response);
+  if (!response.ok) throw new Error(`runtime binding upsert failed: ${response.status} ${response.statusText}`);
+
+  const record = asRecord(body);
+  const session = asRecord(record?.session);
+  const runtime = asRecord(record?.runtime);
+  const sessionId = optionalString(session?.session_id);
+  const resolvedRuntimeInstanceId = optionalString(runtime?.runtime_instance_id);
+  const internalEventUrl = optionalString(runtime?.internal_event_url) ?? discovered?.internalEventUrl;
+  if (!sessionId) throw new Error("runtime binding upsert response missing session.session_id");
+  if (!resolvedRuntimeInstanceId) throw new Error("runtime binding upsert response missing runtime.runtime_instance_id");
+  if (!internalEventUrl) throw new Error("runtime binding upsert response missing runtime.internal_event_url");
+  return {
+    sessionId,
+    clientType: "pi",
+    internalEventUrl,
+    runtimeInstanceId: resolvedRuntimeInstanceId,
+    ...sessionDetails,
+  };
+}
+
+export interface ExistingPiSessionContext extends SessionContext {
+  sessionState: string;
+}
+
+export async function loadExistingSessionContext(
+  pontiaHome: string,
+  fetchImpl: typeof fetch,
+  sessionDetails: PiSessionDetails,
+): Promise<ExistingPiSessionContext | undefined> {
+  if (!sessionDetails.clientSessionKey) return undefined;
+  const discovered = await resolvePontiaConnection({ pontiaHome, fetch: fetchImpl });
+  const baseUrl = agentBindingSessionContextUrl(discovered?.bindingUpsertUrl);
+  if (!baseUrl) return undefined;
+  const url = new URL(baseUrl);
+  url.searchParams.set("client_type", "pi");
+  url.searchParams.set("client_session_key", sessionDetails.clientSessionKey);
+  const response = await fetchImpl(url.toString());
+  if (response.status === 404) return undefined;
+  const body = await parseJsonResponse(response);
+  if (!response.ok) throw new Error(`agent binding session context lookup failed: ${response.status} ${response.statusText}`);
+
+  const record = asRecord(asRecord(asRecord(body)?.data)?.session_context);
+  const sessionId = optionalString(record?.session_id);
+  const sessionState = optionalString(record?.session_state);
+  const clientType = optionalString(record?.client_type);
+  const runtimeInstanceId = optionalString(record?.runtime_instance_id);
+  const internalEventUrl = optionalString(record?.internal_event_url) ?? discovered?.internalEventUrl;
+  if (!sessionId || !sessionState || clientType !== "pi" || !runtimeInstanceId || !internalEventUrl) {
+    throw new Error("agent binding session context lookup returned an invalid context");
+  }
+  return {
+    sessionId,
+    sessionState,
+    clientType: "pi",
+    runtimeInstanceId,
+    internalEventUrl,
+    ...sessionDetails,
+  };
+}

package/src/session.ts

@@ -0,0 +1,10 @@
+export interface SessionContext {
+  sessionId: string;
+  clientType: "pi";
+  internalEventUrl: string;
+  runtimeInstanceId: string;
+  clientSessionKey?: string;
+  clientSessionFile?: string;
+  clientSessionDir?: string;
+  clientCwd?: string;
+}

package/src/workspace.ts

@@ -0,0 +1,34 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { resolvePontiaConnection } from "./discovery.js";
+import { asRecord, fetchJson, responseDataRecord } from "./internal-api.js";
+
+async function canonicalPath(path: string): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+export async function resolveWorkspaceApi(pontiaHome: string, fetchImpl: typeof fetch): Promise<{ externalApiUrl: string; externalApiToken: string } | undefined> {
+  const discovered = await resolvePontiaConnection({ pontiaHome, fetch: fetchImpl });
+  if (!discovered?.externalApiToken) return undefined;
+  return { externalApiUrl: discovered.externalApiUrl, externalApiToken: discovered.externalApiToken };
+}
+
+export async function isActiveRegisteredWorkspace(pontiaHome: string, fetchImpl: typeof fetch, clientCwd: string | undefined): Promise<boolean | undefined> {
+  if (!clientCwd) return false;
+  const api = await resolveWorkspaceApi(pontiaHome, fetchImpl);
+  if (!api) return undefined;
+
+  const workspacePath = await canonicalPath(clientCwd);
+  const body = await fetchJson(fetchImpl, `${api.externalApiUrl}/workspaces`, api.externalApiToken);
+  const workspaces = responseDataRecord(body)?.workspaces;
+  if (!Array.isArray(workspaces)) return false;
+
+  return workspaces.some((workspace) => {
+    const record = asRecord(workspace);
+    return record?.state === "active" && record.canonical_path === workspacePath;
+  });
+}