@plannotator/pi-extension 0.15.0 → 0.15.2

package/generated/ai/types.ts

@@ -0,0 +1,370 @@
+// @generated — DO NOT EDIT. Source: packages/ai/types.ts
+/**
+ * Core types for the Plannotator AI provider layer.
+ *
+ * This module defines the abstract interfaces that any agent runtime
+ * (Claude Agent SDK, OpenCode, future providers) must implement to
+ * power AI features inside Plannotator's plan review and code review UIs.
+ */
+
+// ---------------------------------------------------------------------------
+// Context — what the AI session knows about
+// ---------------------------------------------------------------------------
+
+/** The surface the user is interacting with when they invoke AI. */
+export type AIContextMode = "plan-review" | "code-review" | "annotate";
+
+/**
+ * Describes the parent agent session that originally produced the plan or diff.
+ * Used to fork conversations with full history.
+ */
+export interface ParentSession {
+  /** Session ID from the host agent (e.g. Claude Code session UUID). */
+  sessionId: string;
+  /** Working directory the parent session was running in. */
+  cwd: string;
+}
+
+/**
+ * Snapshot of plan-review-specific context.
+ * Passed when AIContextMode is "plan-review".
+ */
+export interface PlanContext {
+  /** The full plan markdown as submitted by the agent. */
+  plan: string;
+  /** Previous plan version (if this is a resubmission). */
+  previousPlan?: string;
+  /** The version number in the plan's history. */
+  version?: number;
+  /** Annotations the user has made so far (serialised for the prompt). */
+  annotations?: string;
+}
+
+/**
+ * Snapshot of code-review-specific context.
+ * Passed when AIContextMode is "code-review".
+ */
+export interface CodeReviewContext {
+  /** The unified diff patch. */
+  patch: string;
+  /** The specific file being discussed (if scoped). */
+  filePath?: string;
+  /** The line range being discussed (if scoped). */
+  lineRange?: { start: number; end: number; side: "old" | "new" };
+  /** The code snippet being discussed (if scoped). */
+  selectedCode?: string;
+  /** Summary of annotations the user has made. */
+  annotations?: string;
+}
+
+/**
+ * Snapshot of annotate-mode context.
+ * Passed when AIContextMode is "annotate".
+ */
+export interface AnnotateContext {
+  /** The markdown file content being annotated. */
+  content: string;
+  /** Path to the file on disk. */
+  filePath: string;
+  /** Summary of annotations the user has made. */
+  annotations?: string;
+}
+
+/**
+ * Union of mode-specific contexts, discriminated by `mode`.
+ */
+export type AIContext =
+  | { mode: "plan-review"; plan: PlanContext; parent?: ParentSession }
+  | { mode: "code-review"; review: CodeReviewContext; parent?: ParentSession }
+  | { mode: "annotate"; annotate: AnnotateContext; parent?: ParentSession };
+
+// ---------------------------------------------------------------------------
+// Messages — what streams back from the AI
+// ---------------------------------------------------------------------------
+
+export interface AITextMessage {
+  type: "text";
+  text: string;
+}
+
+export interface AITextDeltaMessage {
+  type: "text_delta";
+  delta: string;
+}
+
+export interface AIToolUseMessage {
+  type: "tool_use";
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  toolUseId: string;
+}
+
+export interface AIToolResultMessage {
+  type: "tool_result";
+  toolUseId?: string;
+  result: string;
+}
+
+export interface AIErrorMessage {
+  type: "error";
+  error: string;
+  code?: string;
+}
+
+export interface AIResultMessage {
+  type: "result";
+  sessionId: string;
+  success: boolean;
+  /** The final text result (if success). */
+  result?: string;
+  /** Total cost in USD (if available). */
+  costUsd?: number;
+  /** Number of agentic turns used. */
+  turns?: number;
+}
+
+export interface AIPermissionRequestMessage {
+  type: "permission_request";
+  requestId: string;
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  title?: string;
+  displayName?: string;
+  description?: string;
+  toolUseId: string;
+}
+
+export interface AIUnknownMessage {
+  type: "unknown";
+  /** The raw message from the provider, for debugging/transparency. */
+  raw: Record<string, unknown>;
+}
+
+export type AIMessage =
+  | AITextMessage
+  | AITextDeltaMessage
+  | AIToolUseMessage
+  | AIToolResultMessage
+  | AIErrorMessage
+  | AIResultMessage
+  | AIPermissionRequestMessage
+  | AIUnknownMessage;
+
+// ---------------------------------------------------------------------------
+// Session — a live conversation with the AI
+// ---------------------------------------------------------------------------
+
+export interface AISession {
+  /** Unique identifier for this session. */
+  readonly id: string;
+
+  /**
+   * The parent session this was forked from, if any.
+   * Null for fresh sessions.
+   */
+  readonly parentSessionId: string | null;
+
+  /**
+   * Send a prompt and stream back messages.
+   * The returned async iterable yields messages as they arrive.
+   */
+  query(prompt: string): AsyncIterable<AIMessage>;
+
+  /**
+   * Abort the current in-flight query.
+   * Safe to call if no query is running (no-op).
+   */
+  abort(): void;
+
+  /** Whether a query is currently in progress. */
+  readonly isActive: boolean;
+
+  /**
+   * Respond to a permission request from the provider.
+   * Called when the user approves or denies a tool use in the UI.
+   */
+  respondToPermission?(requestId: string, allow: boolean, message?: string): void;
+
+  /**
+   * Callback invoked when the real session ID is resolved from the provider.
+   * Set by the SessionManager to remap its internal tracking key.
+   */
+  onIdResolved?: (oldId: string, newId: string) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Provider — the pluggable backend
+// ---------------------------------------------------------------------------
+
+export interface AIProviderCapabilities {
+  /** Whether the provider supports forking from a parent session. */
+  fork: boolean;
+  /** Whether the provider supports resuming a prior session by ID. */
+  resume: boolean;
+  /** Whether the provider streams partial text deltas. */
+  streaming: boolean;
+  /** Whether the provider can execute tools (read files, search, etc.). */
+  tools: boolean;
+}
+
+export interface CreateSessionOptions {
+  /** The context (plan, diff, file) to seed the session with. */
+  context: AIContext;
+  /**
+   * Working directory override for the agent session.
+   * Falls back to the provider's configured cwd if omitted.
+   */
+  cwd?: string;
+  /**
+   * Model override. Provider-specific string.
+   * Falls back to provider default if omitted.
+   */
+  model?: string;
+  /**
+   * Maximum agentic turns for the session.
+   * Keeps inline chat cost-bounded.
+   */
+  maxTurns?: number;
+  /**
+   * Maximum budget in USD for this session.
+   */
+  maxBudgetUsd?: number;
+  /**
+   * Reasoning effort level (Codex only).
+   * Controls how much thinking the model does before responding.
+   */
+  reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
+}
+
+/**
+ * An AI provider implements the bridge between Plannotator and a specific
+ * agent runtime. The provider is responsible for:
+ *
+ * 1. Creating new AI sessions seeded with review context
+ * 2. Forking from parent agent sessions to maintain conversation history
+ * 3. Streaming responses back as AIMessage events
+ *
+ * Providers are registered by name and selected at runtime based on the
+ * host environment (Claude Code → "claude-agent-sdk", OpenCode → "opencode-sdk").
+ */
+export interface AIProvider {
+  /** Unique name for this provider (e.g. "claude-agent-sdk"). */
+  readonly name: string;
+
+  /** What this provider can do. */
+  readonly capabilities: AIProviderCapabilities;
+
+  /** Available models for this provider. */
+  readonly models?: ReadonlyArray<{ id: string; label: string; default?: boolean }>;
+
+  /**
+   * Create a fresh session (no parent history).
+   * Context is injected via the system prompt.
+   */
+  createSession(options: CreateSessionOptions): Promise<AISession>;
+
+  /**
+   * Fork from a parent agent session.
+   *
+   * The new session inherits the parent's full conversation history
+   * (files read, analysis performed, decisions made) and additionally
+   * receives the Plannotator review context. This enables the user to
+   * ask contextual questions like "why did you change this function?"
+   * without the AI losing insight.
+   *
+   * Providers that don't support real forking MUST throw. The endpoint
+   * layer checks `capabilities.fork` before calling this, so it should
+   * only be reached by providers that genuinely support history inheritance.
+   */
+  forkSession(options: CreateSessionOptions): Promise<AISession>;
+
+  /**
+   * Resume a previously created Plannotator AI session by its ID.
+   * Used when the user returns to a conversation they started earlier.
+   *
+   * If the provider doesn't support resuming, this should throw.
+   */
+  resumeSession(sessionId: string): Promise<AISession>;
+
+  /**
+   * Clean up any resources held by the provider.
+   * Called when the server shuts down.
+   */
+  dispose(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Provider configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration passed to a provider factory.
+ * Each provider type may extend this with its own fields.
+ */
+export interface AIProviderConfig {
+  /** Provider type identifier (matches AIProvider.name). */
+  type: string;
+  /** Working directory for the agent. */
+  cwd?: string;
+  /** Default model to use. */
+  model?: string;
+}
+
+export interface ClaudeAgentSDKConfig extends AIProviderConfig {
+  type: "claude-agent-sdk";
+  /**
+   * Tools the AI session is allowed to use.
+   * Defaults to read-only tools for safety in inline chat.
+   */
+  allowedTools?: string[];
+  /**
+   * Permission mode for the session.
+   * Defaults to "default" (inherits user's existing permission rules).
+   */
+  permissionMode?: "default" | "plan" | "bypassPermissions";
+  /**
+   * Explicit path to the claude CLI binary.
+   * Required when running inside a compiled binary where PATH resolution
+   * doesn't work the same way (e.g., bun build --compile).
+   */
+  claudeExecutablePath?: string;
+  /**
+   * Setting sources to load permission rules from.
+   * Loads user's existing Claude Code permission rules so inline chat
+   * inherits what they've already approved.
+   */
+  settingSources?: string[];
+}
+
+export interface CodexSDKConfig extends AIProviderConfig {
+  type: "codex-sdk";
+  /**
+   * Sandbox mode controls what the Codex agent can do.
+   * Defaults to "read-only" for safety in inline chat.
+   */
+  sandboxMode?: "read-only" | "workspace-write" | "danger-full-access";
+  /**
+   * Explicit path to the codex CLI binary.
+   * Required when running inside a compiled binary where PATH resolution
+   * doesn't work the same way (e.g., bun build --compile).
+   */
+  codexExecutablePath?: string;
+}
+
+export interface PiSDKConfig extends AIProviderConfig {
+  type: "pi-sdk";
+  /**
+   * Explicit path to the pi CLI binary.
+   * Required when running inside a compiled binary where PATH resolution
+   * doesn't work the same way (e.g., bun build --compile).
+   */
+  piExecutablePath?: string;
+}
+
+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?: number;
+}

package/generated/resolve-file.ts

@@ -218,3 +218,31 @@ export function resolveMarkdownFile(
 
 	return { kind: "not_found", input };
 }
+
+/**
+ * Check if a directory contains at least one markdown file.
+ * Used to validate folder annotation targets.
+ *
+ * @param dirPath - Directory to search
+ * @param excludedDirs - Directory names to skip (with trailing slash, e.g. "node_modules/")
+ */
+export function hasMarkdownFiles(dirPath: string, excludedDirs: string[] = IGNORED_DIRS): boolean {
+	function walk(dir: string): boolean {
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return false;
+		}
+		for (const entry of entries) {
+			if (entry.isDirectory()) {
+				if (excludedDirs.some((d) => d === entry.name + "/")) continue;
+				if (walk(join(dir, entry.name))) return true;
+			} else if (entry.isFile() && /\.mdx?$/i.test(entry.name)) {
+				return true;
+			}
+		}
+		return false;
+	}
+	return walk(dirPath);
+}