@plannotator/pi-extension 0.15.0 → 0.15.2

package/README.md

@@ -55,7 +55,7 @@ In plan mode the agent is restricted — destructive commands are blocked, write
 - [ ] Update error messages in the UI
 ```
 
-When the agent calls `exit_plan_mode`, the Plannotator UI opens in your browser. You can:
+When the agent calls `plannotator_submit_plan`, the Plannotator UI opens in your browser. You can:
 
 - **Approve** the plan to begin execution
 - **Deny with annotations** to send structured feedback back to the agent

package/generated/ai/base-session.ts

@@ -0,0 +1,95 @@
+// @generated — DO NOT EDIT. Source: packages/ai/base-session.ts
+/**
+ * Shared session base class — extracts the common lifecycle, abort, and
+ * ID-resolution logic that every AIProvider session needs.
+ *
+ * Concrete providers extend this and implement query().
+ */
+
+import type { AIMessage, AISession } from "./types.ts";
+
+export abstract class BaseSession implements AISession {
+	readonly parentSessionId: string | null;
+	onIdResolved?: (oldId: string, newId: string) => void;
+
+	protected _placeholderId: string;
+	protected _resolvedId: string | null = null;
+	protected _isActive = false;
+	protected _currentAbort: AbortController | null = null;
+	protected _queryGen = 0;
+	protected _firstQuerySent = false;
+
+	constructor(opts: { parentSessionId: string | null; initialId?: string }) {
+		this.parentSessionId = opts.parentSessionId;
+		this._placeholderId = opts.initialId ?? crypto.randomUUID();
+	}
+
+	get id(): string {
+		return this._resolvedId ?? this._placeholderId;
+	}
+
+	get isActive(): boolean {
+		return this._isActive;
+	}
+
+	// ---------------------------------------------------------------------------
+	// Query lifecycle helpers — call from concrete query() implementations
+	// ---------------------------------------------------------------------------
+
+	/** Error message returned when a query is already active. */
+	static readonly BUSY_ERROR: AIMessage = {
+		type: "error",
+		error:
+			"A query is already in progress. Abort the current query before sending a new one.",
+		code: "session_busy",
+	};
+
+	/**
+	 * Call at the start of query(). Returns the generation number and abort
+	 * signal, or null if the session is busy.
+	 */
+	protected startQuery(): { gen: number; signal: AbortSignal } | null {
+		if (this._isActive) return null;
+
+		const gen = ++this._queryGen;
+		this._isActive = true;
+		this._currentAbort = new AbortController();
+		return { gen, signal: this._currentAbort.signal };
+	}
+
+	/**
+	 * Call in the finally block of query(). Only clears state if the
+	 * generation matches (prevents a stale finally from clobbering a newer query).
+	 */
+	protected endQuery(gen: number): void {
+		if (this._queryGen === gen) {
+			this._isActive = false;
+			this._currentAbort = null;
+		}
+	}
+
+	/**
+	 * Call when the provider resolves the real session ID from the backend.
+	 * Fires the onIdResolved callback so the SessionManager can remap its key.
+	 */
+	protected resolveId(newId: string): void {
+		if (this._resolvedId) return; // Already resolved
+		const oldId = this._placeholderId;
+		this._resolvedId = newId;
+		this.onIdResolved?.(oldId, newId);
+	}
+
+	/**
+	 * Abort the current in-flight query. Subclasses should call super.abort()
+	 * after any provider-specific cleanup.
+	 */
+	abort(): void {
+		if (this._currentAbort) {
+			this._currentAbort.abort();
+			this._isActive = false;
+			this._currentAbort = null;
+		}
+	}
+
+	abstract query(prompt: string): AsyncIterable<AIMessage>;
+}

package/generated/ai/context.ts

@@ -0,0 +1,212 @@
+// @generated — DO NOT EDIT. Source: packages/ai/context.ts
+/**
+ * Context builders — translate Plannotator review state into system prompts
+ * that give the AI session the right background for answering questions.
+ *
+ * These are provider-agnostic: any AIProvider implementation can use them
+ * to build the system prompt it needs.
+ */
+
+import type { AIContext } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a system prompt from the given context.
+ *
+ * The prompt tells the AI:
+ * - What role it plays (plan reviewer, code reviewer, etc.)
+ * - The content it should reference (plan markdown, diff patch, file)
+ * - Any annotations the user has already made
+ * - That it's operating inside Plannotator (not a general coding session)
+ */
+export function buildSystemPrompt(ctx: AIContext): string {
+  switch (ctx.mode) {
+    case "plan-review":
+      return buildPlanReviewPrompt(ctx);
+    case "code-review":
+      return buildCodeReviewPrompt(ctx);
+    case "annotate":
+      return buildAnnotatePrompt(ctx);
+  }
+}
+
+/**
+ * Build a compact context summary suitable for injecting into a fork prompt.
+ *
+ * When forking from a parent session, we don't need a full system prompt
+ * (the parent's history already provides context). Instead, we inject a
+ * short "you are now in Plannotator" preamble with the relevant content.
+ */
+export function buildForkPreamble(ctx: AIContext): string {
+  const lines: string[] = [
+    "The user is now reviewing your work in Plannotator and has a question.",
+    "Answer concisely based on the conversation history and the context below.",
+    "",
+  ];
+
+  switch (ctx.mode) {
+    case "plan-review": {
+      lines.push("## Current Plan Under Review");
+      lines.push("");
+      lines.push(truncate(ctx.plan.plan, MAX_PLAN_CHARS));
+      if (ctx.plan.annotations) {
+        lines.push("");
+        lines.push("## User Annotations So Far");
+        lines.push(ctx.plan.annotations);
+      }
+      break;
+    }
+    case "code-review": {
+      if (ctx.review.filePath) {
+        lines.push(`## Reviewing: ${ctx.review.filePath}`);
+      }
+      if (ctx.review.selectedCode) {
+        lines.push("");
+        lines.push("### Selected Code");
+        lines.push("```");
+        lines.push(ctx.review.selectedCode);
+        lines.push("```");
+      }
+      if (ctx.review.lineRange) {
+        const { start, end, side } = ctx.review.lineRange;
+        lines.push(`Lines ${start}-${end} (${side} side)`);
+      }
+      lines.push("");
+      lines.push("## Diff Patch");
+      lines.push("```diff");
+      lines.push(truncate(ctx.review.patch, MAX_DIFF_CHARS));
+      lines.push("```");
+      if (ctx.review.annotations) {
+        lines.push("");
+        lines.push("## User Annotations So Far");
+        lines.push(ctx.review.annotations);
+      }
+      break;
+    }
+    case "annotate": {
+      lines.push(`## Annotating: ${ctx.annotate.filePath}`);
+      lines.push("");
+      lines.push(truncate(ctx.annotate.content, MAX_PLAN_CHARS));
+      if (ctx.annotate.annotations) {
+        lines.push("");
+        lines.push("## User Annotations So Far");
+        lines.push(ctx.annotate.annotations);
+      }
+      break;
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Build the effective prompt for a query, prepending a preamble on the first
+ * message. Used by providers that inject context via the prompt itself (Codex,
+ * Pi) rather than a separate system-prompt channel (Claude).
+ */
+export function buildEffectivePrompt(
+  userPrompt: string,
+  preamble: string | null,
+  firstQuerySent: boolean,
+): string {
+  if (!firstQuerySent && preamble) {
+    return `${preamble}\n\n---\n\nUser question: ${userPrompt}`;
+  }
+  return userPrompt;
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+const MAX_PLAN_CHARS = 60_000;
+const MAX_DIFF_CHARS = 40_000;
+
+function truncate(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n\n... [truncated for context window]`;
+}
+
+function buildPlanReviewPrompt(
+  ctx: Extract<AIContext, { mode: "plan-review" }>
+): string {
+  const sections: string[] = [
+    "The user is reviewing an implementation plan in Plannotator.",
+    "",
+    "## Plan Under Review",
+    "",
+    truncate(ctx.plan.plan, MAX_PLAN_CHARS),
+  ];
+
+  if (ctx.plan.previousPlan) {
+    sections.push("");
+    sections.push("## Previous Plan Version (for reference)");
+    sections.push(truncate(ctx.plan.previousPlan, MAX_PLAN_CHARS / 2));
+  }
+
+  if (ctx.plan.annotations) {
+    sections.push("");
+    sections.push("## User Annotations");
+    sections.push(ctx.plan.annotations);
+  }
+
+  return sections.join("\n");
+}
+
+function buildCodeReviewPrompt(
+  ctx: Extract<AIContext, { mode: "code-review" }>
+): string {
+  const sections: string[] = [
+    "The user is reviewing a code diff in Plannotator.",
+  ];
+
+  if (ctx.review.filePath) {
+    sections.push("");
+    sections.push(`## Currently Viewing: ${ctx.review.filePath}`);
+  }
+
+  if (ctx.review.selectedCode) {
+    sections.push("");
+    sections.push("## Selected Code");
+    sections.push("```");
+    sections.push(ctx.review.selectedCode);
+    sections.push("```");
+  }
+
+  sections.push("");
+  sections.push("## Diff");
+  sections.push("```diff");
+  sections.push(truncate(ctx.review.patch, MAX_DIFF_CHARS));
+  sections.push("```");
+
+  if (ctx.review.annotations) {
+    sections.push("");
+    sections.push("## User Annotations");
+    sections.push(ctx.review.annotations);
+  }
+
+  return sections.join("\n");
+}
+
+function buildAnnotatePrompt(
+  ctx: Extract<AIContext, { mode: "annotate" }>
+): string {
+  const sections: string[] = [
+    "The user is annotating a markdown document in Plannotator.",
+    "",
+    `## Document: ${ctx.annotate.filePath}`,
+    "",
+    truncate(ctx.annotate.content, MAX_PLAN_CHARS),
+  ];
+
+  if (ctx.annotate.annotations) {
+    sections.push("");
+    sections.push("## User Annotations");
+    sections.push(ctx.annotate.annotations);
+  }
+
+  return sections.join("\n");
+}

package/generated/ai/endpoints.ts

@@ -0,0 +1,309 @@
+// @generated — DO NOT EDIT. Source: packages/ai/endpoints.ts
+/**
+ * HTTP endpoint handlers for AI features.
+ *
+ * These handlers are provider-agnostic — they work with whatever AIProvider
+ * is registered in the provided ProviderRegistry. They're designed to be
+ * mounted into any Plannotator server (plan review, code review, annotate).
+ *
+ * Endpoints:
+ *   POST /api/ai/session       — Create or fork an AI session
+ *   POST /api/ai/query         — Send a message and stream the response
+ *   POST /api/ai/abort         — Abort the current query
+ *   GET  /api/ai/sessions      — List active sessions
+ *   GET  /api/ai/capabilities  — Check if AI features are available
+ */
+
+import type { AIContext, AIMessage, CreateSessionOptions } from "./types.ts";
+import type { ProviderRegistry } from "./provider.ts";
+import type { SessionManager } from "./session-manager.ts";
+
+// ---------------------------------------------------------------------------
+// Types for request/response
+// ---------------------------------------------------------------------------
+
+export interface CreateSessionRequest {
+  /** The context mode and content for the session. */
+  context: AIContext;
+  /** Instance ID of the provider to use (optional — uses default if omitted). */
+  providerId?: string;
+  /** Optional model override. */
+  model?: string;
+  /** Max agentic turns. */
+  maxTurns?: number;
+  /** Max budget in USD. */
+  maxBudgetUsd?: number;
+  /** Reasoning effort (Codex only). */
+  reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
+}
+
+export interface QueryRequest {
+  /** The session ID to query. */
+  sessionId: string;
+  /** The user's prompt/question. */
+  prompt: string;
+  /** Optional context update (e.g., new annotations since session was created). */
+  contextUpdate?: string;
+}
+
+export interface AbortRequest {
+  /** The session ID to abort. */
+  sessionId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Handler factory
+// ---------------------------------------------------------------------------
+
+export interface AIEndpointDeps {
+  /** Provider registry (one per server or shared). */
+  registry: ProviderRegistry;
+  /** Session manager instance (one per server). */
+  sessionManager: SessionManager;
+  /** Resolve the current working directory for new AI sessions. */
+  getCwd?: () => string;
+}
+
+/**
+ * Create the route handler map for AI endpoints.
+ *
+ * Usage in a Bun server:
+ * ```ts
+ * const aiHandlers = createAIEndpoints({ registry, sessionManager });
+ *
+ * // In your request handler:
+ * if (url.pathname.startsWith('/api/ai/')) {
+ *   const handler = aiHandlers[url.pathname];
+ *   if (handler) return handler(req);
+ * }
+ * ```
+ */
+export function createAIEndpoints(deps: AIEndpointDeps) {
+  const { registry, sessionManager, getCwd } = deps;
+
+  return {
+    "/api/ai/capabilities": async (_req: Request) => {
+      const defaultEntry = registry.getDefault();
+      const providerDetails = registry.list().map(id => {
+        const p = registry.get(id)!;
+        return {
+          id,
+          name: p.name,
+          capabilities: p.capabilities,
+          models: p.models ?? [],
+        };
+      });
+      return Response.json({
+        available: !!defaultEntry,
+        providers: providerDetails,
+        defaultProvider: defaultEntry?.id ?? null,
+      });
+    },
+
+    "/api/ai/session": async (req: Request) => {
+      if (req.method !== "POST") {
+        return new Response("Method not allowed", { status: 405 });
+      }
+
+      const body = (await req.json()) as CreateSessionRequest;
+      const { context, providerId, model, maxTurns, maxBudgetUsd, reasoningEffort } = body;
+
+      if (!context?.mode) {
+        return Response.json(
+          { error: "Missing context.mode" },
+          { status: 400 }
+        );
+      }
+
+      // Resolve provider: by ID, or default
+      const provider = providerId
+        ? registry.get(providerId)
+        : registry.getDefault()?.provider;
+
+      if (!provider) {
+        return Response.json(
+          { error: providerId ? `Provider "${providerId}" not found` : "No AI provider available" },
+          { status: 503 }
+        );
+      }
+
+      try {
+        const options: CreateSessionOptions = {
+          context,
+          cwd: getCwd?.(),
+          model,
+          maxTurns,
+          maxBudgetUsd,
+          reasoningEffort,
+        };
+
+        // Fork if parent session is provided AND provider supports it.
+        // Providers that can't fork (e.g. Codex) fall back to a fresh
+        // session with the full system prompt — no fake history.
+        const shouldFork = context.parent && provider.capabilities.fork;
+        const session = shouldFork
+          ? await provider.forkSession(options)
+          : await provider.createSession(options);
+
+        const entry = sessionManager.track(session, context.mode);
+
+        return Response.json({
+          sessionId: session.id,
+          parentSessionId: session.parentSessionId,
+          mode: context.mode,
+          createdAt: entry.createdAt,
+        });
+      } catch (err) {
+        return Response.json(
+          {
+            error:
+              err instanceof Error ? err.message : "Failed to create session",
+          },
+          { status: 500 }
+        );
+      }
+    },
+
+    "/api/ai/query": async (req: Request) => {
+      if (req.method !== "POST") {
+        return new Response("Method not allowed", { status: 405 });
+      }
+
+      const body = (await req.json()) as QueryRequest;
+      const { sessionId, prompt, contextUpdate } = body;
+
+      if (!sessionId || !prompt) {
+        return Response.json(
+          { error: "Missing sessionId or prompt" },
+          { status: 400 }
+        );
+      }
+
+      const entry = sessionManager.get(sessionId);
+      if (!entry) {
+        return Response.json(
+          { error: "Session not found" },
+          { status: 404 }
+        );
+      }
+
+      sessionManager.touch(sessionId);
+
+      // If context update provided, prepend it to the prompt
+      const effectivePrompt = contextUpdate
+        ? `[Context update: the user has made changes since this conversation started]\n${contextUpdate}\n\n${prompt}`
+        : prompt;
+
+      // Set label from first query if not already set
+      if (!entry.label) {
+        entry.label = prompt.slice(0, 80);
+      }
+
+      // Stream the response using Server-Sent Events (SSE)
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        async start(controller) {
+          try {
+            for await (const message of entry.session.query(effectivePrompt)) {
+              const data = JSON.stringify(message);
+              controller.enqueue(
+                encoder.encode(`data: ${data}\n\n`)
+              );
+            }
+            controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+          } catch (err) {
+            const errorMsg: AIMessage = {
+              type: "error",
+              error: err instanceof Error ? err.message : String(err),
+              code: "stream_error",
+            };
+            controller.enqueue(
+              encoder.encode(`data: ${JSON.stringify(errorMsg)}\n\n`)
+            );
+          } finally {
+            controller.close();
+          }
+        },
+      });
+
+      return new Response(stream, {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        },
+      });
+    },
+
+    "/api/ai/abort": async (req: Request) => {
+      if (req.method !== "POST") {
+        return new Response("Method not allowed", { status: 405 });
+      }
+
+      const body = (await req.json()) as AbortRequest;
+      const entry = sessionManager.get(body.sessionId);
+      if (!entry) {
+        return Response.json(
+          { error: "Session not found" },
+          { status: 404 }
+        );
+      }
+
+      entry.session.abort();
+      return Response.json({ ok: true });
+    },
+
+    "/api/ai/permission": async (req: Request) => {
+      if (req.method !== "POST") {
+        return new Response("Method not allowed", { status: 405 });
+      }
+
+      const body = (await req.json()) as {
+        sessionId: string;
+        requestId: string;
+        allow: boolean;
+        message?: string;
+      };
+
+      if (!body.sessionId || !body.requestId) {
+        return Response.json(
+          { error: "Missing sessionId or requestId" },
+          { status: 400 }
+        );
+      }
+
+      const entry = sessionManager.get(body.sessionId);
+      if (!entry) {
+        return Response.json(
+          { error: "Session not found" },
+          { status: 404 }
+        );
+      }
+
+      entry.session.respondToPermission?.(
+        body.requestId,
+        body.allow,
+        body.message
+      );
+
+      return Response.json({ ok: true });
+    },
+
+    "/api/ai/sessions": async (_req: Request) => {
+      const entries = sessionManager.list();
+      return Response.json(
+        entries.map((e) => ({
+          sessionId: e.session.id,
+          mode: e.mode,
+          parentSessionId: e.parentSessionId,
+          createdAt: e.createdAt,
+          lastActiveAt: e.lastActiveAt,
+          isActive: e.session.isActive,
+          label: e.label,
+        }))
+      );
+    },
+  } as const;
+}
+
+export type AIEndpoints = ReturnType<typeof createAIEndpoints>;