pi-var 1.0.1

package/extensions/pi-var/src/tools/command/index.ts

@@ -0,0 +1,95 @@
+/**
+ * /var command registration
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { VarRuntime } from '../../types/index';
+import type { RuntimeStore } from '../../state/types';
+import { handleStatus, handleList } from './status';
+import { handleCleanStale, handleCleanSpecific } from './clean';
+import { handleStop } from './stop';
+
+/** Dependencies for command handlers */
+interface CommandDeps {
+  pi: ExtensionAPI;
+  getRuntime: (ctx: ExtensionContext) => VarRuntime;
+  runtimeStore: RuntimeStore;
+}
+
+/**
+ * Register the /var command (argument-free, status/overview)
+ */
+export function registerVarCommand(pi: ExtensionAPI, deps: CommandDeps): void {
+  const { getRuntime, runtimeStore } = deps;
+
+  pi.registerCommand('var', {
+    description: 'Show variation status and provide manual override commands',
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const trimmed = args.trim();
+      const parts = trimmed.split(/\s+/);
+      const subcommand = parts[0] || '';
+
+      const runtime = getRuntime(ctx);
+
+      // Parse flags
+      const staleMatch = trimmed.match(/--stale\s+(\d+)/);
+      const staleDays = staleMatch ? parseInt(staleMatch[1], 10) : null;
+
+      try {
+        // No args = status overview
+        if (!trimmed) {
+          handleStatus(runtime, ctx);
+          return;
+        }
+
+        // Manual subcommands (power user features)
+        switch (subcommand) {
+          case 'list': {
+            handleList(runtime, ctx);
+            break;
+          }
+
+          case 'clean': {
+            // Handle --stale flag
+            if (staleDays) {
+              await handleCleanStale(runtime, ctx, staleDays, runtimeStore, pi);
+              return;
+            }
+
+            // Clean specific variation
+            const name = parts[1];
+            if (!name) {
+              ctx.ui.notify('Usage: /var clean <name> or /var clean --stale <days>', 'warning');
+              return;
+            }
+
+            await handleCleanSpecific(runtime, ctx, name, runtimeStore, pi);
+            break;
+          }
+
+          case 'stop':
+          case 'main': {
+            handleStop(runtime, ctx, runtimeStore, pi);
+            break;
+          }
+
+          default: {
+            ctx.ui.notify(
+              `Unknown: ${subcommand}\n\n` +
+                'Usage:\n' +
+                '  /var                    Show status\n' +
+                '  /var list               List variations\n' +
+                '  /var clean <name>       Delete variation\n' +
+                '  /var clean --stale <d>  Delete variations older than d days\n' +
+                '  /var stop               Return to source (deactivate)',
+              'warning'
+            );
+          }
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`Error: ${message}`, 'error');
+      }
+    },
+  });
+}

package/extensions/pi-var/src/tools/command/status.ts

@@ -0,0 +1,58 @@
+/**
+ * /var command status handlers
+ */
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { VarRuntime } from '../../types/index';
+
+export function handleStatus(runtime: VarRuntime, ctx: ExtensionContext): void {
+  if (runtime.state.variations.length === 0) {
+    ctx.ui.notify(
+      'No active variations.\n\n' +
+        'The AI creates variations automatically via the create_variation tool ' +
+        'when parallel or isolated work is needed.',
+      'info'
+    );
+    return;
+  }
+
+  const lines = runtime.state.variations.map((v) => {
+    const isActive = v.id === runtime.state.activeVariationId;
+    const indicator = isActive ? '🌿 ' : '   ';
+    const typeIcon = v.type === 'cow' ? '⚡' : v.type === 'worktree' ? 'Git' : 'Copy';
+    const branchInfo = v.branchName ? ` → ${v.branchName}` : '';
+    return `${indicator}${v.name} [${typeIcon}]${branchInfo}`;
+  });
+
+  const active = runtime.state.activeVariationId
+    ? runtime.state.variations.find((v) => v.id === runtime.state.activeVariationId)
+    : null;
+
+  const branchDetail = active?.branchName
+    ? `\nBranch: ${active.branchName}` +
+      (active.mergeBaseCommit ? ` (base: ${active.mergeBaseCommit.slice(0, 8)})` : '')
+    : '';
+
+  const header = active
+    ? `Active variation: "${active.name}"\nAll operations redirect to: ${active.path}${branchDetail}\n`
+    : 'No active variation (working in source)';
+
+  ctx.ui.notify(`${header}\n\nVariations:\n${lines.join('\n')}`, 'info');
+}
+
+export function handleList(runtime: VarRuntime, ctx: ExtensionContext): void {
+  if (runtime.state.variations.length === 0) {
+    ctx.ui.notify('No variations yet. The AI creates them via create_variation tool.', 'info');
+    return;
+  }
+
+  const lines = runtime.state.variations.map((v) => {
+    const isActive = v.id === runtime.state.activeVariationId;
+    const indicator = isActive ? '🌿 ' : '   ';
+    const typeIcon = v.type === 'cow' ? '⚡' : v.type === 'worktree' ? 'Git' : 'Copy';
+    const branchInfo = v.branchName ? ` → ${v.branchName}` : '';
+    return `${indicator}${v.name} [${typeIcon}]${branchInfo}`;
+  });
+
+  ctx.ui.notify(`Variations:\n${lines.join('\n')}`, 'info');
+}

