@plannotator/pi-extension 0.17.10 → 0.18.0

package/generated/ai/providers/opencode-sdk.ts

@@ -2,11 +2,13 @@
 /**
  * OpenCode provider — bridges Plannotator's AI layer with OpenCode's agent server.
  *
- * Uses @opencode-ai/sdk to spawn `opencode serve` and communicate via HTTP + SSE.
- * One server per provider, shared across all sessions. The user must have the
- * `opencode` CLI installed and authenticated.
+ * Uses @opencode-ai/sdk to connect to an existing `opencode serve` first and
+ * only spawns a new server when nothing is reachable. One server is shared
+ * across all sessions. The user must have the `opencode` CLI installed and
+ * authenticated.
  */
 
+import type { OpencodeClient } from "@opencode-ai/sdk";
 import { BaseSession } from "../base-session.ts";
 import { buildSystemPrompt } from "../context.ts";
 import type {
@@ -55,17 +57,17 @@ export class OpenCodeProvider implements AIProvider {
 	private config: OpenCodeConfig;
 	// biome-ignore lint/suspicious/noExplicitAny: SDK types not available at compile time
 	private server: { url: string; close: () => void } | null = null;
-	// biome-ignore lint/suspicious/noExplicitAny: SDK types not available at compile time
-	private client: any = null;
+	private client: OpencodeClient | null = null;
 	private startPromise: Promise<void> | null = null;
+	private lastAttachError: string | null = null;
 
 	constructor(config: OpenCodeConfig) {
 		this.config = config;
 	}
 
-	/** Lazy-spawn the OpenCode server and create the HTTP client. */
+	/** Attach to an existing OpenCode server or spawn one if needed. */
 	async ensureServer(): Promise<void> {
-		if (this.server && this.client) return;
+		if (this.client) return;
 		this.startPromise ??= this.doStart().catch((err) => {
 			this.startPromise = null;
 			throw err;
@@ -74,13 +76,27 @@ export class OpenCodeProvider implements AIProvider {
 	}
 
 	private async doStart(): Promise<void> {
+		this.lastAttachError = null;
 		const { createOpencodeServer, createOpencodeClient } = await getSDK();
+		const attachedClient = await this.tryAttachExistingServer(createOpencodeClient);
+		if (attachedClient) {
+			this.client = attachedClient;
+			return;
+		}
 
-		this.server = await createOpencodeServer({
-			hostname: this.config.hostname ?? "127.0.0.1",
-			...(this.config.port != null && { port: this.config.port }),
-			timeout: 15_000,
-		});
+		try {
+			this.server = await createOpencodeServer({
+				hostname: this.config.hostname ?? "127.0.0.1",
+				...(this.config.port != null && { port: this.config.port }),
+				timeout: 15_000,
+			});
+		} catch (err) {
+			const spawnMessage = err instanceof Error ? err.message : String(err);
+			if (this.lastAttachError) {
+				throw new Error(`${this.lastAttachError}\nFallback startup also failed: ${spawnMessage}`);
+			}
+			throw err;
+		}
 
 		this.client = createOpencodeClient({
 			baseUrl: this.server!.url,
@@ -88,18 +104,52 @@ export class OpenCodeProvider implements AIProvider {
 		});
 	}
 
+	private async tryAttachExistingServer(
+		createOpencodeClient: (config?: { baseUrl?: string; directory?: string }) => OpencodeClient,
+	): Promise<OpencodeClient | null> {
+		const cwd = this.config.cwd ?? process.cwd();
+		const baseUrl = `http://${this.config.hostname ?? "127.0.0.1"}:${this.config.port ?? 4096}`;
+		const client = createOpencodeClient({
+			baseUrl,
+			directory: cwd,
+		});
+
+		try {
+			await client.config.get({
+				throwOnError: true,
+				signal: AbortSignal.timeout(1_000),
+			});
+			return client;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			this.lastAttachError = `Failed to attach to existing OpenCode server at ${baseUrl}: ${message}`;
+			return null;
+		}
+	}
+
+	private getClient(): OpencodeClient {
+		if (!this.client) {
+			throw new Error("OpenCode client is not initialized.");
+		}
+		return this.client;
+	}
+
 	async createSession(options: CreateSessionOptions): Promise<AISession> {
 		await this.ensureServer();
+		const client = this.getClient();
 
-		const result = await this.client.session.create({
+		const result = await client.session.create({
 			query: { directory: options.cwd ?? this.config.cwd ?? process.cwd() },
 		});
 		const sessionData = result.data;
+		if (!sessionData) {
+			throw new Error("OpenCode did not return session data.");
+		}
 
 		const session = new OpenCodeSession({
 			sessionId: sessionData.id,
 			systemPrompt: buildSystemPrompt(options.context),
-			client: this.client,
+			client,
 			model: options.model,
 			parentSessionId: null,
 		});
@@ -108,21 +158,25 @@ export class OpenCodeProvider implements AIProvider {
 
 	async forkSession(options: CreateSessionOptions): Promise<AISession> {
 		await this.ensureServer();
+		const client = this.getClient();
 
 		const parentId = options.context.parent?.sessionId;
 		if (!parentId) {
 			throw new Error("Fork requires a parent session ID.");
 		}
 
-		const result = await this.client.session.fork({
+		const result = await client.session.fork({
 			path: { id: parentId },
 		});
 		const sessionData = result.data;
+		if (!sessionData) {
+			throw new Error("OpenCode did not return forked session data.");
+		}
 
 		return new OpenCodeSession({
 			sessionId: sessionData.id,
 			systemPrompt: buildSystemPrompt(options.context),
-			client: this.client,
+			client,
 			model: options.model,
 			parentSessionId: parentId,
 		});
@@ -130,14 +184,15 @@ export class OpenCodeProvider implements AIProvider {
 
 	async resumeSession(sessionId: string): Promise<AISession> {
 		await this.ensureServer();
+		const client = this.getClient();
 
 		// Verify session exists
-		await this.client.session.get({ path: { id: sessionId } });
+		await client.session.get({ path: { id: sessionId } });
 
 		return new OpenCodeSession({
 			sessionId,
 			systemPrompt: null,
-			client: this.client,
+			client,
 			model: undefined,
 			parentSessionId: null,
 		});
@@ -147,32 +202,33 @@ export class OpenCodeProvider implements AIProvider {
 		if (this.server) {
 			this.server.close();
 			this.server = null;
-			this.client = null;
-			this.startPromise = null;
 		}
+		this.client = null;
+		this.startPromise = null;
 	}
 
 	/** Fetch available models from OpenCode. Call before registering the provider. */
 	async fetchModels(): Promise<void> {
 		try {
 			await this.ensureServer();
+			const client = this.getClient();
 
-			const result = await this.client.provider.list({
+			const result = await client.provider.list({
 				query: { directory: this.config.cwd ?? process.cwd() },
 			});
 			const data = result.data;
-			const connected = new Set(data.connected as string[]);
-			const allProviders = data.all as Array<{
-				id: string;
-				models: Record<string, { id: string; providerID: string; name: string }>;
-			}>;
+			if (!data) {
+				return;
+			}
+			const connected = new Set(data.connected ?? []);
+			const allProviders = data.all ?? [];
 
 			const models: Array<{ id: string; label: string; default?: boolean }> = [];
 			for (const provider of allProviders) {
 				if (!connected.has(provider.id)) continue;
 				for (const model of Object.values(provider.models)) {
 					models.push({
-						id: `${model.providerID}/${model.id}`,
+						id: `${provider.id}/${model.id}`,
 						label: model.name ?? model.id,
 					});
 				}

package/generated/ai/types.ts

@@ -365,6 +365,6 @@ export interface OpenCodeConfig extends AIProviderConfig {
   type: "opencode-sdk";
   /** Hostname for the OpenCode server. Default: "127.0.0.1". */
   hostname?: string;
-  /** Port for the OpenCode server. Default: random. */
+  /** Port for the OpenCode server. Default: 4096. */
   port?: number;
 }

package/generated/resolve-file.ts

@@ -10,6 +10,7 @@
  * Used by both the CLI (`plannotator annotate`) and the `/api/doc` endpoint.
  */
 
+import { homedir } from "os";
 import { isAbsolute, join, resolve, win32 } from "path";
 import { existsSync, readdirSync, type Dirent } from "fs";
 
@@ -43,8 +44,93 @@ function stripTrailingSlashes(input: string): string {
 	return input.replace(/\/+$/, "");
 }
 
+export function expandHomePath(input: string, home = homedir()): string {
+	if (input === "~") {
+		return home;
+	}
+
+	if (input.startsWith("~/") || input.startsWith("~\\")) {
+		return join(home, input.slice(2));
+	}
+
+	return input;
+}
+
+function stripWrappingQuotes(input: string): string {
+	if (input.length < 2) {
+		return input;
+	}
+
+	const first = input[0];
+	const last = input[input.length - 1];
+	if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+		return input.slice(1, -1);
+	}
+
+	return input;
+}
+
+export function normalizeUserPathInput(
+	input: string,
+	platform = process.platform,
+): string {
+	const trimmedInput = input.trim();
+	const unquotedInput = stripWrappingQuotes(trimmedInput);
+	const expandedInput = expandHomePath(unquotedInput);
+
+	if (platform !== "win32") {
+		return expandedInput;
+	}
+
+	for (const pattern of WINDOWS_DRIVE_PATH_PATTERNS) {
+		const match = expandedInput.match(pattern);
+		if (!match) {
+			continue;
+		}
+
+		const [, driveLetter, rest] = match;
+		return `${driveLetter.toUpperCase()}:/${rest}`;
+	}
+
+	return expandedInput;
+}
+
+function isAbsoluteNormalizedUserPath(
+	input: string,
+	platform = process.platform,
+): boolean {
+	if (hasWindowsDriveLetter(input)) {
+		return true;
+	}
+
+	return platform === "win32"
+		? win32.isAbsolute(input)
+		: isAbsolute(input);
+}
+
+export function isAbsoluteUserPath(
+	input: string,
+	platform = process.platform,
+): boolean {
+	return isAbsoluteNormalizedUserPath(normalizeUserPathInput(input, platform), platform);
+}
+
+export function resolveUserPath(
+	input: string,
+	baseDir = process.cwd(),
+	platform = process.platform,
+): string {
+	const normalizedInput = normalizeUserPathInput(input, platform);
+	if (!normalizedInput) {
+		return "";
+	}
+	return isAbsoluteNormalizedUserPath(normalizedInput, platform)
+		? resolveAbsolutePath(normalizedInput, platform)
+		: resolve(baseDir, normalizedInput);
+}
+
 function normalizeComparablePath(input: string): string {
-	return stripTrailingSlashes(normalizeSeparators(resolve(input)));
+	return stripTrailingSlashes(normalizeSeparators(resolveUserPath(input)));
 }
 
 export function isWithinProjectRoot(candidate: string, projectRoot: string): boolean {
@@ -79,20 +165,6 @@ function isSearchableMarkdownPath(input: string): boolean {
 	return MARKDOWN_PATH_REGEX.test(input.trim());
 }
 
-function stripWrappingQuotes(input: string): string {
-	if (input.length < 2) {
-		return input;
-	}
-
-	const first = input[0];
-	const last = input[input.length - 1];
-	if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
-		return input.slice(1, -1);
-	}
-
-	return input;
-}
-
 /** Check if a path looks like a Windows absolute path (e.g. C:\ or C:/) */
 function hasWindowsDriveLetter(input: string): boolean {
 	return /^[a-zA-Z]:[/\\]/.test(input);
@@ -128,42 +200,6 @@ function walkMarkdownFiles(dir: string, root: string, results: string[], ignored
 	}
 }
 
-export function normalizeMarkdownPathInput(
-	input: string,
-	platform = process.platform,
-): string {
-	if (platform !== "win32") {
-		return input;
-	}
-
-	for (const pattern of WINDOWS_DRIVE_PATH_PATTERNS) {
-		const match = input.match(pattern);
-		if (!match) {
-			continue;
-		}
-
-		const [, driveLetter, rest] = match;
-		return `${driveLetter.toUpperCase()}:/${rest}`;
-	}
-
-	return input;
-}
-
-export function isAbsoluteMarkdownPath(
-	input: string,
-	platform = process.platform,
-): boolean {
-	const normalizedInput = normalizeMarkdownPathInput(input, platform);
-	// Always check for Windows drive letters (handles compiled Bun exes where
-	// process.platform may not reflect the actual OS correctly)
-	if (hasWindowsDriveLetter(normalizedInput)) {
-		return true;
-	}
-	return platform === "win32"
-		? win32.isAbsolute(normalizedInput)
-		: isAbsolute(normalizedInput);
-}
-
 /**
  * Resolve a markdown file path within a project root.
  *
@@ -174,7 +210,7 @@ function resolveMarkdownFileCore(
 	input: string,
 	projectRoot: string,
 ): ResolveResult {
-	const normalizedInput = normalizeMarkdownPathInput(input);
+	const normalizedInput = normalizeUserPathInput(input);
 	const searchInput = normalizeSeparators(normalizedInput);
 	const isBareFilename = !searchInput.includes("/");
 	const targetLookupKey = getLookupKey(searchInput, isBareFilename);
@@ -186,7 +222,7 @@ function resolveMarkdownFileCore(
 
 	// 1. Absolute path — use as-is (no project root restriction;
 	//    the user explicitly typed the full path)
-	if (isAbsoluteMarkdownPath(normalizedInput)) {
+	if (isAbsoluteNormalizedUserPath(normalizedInput)) {
 		const absolutePath = resolveAbsolutePath(normalizedInput);
 		if (fileExists(absolutePath)) {
 			return { kind: "found", path: absolutePath };

package/generated/storage.ts

@@ -12,6 +12,7 @@ import { homedir } from "os";
 import { join, resolve, sep } from "path";
 import { mkdirSync, writeFileSync, readFileSync, readdirSync, statSync, existsSync } from "fs";
 import { sanitizeTag } from "./project";
+import { resolveUserPath } from "./resolve-file";
 
 /**
  * Get the plan storage directory, creating it if needed.
@@ -21,16 +22,12 @@ import { sanitizeTag } from "./project";
 export function getPlanDir(customPath?: string | null): string {
   let planDir: string;
 
-  if (customPath) {
-    // Expand ~ to home directory
-    planDir = customPath.startsWith("~")
-      ? join(homedir(), customPath.slice(1))
-      : customPath;
+  if (customPath?.trim()) {
+    planDir = resolveUserPath(customPath);
   } else {
     planDir = join(homedir(), ".plannotator", "plans");
   }
 
-  planDir = resolve(planDir);
   mkdirSync(planDir, { recursive: true });
   return planDir;
 }

package/generated/url-to-markdown.ts

@@ -15,7 +15,7 @@ export interface UrlToMarkdownOptions {
 
 export interface UrlToMarkdownResult {
   markdown: string;
-  source: "jina" | "fetch+turndown" | "fetch-raw";
+  source: "jina" | "fetch+turndown" | "fetch-raw" | "content-negotiation";
 }
 
 const FETCH_TIMEOUT_MS = 30_000;
@@ -87,7 +87,17 @@ export async function urlToMarkdown(
     // Server returned HTML for this .md URL — fall through to normal conversion
   }
 
-  if (options.useJina && !isLocalUrl(url)) {
+  // Content negotiation fast path — if the server natively returns markdown
+  // (e.g. Cloudflare's Markdown for Agents), skip Jina/Turndown entirely.
+  const local = isLocalUrl(url);
+  if (!local) {
+    const negotiated = await fetchViaContentNegotiation(url);
+    if (negotiated !== null) {
+      return { markdown: negotiated, source: "content-negotiation" };
+    }
+  }
+
+  if (options.useJina && !local) {
     try {
       const markdown = await fetchViaJina(url);
       return { markdown, source: "jina" };
@@ -191,6 +201,57 @@ async function fetchRawText(url: string): Promise<string | null> {
   }
 }
 
+/**
+ * Content negotiation fast path — request `text/markdown` via the Accept header.
+ * Sites that support Cloudflare's "Markdown for Agents" (or similar) will return
+ * markdown directly, letting us skip Jina and Turndown entirely.
+ * Returns null if the server doesn't serve markdown.
+ */
+const NEGOTIATION_TIMEOUT_MS = 5_000; // Short timeout — this is a best-effort optimization
+
+async function fetchViaContentNegotiation(url: string): Promise<string | null> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), NEGOTIATION_TIMEOUT_MS);
+  const headers = {
+    "User-Agent": "Mozilla/5.0 (compatible; Plannotator/1.0; +https://plannotator.ai)",
+    Accept: "text/markdown, text/html;q=0.9",
+  };
+
+  try {
+    let currentUrl = url;
+    let res = await fetch(currentUrl, { headers, redirect: "manual", signal: controller.signal });
+
+    for (let i = 0; i < MAX_REDIRECTS && REDIRECT_STATUSES.has(res.status); i++) {
+      const location = res.headers.get("location");
+      if (!location) break;
+      currentUrl = new URL(location, currentUrl).href;
+      if (isLocalUrl(currentUrl)) {
+        res.body?.cancel();
+        return null;
+      }
+      res.body?.cancel();
+      res = await fetch(currentUrl, { headers, redirect: "manual", signal: controller.signal });
+    }
+
+    if (!res.ok) {
+      res.body?.cancel();
+      return null;
+    }
+
+    const ct = res.headers.get("content-type") || "";
+    if (!ct.includes("text/markdown")) {
+      res.body?.cancel();
+      return null;
+    }
+
+    return await readBodyWithLimit(res);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /** Fetch via Jina Reader — returns markdown directly. */
 async function fetchViaJina(url: string): Promise<string> {
   // Strip fragment (never sent to server) and encode for Jina's path-based API

package/index.ts

@@ -19,7 +19,7 @@
  */
 
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { resolve, basename } from "node:path";
+import { basename, resolve } from "node:path";
 import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
 import { Type } from "@mariozechner/pi-ai";
 import type {
@@ -34,7 +34,7 @@ import {
 	parseChecklist,
 } from "./generated/checklist.js";
 import { planDenyFeedback } from "./generated/feedback-templates.js";
-import { hasMarkdownFiles } from "./generated/resolve-file.js";
+import { hasMarkdownFiles, resolveUserPath } from "./generated/resolve-file.js";
 import { FILE_BROWSER_EXCLUDED } from "./generated/reference-common.js";
 import { htmlToMarkdown } from "./generated/html-to-markdown.js";
 import { urlToMarkdown } from "./generated/url-to-markdown.js";
@@ -417,7 +417,7 @@ export default function plannotator(pi: ExtensionAPI): void {
 				absolutePath = filePath;
 				sourceInfo = filePath;
 			} else {
-				absolutePath = resolve(ctx.cwd, filePath);
+				absolutePath = resolveUserPath(filePath, ctx.cwd);
 				if (!existsSync(absolutePath)) {
 					ctx.ui.notify(`File not found: ${absolutePath}`, "error");
 					return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/pi-extension",
-  "version": "0.17.10",
+  "version": "0.18.0",
   "type": "module",
   "description": "Plannotator extension for Pi coding agent - interactive plan review with visual annotation",
   "author": "backnotprop",
@@ -44,5 +44,11 @@
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": ">=0.53.0"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.53.0",
+    "@mariozechner/pi-agent-core": ">=0.53.0",
+    "@mariozechner/pi-ai": ">=0.53.0",
+    "@mariozechner/pi-tui": ">=0.53.0"
   }
 }

package/plannotator-browser.ts

@@ -356,6 +356,7 @@ export async function openCodeReview(
 		htmlContent: reviewHtmlContent,
 		sharingEnabled: process.env.PLANNOTATOR_SHARE !== "disabled",
 		shareBaseUrl: process.env.PLANNOTATOR_SHARE_URL || undefined,
+		pasteApiUrl: process.env.PLANNOTATOR_PASTE_URL || undefined,
 		onCleanup: worktreeCleanup,
 	});