pi-git-delegate 0.2.0

package/lib/register-commands.ts

@@ -0,0 +1,57 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadGitDelegateConfig } from "./config.ts";
+import {
+  buildConfigureHelp,
+  formatGitDelegateConfig,
+  promptForGitDelegateConfig,
+  resolveWritableSettingsPath,
+  writeGitDelegateSettings,
+} from "./settings-help.ts";
+
+export const GIT_DELEGATE_COMMANDS = [
+  { name: "git-delegate:configure", description: "Help set up pi-git-delegate models in .pi/settings.json" },
+  { name: "git-delegate:status", description: "Show current pi-git-delegate model routing settings" },
+] as const;
+
+export function registerGitDelegateCommands(pi: ExtensionAPI): void {
+  for (const command of GIT_DELEGATE_COMMANDS) {
+    pi.registerCommand(command.name, {
+      description: command.description,
+      handler: async (_args, ctx) => {
+        if (command.name === "git-delegate:status") {
+          const config = loadGitDelegateConfig(ctx.cwd);
+          const message = buildConfigureHelp(ctx.cwd, config);
+          ctx.ui.notify(message, "info");
+          return;
+        }
+
+        const config = loadGitDelegateConfig(ctx.cwd);
+        ctx.ui.notify(buildConfigureHelp(ctx.cwd, config), "info");
+
+        if (!ctx.hasUI) {
+          ctx.ui.notify("Interactive save requires UI support. Copy the JSON above into .pi/settings.json.", "warning");
+          return;
+        }
+
+        const target = resolveWritableSettingsPath(ctx.cwd);
+        const nextConfig = await promptForGitDelegateConfig(ctx.ui, config ?? undefined);
+        if (!nextConfig) {
+          ctx.ui.notify("Settings not saved.", "info");
+          return;
+        }
+
+        const save = await ctx.ui.confirm(
+          "Save pi-git-delegate settings?",
+          `${target.path}\n\n${formatGitDelegateConfig(nextConfig)}`,
+        );
+        if (!save) {
+          ctx.ui.notify("Settings not saved.", "info");
+          return;
+        }
+
+        writeGitDelegateSettings(target.path, nextConfig);
+        ctx.ui.notify(`Saved pi-git-delegate settings to ${target.path}`, "info");
+      },
+    });
+  }
+}

package/lib/register-tools.ts

@@ -0,0 +1,77 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { executeGitBlameSummary } from "./tools/git-blame-summary.ts";
+import { executeGitDiffSummary } from "./tools/git-diff-summary.ts";
+import { executeGitLogSummary } from "./tools/git-log-summary.ts";
+
+const modelOverrideParameters = {
+  provider: Type.Optional(Type.String({ description: "Override provider for this call." })),
+  model: Type.Optional(Type.String({ description: "Override model for this call." })),
+};
+
+const gitDiffSummaryParameters = Type.Object({
+  ref: Type.Optional(Type.String({ description: 'Git ref to diff against (default: "HEAD").' })),
+  ...modelOverrideParameters,
+});
+
+const gitLogSummaryParameters = Type.Object({
+  range: Type.Optional(Type.String({ description: 'Git log range (default: "HEAD~10..HEAD").' })),
+  ...modelOverrideParameters,
+});
+
+const gitBlameSummaryParameters = Type.Object({
+  path: Type.String({ description: "File path to blame." }),
+  ref: Type.Optional(Type.String({ description: 'Git ref (default: "HEAD").' })),
+  ...modelOverrideParameters,
+});
+
+export const GIT_DELEGATE_TOOL_NAMES = [
+  "git_diff_summary",
+  "git_log_summary",
+  "git_blame_summary",
+] as const;
+
+export function registerGitDelegateTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "git_diff_summary",
+    label: "Git Diff Summary",
+    description: "Run git diff and delegate summarization to a subagent.",
+    promptSnippet: "git_diff_summary: summarize git diff via subagent",
+    promptGuidelines: [
+      "Use git_diff_summary when the user wants a concise summary of git diff output without loading raw diff into context.",
+      "Do not use this tool for write operations such as commit or push.",
+    ],
+    parameters: gitDiffSummaryParameters,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      return executeGitDiffSummary(params, ctx, signal);
+    },
+  });
+
+  pi.registerTool({
+    name: "git_log_summary",
+    label: "Git Log Summary",
+    description: "Run git log and delegate digest generation to a subagent.",
+    promptSnippet: "git_log_summary: summarize recent commits via subagent",
+    promptGuidelines: [
+      "Use git_log_summary when the user wants a digest of recent commits without loading full log output into context.",
+    ],
+    parameters: gitLogSummaryParameters,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      return executeGitLogSummary(params, ctx, signal);
+    },
+  });
+
+  pi.registerTool({
+    name: "git_blame_summary",
+    label: "Git Blame Summary",
+    description: "Run git blame and delegate contributor context to a subagent.",
+    promptSnippet: "git_blame_summary: summarize file blame history via subagent",
+    promptGuidelines: [
+      "Use git_blame_summary when the user asks who changed a file and wants a concise contributor summary.",
+    ],
+    parameters: gitBlameSummaryParameters,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      return executeGitBlameSummary(params, ctx, signal);
+    },
+  });
+}