package/extensions/pi-var/src/tools/command/stop.ts

@@ -0,0 +1,37 @@
+/**
+ * /var command stop/main handler
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { VarRuntime } from '../../types/index';
+import type { RuntimeStore } from '../../state/types';
+
+function getSessionKey(ctx: ExtensionContext): string {
+  return ctx.sessionManager.getSessionId?.() || 'default';
+}
+
+export function handleStop(
+  runtime: VarRuntime,
+  ctx: ExtensionContext,
+  runtimeStore: RuntimeStore,
+  pi: ExtensionAPI
+): void {
+  // Deactivate current variation (return to source)
+  if (runtime.state.activeVariationId) {
+    const variation = runtime.state.variations.find(
+      (v) => v.id === runtime.state.activeVariationId
+    );
+    runtime.state.activeVariationId = null;
+    ctx.ui.setStatus('pi-var', '');
+
+    // Persist the "stop" state to session
+    runtimeStore.persistState(getSessionKey(ctx), pi);
+
+    ctx.ui.notify(
+      variation ? `Left variation "${variation.name}" — now in source` : 'Now in source directory',
+      'info'
+    );
+  } else {
+    ctx.ui.notify('Already in source directory', 'info');
+  }
+}

package/extensions/pi-var/src/tools/file-redirect.ts

@@ -0,0 +1,126 @@
+/**
+ * File Redirection Tools for pi-var
+ *
+ * Provides redirected file operations that automatically route read, edit, and write
+ * calls to the active variation directory when a variation is active.
+ *
+ * Path resolution logic:
+ * - If no active variation: return inputPath unchanged
+ * - If absolute path in source: redirect to variation
+ * - If absolute path already in variation: keep as-is
+ * - If relative path: resolve against variation path
+ */
+
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import type { VarRuntime, VarState, Variation } from '../types/index';
+
+/**
+ * Resolve a path to the variation directory when redirection is active
+ *
+ * @param inputPath - The original path (relative or absolute)
+ * @param cwd - Current working directory
+ * @param state - The current VarState containing active variation info
+ * @returns The resolved path (redirected to variation if active)
+ */
+export function resolveVariationPath(inputPath: string, cwd: string, state: VarState): string {
+  // No active variation - return path unchanged
+  if (!state.activeVariationId) {
+    return inputPath;
+  }
+
+  const variation = state.variations.find((v) => v.id === state.activeVariationId);
+  if (!variation) {
+    return inputPath;
+  }
+
+  // Handle absolute paths
+  if (path.isAbsolute(inputPath)) {
+    // Check if already in variation directory
+    const relativeToVariation = path.relative(variation.path, inputPath);
+    if (!relativeToVariation.startsWith('..') && !path.isAbsolute(relativeToVariation)) {
+      // Already in variation path - keep as-is
+      return inputPath;
+    }
+
+    // Check if in source directory
+    const relativeToSource = path.relative(variation.sourcePath, inputPath);
+    if (!relativeToSource.startsWith('..') && !path.isAbsolute(relativeToSource)) {
+      // In source - redirect to variation
+      return path.join(variation.path, relativeToSource);
+    }
+
+    // External file (outside both source and variation) - keep as-is
+    return inputPath;
+  }
+
+  // Relative path - resolve against variation path
+  return path.join(variation.path, inputPath);
+}
+
+/**
+ * Create read operations that redirect to the variation directory when active
+ */
+export function createRedirectedReadOps(cwd: string, runtime: VarRuntime) {
+  return {
+    readFile: async (filePath: string): Promise<Buffer> => {
+      const resolvedPath = resolveVariationPath(filePath, cwd, runtime.state);
+      return fs.readFile(resolvedPath);
+    },
+
+    access: async (filePath: string, mode?: number): Promise<void> => {
+      const resolvedPath = resolveVariationPath(filePath, cwd, runtime.state);
+      return fs.access(resolvedPath, mode);
+    },
+
+    detectImageMimeType: async (filePath: string): Promise<string | null | undefined> => {
+      const resolvedPath = resolveVariationPath(filePath, cwd, runtime.state);
+      try {
+        const ext = path.extname(resolvedPath).toLowerCase();
+        const mimeTypes: Record<string, string> = {
+          '.jpg': 'image/jpeg',
+          '.jpeg': 'image/jpeg',
+          '.png': 'image/png',
+          '.gif': 'image/gif',
+          '.webp': 'image/webp',
+        };
+        return mimeTypes[ext] || null;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Create write operations that redirect to the variation directory when active
+ */
+export function createRedirectedWriteOps(cwd: string, runtime: VarRuntime) {
+  return {
+    writeFile: async (filePath: string, content: string | Buffer): Promise<void> => {
+      const resolvedPath = resolveVariationPath(filePath, cwd, runtime.state);
+      // Ensure parent directory exists
+      await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
+      await fs.writeFile(resolvedPath, content);
+    },
+
+    mkdir: async (dirPath: string, options?: { recursive?: boolean }): Promise<void> => {
+      const resolvedPath = resolveVariationPath(dirPath, cwd, runtime.state);
+      await fs.mkdir(resolvedPath, options);
+    },
+  };
+}
+
+/**
+ * Create edit operations that redirect to the variation directory when active
+ */
+export function createRedirectedEditOps(cwd: string, runtime: VarRuntime) {
+  const readOps = createRedirectedReadOps(cwd, runtime);
+  const writeOps = createRedirectedWriteOps(cwd, runtime);
+
+  return {
+    readFile: readOps.readFile,
+    access: readOps.access,
+    writeFile: writeOps.writeFile,
+  };
+}

package/extensions/pi-var/src/tools/redirect/bash.ts

@@ -0,0 +1,75 @@
+/**
+ * Bash tool override for variation redirection
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  AgentToolUpdateCallback,
+} from '@earendil-works/pi-coding-agent';
+import {
+  createBashTool,
+  type BashSpawnContext,
+  type BashToolInput,
+} from '@earendil-works/pi-coding-agent';
+import type { VarRuntime } from '../../types/index';
+
+export function createBashHandler(
+  getRuntime: (ctx: ExtensionContext) => VarRuntime,
+  getDefaultTools: (cwd: string) => {
+    bash: ReturnType<typeof createBashTool>;
+  }
+) {
+  return {
+    name: 'bash' as const,
+    label: 'bash',
+    description:
+      'Execute a bash command. Returns stdout and stderr. ' +
+      'Output is truncated to last 2000 lines or 50KB (whichever is hit first). ' +
+      'When in a variation, executes in the variation directory.',
+    parameters: createBashTool('').parameters,
+
+    async execute(
+      toolCallId: string,
+      params: BashToolInput,
+      signal: AbortSignal,
+      onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+      ctx: ExtensionContext
+    ) {
+      const runtime = getRuntime(ctx);
+
+      // No active variation - use default behavior with ctx.cwd
+      if (!runtime.state.activeVariationId) {
+        const tools = getDefaultTools(ctx.cwd);
+        return tools.bash.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Get active variation
+      const variation = runtime.state.variations.find(
+        (v) => v.id === runtime.state.activeVariationId
+      );
+
+      if (!variation) {
+        const tools = getDefaultTools(ctx.cwd);
+        return tools.bash.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Create bash tool with variation as cwd and spawn hook for env vars
+      const tool = createBashTool(variation.path, {
+        spawnHook: (context: BashSpawnContext): BashSpawnContext => ({
+          ...context,
+          cwd: variation.path,
+          env: {
+            ...context.env,
+            PI_VARIATION: variation.name,
+            PI_VARIATION_PATH: variation.path,
+            PI_SOURCE_PATH: variation.sourcePath,
+            PI_VARIATION_TYPE: variation.type,
+          },
+        }),
+      });
+
+      return tool.execute(toolCallId, params, signal, onUpdate);
+    },
+  };
+}

package/extensions/pi-var/src/tools/redirect/edit.ts

@@ -0,0 +1,60 @@
+/**
+ * Edit tool override for variation redirection
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  AgentToolUpdateCallback,
+} from '@earendil-works/pi-coding-agent';
+import { createEditTool, type EditToolInput } from '@earendil-works/pi-coding-agent';
+import type { VarRuntime } from '../../types/index';
+import { createRedirectedEditOps } from '../file-redirect';
+
+export function createEditHandler(
+  getRuntime: (ctx: ExtensionContext) => VarRuntime,
+  getDefaultTools: (cwd: string) => {
+    edit: ReturnType<typeof createEditTool>;
+  }
+) {
+  return {
+    name: 'edit' as const,
+    label: 'edit',
+    description:
+      'Edit a file by replacing exact text. The oldText must match exactly ' +
+      '(including whitespace). Use this for precise, surgical edits. ' +
+      'When in a variation, edits in the variation directory.',
+    parameters: createEditTool('').parameters,
+
+    async execute(
+      toolCallId: string,
+      params: EditToolInput,
+      signal: AbortSignal,
+      onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+      ctx: ExtensionContext
+    ) {
+      const runtime = getRuntime(ctx);
+
+      // No active variation - use default behavior
+      if (!runtime.state.activeVariationId) {
+        const tools = getDefaultTools(ctx.cwd);
+        return tools.edit.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Get active variation
+      const variation = runtime.state.variations.find(
+        (v) => v.id === runtime.state.activeVariationId
+      );
+
+      if (!variation) {
+        const tools = getDefaultTools(ctx.cwd);
+        return tools.edit.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Create tool with redirected operations
+      const ops = createRedirectedEditOps(ctx.cwd, runtime);
+      const tool = createEditTool(ctx.cwd, { operations: ops });
+      return tool.execute(toolCallId, params, signal, onUpdate);
+    },
+  };
+}

package/extensions/pi-var/src/tools/redirect/index.ts

@@ -0,0 +1,64 @@
+/**
+ * Redirected tools registration module
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import {
+  createReadTool,
+  createEditTool,
+  createWriteTool,
+  createBashTool,
+} from '@earendil-works/pi-coding-agent';
+import type { VarRuntime } from '../../types/index';
+import { createReadHandler } from './read';
+import { createEditHandler } from './edit';
+import { createWriteHandler } from './write';
+import { createBashHandler } from './bash';
+
+/**
+ * Get runtime function type
+ */
+type GetRuntime = (ctx: ExtensionContext) => VarRuntime;
+
+/**
+ * Register redirected file tools (read, edit, write) and bash tool.
+ * These override the built-in tools to redirect operations to the active variation
+ * when a variation is active.
+ */
+export function registerRedirectedTools(pi: ExtensionAPI, getRuntime: GetRuntime): void {
+  // Cache for default tools by cwd to avoid recreating
+  const defaultTools = new Map<
+    string,
+    {
+      read: ReturnType<typeof createReadTool>;
+      edit: ReturnType<typeof createEditTool>;
+      write: ReturnType<typeof createWriteTool>;
+      bash: ReturnType<typeof createBashTool>;
+    }
+  >();
+
+  function getDefaultTools(cwd: string) {
+    let tools = defaultTools.get(cwd);
+    if (!tools) {
+      tools = {
+        read: createReadTool(cwd),
+        edit: createEditTool(cwd),
+        write: createWriteTool(cwd),
+        bash: createBashTool(cwd),
+      };
+      defaultTools.set(cwd, tools);
+    }
+    return tools;
+  }
+
+  // Register all redirected tools
+  const readTool = createReadHandler(getRuntime, getDefaultTools);
+  const editTool = createEditHandler(getRuntime, getDefaultTools);
+  const writeTool = createWriteHandler(getRuntime, getDefaultTools);
+  const bashTool = createBashHandler(getRuntime, getDefaultTools);
+
+  pi.registerTool(readTool);
+  pi.registerTool(editTool);
+  pi.registerTool(writeTool);
+  pi.registerTool(bashTool);
+}

package/extensions/pi-var/src/tools/redirect/read.ts

@@ -0,0 +1,61 @@
+/**
+ * Read tool override for variation redirection
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  AgentToolUpdateCallback,
+} from '@earendil-works/pi-coding-agent';
+import { createReadTool, type ReadToolInput } from '@earendil-works/pi-coding-agent';
+import type { VarRuntime } from '../../types/index';
+import { createRedirectedReadOps } from '../file-redirect';
+
+export function createReadHandler(
+  getRuntime: (ctx: ExtensionContext) => VarRuntime,
+  getDefaultTools: (cwd: string) => {
+    read: ReturnType<typeof createReadTool>;
+  }
+) {
+  return {
+    name: 'read' as const,
+    label: 'read',
+    description:
+      'Read the contents of a file. Supports text files and images (jpg, png, gif, webp). ' +
+      'Images are sent as attachments. For text files, output is truncated to 2000 lines ' +
+      'or 50KB (whichever is hit first). Use offset/limit for large files. ' +
+      'When in a variation, reads from the variation directory.',
+    parameters: createReadTool('').parameters,
+
+    async execute(
+      toolCallId: string,
+      params: ReadToolInput,
+      signal: AbortSignal,
+      onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+      ctx: ExtensionContext
+    ) {
+      const runtime = getRuntime(ctx);
+
+      // No active variation - use default behavior
+      if (!runtime.state.activeVariationId) {
+        const tools = getDefaultTools(ctx.cwd);
+        return tools.read.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Get active variation
+      const variation = runtime.state.variations.find(
+        (v) => v.id === runtime.state.activeVariationId
+      );
+
+      if (!variation) {
+        const tools = getDefaultTools(ctx.cwd);
+        return tools.read.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Create tool with redirected operations
+      const ops = createRedirectedReadOps(ctx.cwd, runtime);
+      const tool = createReadTool(ctx.cwd, { operations: ops });
+      return tool.execute(toolCallId, params, signal, onUpdate);
+    },
+  };
+}

package/extensions/pi-var/src/tools/redirect/write.ts

@@ -0,0 +1,60 @@
+/**
+ * Write tool override for variation redirection
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  AgentToolUpdateCallback,
+} from '@earendil-works/pi-coding-agent';
+import { createWriteTool, type WriteToolInput } from '@earendil-works/pi-coding-agent';
+import type { VarRuntime } from '../../types/index';
+import { createRedirectedWriteOps } from '../file-redirect';
+
+export function createWriteHandler(
+  getRuntime: (ctx: ExtensionContext) => VarRuntime,
+  getDefaultTools: (cwd: string) => {
+    write: ReturnType<typeof createWriteTool>;
+  }
+) {
+  return {
+    name: 'write' as const,
+    label: 'write',
+    description:
+      'Write content to a file. Creates the file if it does not exist, overwrites if it does. ' +
+      'Automatically creates parent directories. ' +
+      'When in a variation, writes to the variation directory.',
+    parameters: createWriteTool('').parameters,
+
+    async execute(
+      toolCallId: string,
+      params: WriteToolInput,
+      signal: AbortSignal,
+      onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+      ctx: ExtensionContext
+    ) {
+      const runtime = getRuntime(ctx);
+
+      // No active variation - use default behavior
+      if (!runtime.state.activeVariationId) {
+        const tools = getDefaultTools(ctx.cwd);
+        return tools.write.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Get active variation
+      const variation = runtime.state.variations.find(
+        (v) => v.id === runtime.state.activeVariationId
+      );
+
+      if (!variation) {
+        const tools = getDefaultTools(ctx.cwd);
+        return tools.write.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Create tool with redirected operations
+      const ops = createRedirectedWriteOps(ctx.cwd, runtime);
+      const tool = createWriteTool(ctx.cwd, { operations: ops });
+      return tool.execute(toolCallId, params, signal, onUpdate);
+    },
+  };
+}