package/lib/schema.ts

@@ -0,0 +1,8 @@
+import { Type, type TEnum, type TSchemaOptions } from "typebox";
+
+export function StringEnum<const Values extends [string, ...string[]]>(
+  values: readonly [...Values],
+  options?: TSchemaOptions,
+): TEnum<Values> {
+  return Type.Enum([...values] as [string, ...string[]], options) as unknown as TEnum<Values>;
+}

package/lib/settings-help.ts

@@ -0,0 +1,176 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+  DEFAULT_GIT_DELEGATE_CONFIG,
+  type GitDelegateConfig,
+  type GitDelegateToolKey,
+  type ModelRoute,
+  NULL_MODEL_ROUTE,
+} from "./config.ts";
+
+export const SETTINGS_KEY = "pi-git-delegate";
+
+export interface SettingsLocation {
+  scope: "project" | "agent";
+  path: string;
+  exists: boolean;
+}
+
+const TOOL_LABELS: Record<GitDelegateToolKey, string> = {
+  diff: "git_diff_summary",
+  log: "git_log_summary",
+  blame: "git_blame_summary",
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function getProjectSettingsPath(cwd: string): string {
+  return join(cwd, ".pi", "settings.json");
+}
+
+export function getAgentSettingsPath(): string {
+  return join(getAgentDir(), "settings.json");
+}
+
+export function resolveWritableSettingsPath(cwd: string): SettingsLocation {
+  const projectPath = getProjectSettingsPath(cwd);
+  if (existsSync(projectPath)) {
+    return { scope: "project", path: projectPath, exists: true };
+  }
+
+  const agentPath = getAgentSettingsPath();
+  if (existsSync(agentPath)) {
+    return { scope: "agent", path: agentPath, exists: true };
+  }
+
+  return { scope: "project", path: projectPath, exists: false };
+}
+
+export function findActiveSettingsLocation(cwd: string): SettingsLocation | undefined {
+  const projectPath = getProjectSettingsPath(cwd);
+  if (existsSync(projectPath)) {
+    return { scope: "project", path: projectPath, exists: true };
+  }
+
+  const agentPath = getAgentSettingsPath();
+  if (existsSync(agentPath)) {
+    return { scope: "agent", path: agentPath, exists: true };
+  }
+
+  return undefined;
+}
+
+export function readSettingsObject(filePath: string): Record<string, unknown> {
+  if (!existsSync(filePath)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function formatGitDelegateConfig(config: GitDelegateConfig = DEFAULT_GIT_DELEGATE_CONFIG): string {
+  const payload = {
+    [SETTINGS_KEY]: config,
+  };
+  return JSON.stringify(payload, null, 2);
+}
+
+export function formatRouteSummary(toolKey: GitDelegateToolKey, route: ModelRoute): string {
+  const provider = route.provider ?? "null";
+  const model = route.model ?? "null";
+  return `${TOOL_LABELS[toolKey]}: provider=${provider}, model=${model}`;
+}
+
+export function buildConfigureHelp(cwd: string, config: GitDelegateConfig | undefined): string {
+  const active = findActiveSettingsLocation(cwd);
+  const writeTarget = resolveWritableSettingsPath(cwd);
+  const resolved = config ?? DEFAULT_GIT_DELEGATE_CONFIG;
+  const lines = [
+    "Pi Git Delegate settings",
+    "",
+    "Add a pi-git-delegate block to .pi/settings.json to route each tool to a subagent model.",
+    "",
+    "Per tool, set:",
+    "  provider -> LLM provider (null = session provider)",
+    "  model    -> model id (null = session model)",
+    "",
+    "Priority: tool parameter provider/model > settings.json > current session",
+    "",
+    `Active settings: ${active ? `${active.scope} (${active.path})` : "none"}`,
+    `Default write target: ${writeTarget.scope} (${writeTarget.path})`,
+    "",
+    "Current resolved routes:",
+    formatRouteSummary("diff", resolved.diff),
+    formatRouteSummary("log", resolved.log),
+    formatRouteSummary("blame", resolved.blame),
+    "",
+    "Starter config (null = use session defaults):",
+    formatGitDelegateConfig(DEFAULT_GIT_DELEGATE_CONFIG),
+    "",
+    "Run /git-delegate:configure in Pi to save this interactively.",
+  ];
+
+  return lines.join("\n");
+}
+
+export function mergeGitDelegateSettings(
+  filePath: string,
+  config: GitDelegateConfig,
+): Record<string, unknown> {
+  const settings = readSettingsObject(filePath);
+  settings[SETTINGS_KEY] = config;
+  return settings;
+}
+
+export function writeGitDelegateSettings(filePath: string, config: GitDelegateConfig): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const merged = mergeGitDelegateSettings(filePath, config);
+  writeFileSync(filePath, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+}
+
+async function promptForRoute(
+  ui: {
+    input: (title: string, placeholder?: string) => Promise<string | undefined>;
+  },
+  toolKey: GitDelegateToolKey,
+  current: ModelRoute,
+): Promise<ModelRoute> {
+  const provider = (await ui.input(`${TOOL_LABELS[toolKey]} provider (empty = null)`, current.provider ?? ""))?.trim();
+  const model = (await ui.input(`${TOOL_LABELS[toolKey]} model (empty = null)`, current.model ?? ""))?.trim();
+
+  return {
+    provider: provider ? provider : null,
+    model: model ? model : null,
+  };
+}
+
+export async function promptForGitDelegateConfig(
+  ui: {
+    confirm: (title: string, message: string) => Promise<boolean>;
+    input: (title: string, placeholder?: string) => Promise<string | undefined>;
+  },
+  defaults: GitDelegateConfig = DEFAULT_GIT_DELEGATE_CONFIG,
+): Promise<GitDelegateConfig | undefined> {
+  const useNullDefaults = await ui.confirm(
+    "Use null defaults?",
+    "Save provider=null and model=null for all tools so subagents use the current session provider/model.",
+  );
+  if (useNullDefaults) {
+    return {
+      diff: { ...NULL_MODEL_ROUTE },
+      log: { ...NULL_MODEL_ROUTE },
+      blame: { ...NULL_MODEL_ROUTE },
+    };
+  }
+
+  return {
+    diff: await promptForRoute(ui, "diff", defaults.diff),
+    log: await promptForRoute(ui, "log", defaults.log),
+    blame: await promptForRoute(ui, "blame", defaults.blame),
+  };
+}

package/lib/subagent-runner.ts

@@ -0,0 +1,148 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+
+export interface SubagentRequest {
+  cwd: string;
+  prompt: string;
+  provider?: string;
+  model?: string;
+  signal?: AbortSignal;
+}
+
+export interface SubagentResult {
+  exitCode: number;
+  outputText: string;
+  stderr: string;
+}
+
+export type SubagentRunner = (request: SubagentRequest) => Promise<SubagentResult>;
+
+let runnerOverride: SubagentRunner | undefined;
+
+export function setSubagentRunnerForTests(runner: SubagentRunner | undefined): void {
+  runnerOverride = runner;
+}
+
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+  const currentScript = process.argv[1];
+  const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
+  if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...args] };
+  }
+
+  const execName = path.basename(process.execPath).toLowerCase();
+  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+  if (!isGenericRuntime) {
+    return { command: process.execPath, args };
+  }
+
+  return { command: "pi", args };
+}
+
+function getFinalOutput(messages: Message[]): string {
+  const assistantTexts = messages
+    .filter((message): message is Extract<Message, { role: "assistant" }> => message.role === "assistant")
+    .flatMap((message) =>
+      message.content
+        .filter((block): block is { type: "text"; text: string } => block.type === "text")
+        .map((block) => block.text),
+    );
+
+  return assistantTexts.join("\n").trim();
+}
+
+export async function runSubagent(request: SubagentRequest): Promise<SubagentResult> {
+  if (runnerOverride) {
+    return runnerOverride(request);
+  }
+
+  const args: string[] = ["--mode", "json", "-p", "--no-session"];
+  if (request.provider) {
+    args.push("--provider", request.provider);
+  }
+  if (request.model) {
+    args.push("--model", request.model);
+  }
+  args.push(request.prompt);
+
+  let stderr = "";
+  const messages: Message[] = [];
+
+  const exitCode = await new Promise<number>((resolve) => {
+    const invocation = getPiInvocation(args);
+    const proc = spawn(invocation.command, invocation.args, {
+      cwd: request.cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let buffer = "";
+
+    const processLine = (line: string) => {
+      if (!line.trim()) return;
+      let event: { type?: string; message?: Message };
+      try {
+        event = JSON.parse(line) as { type?: string; message?: Message };
+      } catch {
+        return;
+      }
+
+      if (event.type === "message_end" && event.message) {
+        messages.push(event.message);
+      }
+    };
+
+    proc.stdout.on("data", (data) => {
+      buffer += data.toString();
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const line of lines) processLine(line);
+    });
+
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on("close", (code) => {
+      if (buffer.trim()) processLine(buffer);
+      resolve(code ?? 0);
+    });
+
+    proc.on("error", (error) => {
+      stderr += error.message;
+      resolve(1);
+    });
+
+    if (request.signal) {
+      const kill = () => {
+        proc.kill("SIGTERM");
+        setTimeout(() => {
+          if (!proc.killed) proc.kill("SIGKILL");
+        }, 5000);
+      };
+      if (request.signal.aborted) kill();
+      else request.signal.addEventListener("abort", kill, { once: true });
+    }
+  });
+
+  if (exitCode !== 0 && !getFinalOutput(messages)) {
+    const message = stderr.trim() || "Failed to run subagent. Ensure `pi` is available in PATH.";
+    return { exitCode, outputText: "", stderr: message };
+  }
+
+  return {
+    exitCode,
+    outputText: getFinalOutput(messages),
+    stderr,
+  };
+}
+
+export function createEchoSubagentRunner(summaryText = "Delegated git summary."): SubagentRunner {
+  return async () => ({
+    exitCode: 0,
+    outputText: summaryText,
+    stderr: "",
+  });
+}

package/lib/tools/git-blame-summary.ts

@@ -0,0 +1,64 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadGitDelegateConfig, resolveSubagentRoute } from "../config.ts";
+import { runGit } from "../git-exec.ts";
+import { buildSubagentPrompt, BLAME_SUMMARY_PROMPT } from "../prompts.ts";
+import { runSubagent } from "../subagent-runner.ts";
+
+export interface GitBlameSummaryParams {
+  path: string;
+  ref?: string;
+  provider?: string;
+  model?: string;
+}
+
+export async function executeGitBlameSummary(
+  params: GitBlameSummaryParams,
+  ctx: ExtensionContext,
+  signal?: AbortSignal,
+) {
+  const filePath = params.path?.trim();
+  if (!filePath) {
+    return textResult("path is required.", { error: true });
+  }
+
+  const ref = params.ref?.trim() || "HEAD";
+  const config = loadGitDelegateConfig(ctx.cwd);
+  const route = resolveSubagentRoute("git_blame_summary", config, {
+    provider: params.provider,
+    model: params.model,
+  });
+
+  const gitResult = runGit(["blame", ref, "--", filePath], ctx.cwd);
+  if (gitResult.status !== 0) {
+    const error = gitResult.stderr || gitResult.stdout || `git blame failed with exit code ${gitResult.status}`;
+    return textResult(error, { path: filePath, ref, error: true });
+  }
+
+  if (!gitResult.stdout) {
+    return textResult(`No blame data found for ${filePath}.`, { path: filePath, ref, empty: true });
+  }
+
+  const subagent = await runSubagent({
+    cwd: ctx.cwd,
+    prompt: buildSubagentPrompt(BLAME_SUMMARY_PROMPT, gitResult.stdout),
+    provider: route?.provider,
+    model: route?.model,
+    signal,
+  });
+
+  if (!subagent.outputText) {
+    const error = subagent.stderr || "Subagent returned no summary.";
+    return textResult(error, { path: filePath, ref, error: true });
+  }
+
+  return textResult(subagent.outputText, {
+    path: filePath,
+    ref,
+    provider: route?.provider ?? null,
+    model: route?.model ?? null,
+  });
+}
+
+function textResult(text: string, details: Record<string, unknown> = {}) {
+  return { content: [{ type: "text" as const, text }], details };
+}

package/lib/tools/git-diff-summary.ts

@@ -0,0 +1,57 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadGitDelegateConfig, resolveSubagentRoute } from "../config.ts";
+import { runGit } from "../git-exec.ts";
+import { buildSubagentPrompt, DIFF_SUMMARY_PROMPT } from "../prompts.ts";
+import { runSubagent } from "../subagent-runner.ts";
+
+export interface GitDiffSummaryParams {
+  ref?: string;
+  provider?: string;
+  model?: string;
+}
+
+export async function executeGitDiffSummary(
+  params: GitDiffSummaryParams,
+  ctx: ExtensionContext,
+  signal?: AbortSignal,
+) {
+  const ref = params.ref?.trim() || "HEAD";
+  const config = loadGitDelegateConfig(ctx.cwd);
+  const route = resolveSubagentRoute("git_diff_summary", config, {
+    provider: params.provider,
+    model: params.model,
+  });
+
+  const gitResult = runGit(["diff", ref], ctx.cwd);
+  if (gitResult.status !== 0) {
+    const error = gitResult.stderr || gitResult.stdout || `git diff failed with exit code ${gitResult.status}`;
+    return textResult(error, { ref, error: true });
+  }
+
+  if (!gitResult.stdout) {
+    return textResult("No changes found.", { ref, empty: true });
+  }
+
+  const subagent = await runSubagent({
+    cwd: ctx.cwd,
+    prompt: buildSubagentPrompt(DIFF_SUMMARY_PROMPT, gitResult.stdout),
+    provider: route?.provider,
+    model: route?.model,
+    signal,
+  });
+
+  if (!subagent.outputText) {
+    const error = subagent.stderr || "Subagent returned no summary.";
+    return textResult(error, { ref, error: true });
+  }
+
+  return textResult(subagent.outputText, {
+    ref,
+    provider: route?.provider ?? null,
+    model: route?.model ?? null,
+  });
+}
+
+function textResult(text: string, details: Record<string, unknown> = {}) {
+  return { content: [{ type: "text" as const, text }], details };
+}

package/lib/tools/git-log-summary.ts

@@ -0,0 +1,64 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadGitDelegateConfig, resolveSubagentRoute } from "../config.ts";
+import { runGit } from "../git-exec.ts";
+import { buildSubagentPrompt, LOG_SUMMARY_PROMPT } from "../prompts.ts";
+import { runSubagent } from "../subagent-runner.ts";
+
+export interface GitLogSummaryParams {
+  range?: string;
+  provider?: string;
+  model?: string;
+}
+
+export async function executeGitLogSummary(
+  params: GitLogSummaryParams,
+  ctx: ExtensionContext,
+  signal?: AbortSignal,
+) {
+  const range = params.range?.trim() || "HEAD~10..HEAD";
+  const config = loadGitDelegateConfig(ctx.cwd);
+  const route = resolveSubagentRoute("git_log_summary", config, {
+    provider: params.provider,
+    model: params.model,
+  });
+
+  const gitResult = runGit(["log", "--oneline", range], ctx.cwd);
+  if (gitResult.status !== 0) {
+    if (isNoCommitsInRange(gitResult.stderr)) {
+      return textResult("No commits in range.", { range, empty: true });
+    }
+    const error = gitResult.stderr || gitResult.stdout || `git log failed with exit code ${gitResult.status}`;
+    return textResult(error, { range, error: true });
+  }
+
+  if (!gitResult.stdout) {
+    return textResult("No commits in range.", { range, empty: true });
+  }
+
+  const subagent = await runSubagent({
+    cwd: ctx.cwd,
+    prompt: buildSubagentPrompt(LOG_SUMMARY_PROMPT, gitResult.stdout),
+    provider: route?.provider,
+    model: route?.model,
+    signal,
+  });
+
+  if (!subagent.outputText) {
+    const error = subagent.stderr || "Subagent returned no summary.";
+    return textResult(error, { range, error: true });
+  }
+
+  return textResult(subagent.outputText, {
+    range,
+    provider: route?.provider ?? null,
+    model: route?.model ?? null,
+  });
+}
+
+function textResult(text: string, details: Record<string, unknown> = {}) {
+  return { content: [{ type: "text" as const, text }], details };
+}
+
+function isNoCommitsInRange(stderr: string): boolean {
+  return /does not have any commits|unknown revision|bad revision|needed single revision|ambiguous argument/i.test(stderr);
+}