@trim21/personal-pi-extensions 0.0.216 → 0.0.222

package/src/bwrap/runtime.ts

@@ -0,0 +1,296 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { createBashTool } from "@earendil-works/pi-coding-agent";
+import { type TObject, Type } from "typebox";
+
+import { type CommandSpec, parseCommand } from "../lib/cli.js";
+import {
+  type BwrapMode,
+  createBwrapBashOperations,
+  findBwrap,
+  loadBwrapConfig,
+  resolveBwrap,
+  resolveBwrapPath,
+  type ResolvedBwrap,
+  resolveHeadlessBwrap,
+} from "./core.js";
+
+export type EscalationDecision = { kind: "dialog" } | { kind: "deny"; reason: string };
+
+export function resolveEscalation(opts: { hasUI: boolean }): EscalationDecision {
+  if (!opts.hasUI) {
+    return {
+      kind: "deny",
+      reason:
+        "request_full_access requires an interactive session with user approval; no UI is available in this session.",
+    };
+  }
+  return { kind: "dialog" };
+}
+
+export interface BwrapExecutionRequest {
+  toolCallId: string;
+  command: string;
+  timeout?: number;
+  requestFullAccess?: boolean;
+  requestFullAccessReason?: string;
+  signal?: AbortSignal;
+  onUpdate?: Parameters<ReturnType<typeof createBashTool>["execute"]>[3];
+  ctx: ExtensionContext;
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function fenceCodeBlock(code: string): string {
+  const longestRun = Math.max(...(code.match(/`+/g)?.map((match) => match.length) ?? [0]));
+  const fence = "`".repeat(Math.max(3, longestRun + 1));
+  return `${fence}\n${code}\n${fence}`;
+}
+
+function notifyMode(
+  ctx: { ui: { notify: (message: string, type?: "info" | "warning" | "error") => void } },
+  mode: BwrapMode,
+): void {
+  const labels: Record<BwrapMode, string> = {
+    "allow-all": "allow-all: sandbox off, network on",
+    "workspace-write": "workspace-write: sandbox on, network off",
+    "allow-net": "allow-net: sandbox on, network on, workspace writable",
+    readonly: "readonly: sandbox on, network off, read-only fs",
+  };
+  ctx.ui.notify(labels[mode], "info");
+}
+
+export class BwrapRuntime {
+  private resolved: ResolvedBwrap | undefined;
+  private sandboxDisabled = false;
+
+  setup(pi: ExtensionAPI): void {
+    pi.registerFlag("no-bwrap", {
+      description: "Disable bwrap sandboxing for bash commands",
+      type: "boolean",
+      default: false,
+    });
+
+    pi.on("session_start", (_event, ctx) => {
+      this.sandboxDisabled = pi.getFlag("no-bwrap") === true && ctx.hasUI;
+      this.resolved = undefined;
+      const runtime = this.resolve(ctx);
+      if (runtime.bwrapEnabled) {
+        try {
+          findBwrap(runtime.bwrapPath);
+        } catch (error) {
+          this.sandboxDisabled = true;
+          this.resolved = undefined;
+          ctx.ui.notify(error instanceof Error ? error.message : "bwrap not found", "error");
+          return;
+        }
+      }
+      ctx.ui.setStatus("bwrap", ctx.ui.theme.fg("accent", `bwrap: ${runtime.mode}`));
+      ctx.ui.notify(
+        runtime.bwrapEnabled
+          ? `bwrap initialized (${runtime.mode})`
+          : `bwrap mode: ${runtime.mode}`,
+        "info",
+      );
+    });
+
+    pi.on("session_shutdown", () => {
+      this.reset();
+    });
+
+    pi.on("before_agent_start", (event, ctx) => {
+      const runtime = this.resolve(ctx);
+      const prompt = ctx.hasUI
+        ? `\n\n## Command Execution\nCurrent bwrap mode: **${runtime.mode}**. The bwrap runtime selects sandboxing and, when requested, user approval for unsandboxed execution.\n`
+        : "\n\n## Command Execution\nThis headless session is forced into bwrap readonly mode. Unsandboxed execution cannot be approved.\n";
+      return { systemPrompt: event.systemPrompt + prompt };
+    });
+
+    this.registerCommands(pi);
+  }
+
+  setMode(cwd: string, mode: BwrapMode): ResolvedBwrap {
+    this.resolved = resolveBwrap({ ...loadBwrapConfig(cwd), mode });
+    this.sandboxDisabled = false;
+    return this.resolved;
+  }
+
+  reset(): void {
+    this.resolved = undefined;
+    this.sandboxDisabled = false;
+  }
+
+  async execute(request: BwrapExecutionRequest) {
+    const runtime = this.resolve(request.ctx);
+    if (request.requestFullAccess === true && runtime.bwrapEnabled) {
+      await this.approveFullAccess(request.ctx, request.command, request.requestFullAccessReason);
+    }
+    const bash =
+      runtime.bwrapEnabled && request.requestFullAccess !== true
+        ? createBashTool(request.ctx.cwd, { operations: createBwrapBashOperations(runtime) })
+        : createBashTool(request.ctx.cwd);
+    return bash.execute(
+      request.toolCallId,
+      { command: request.command, timeout: request.timeout },
+      request.signal,
+      request.onUpdate,
+    );
+  }
+
+  private resolve(ctx: Pick<ExtensionContext, "cwd" | "hasUI">): ResolvedBwrap {
+    const config = loadBwrapConfig(ctx.cwd);
+    if (!ctx.hasUI) return resolveHeadlessBwrap(config);
+    if (this.sandboxDisabled) return resolveBwrap({ ...config, mode: "allow-all" });
+    if (!this.resolved) this.resolved = resolveBwrap(config);
+    return this.resolved;
+  }
+
+  private async approveFullAccess(
+    ctx: ExtensionContext,
+    command: string,
+    reason: string | undefined,
+  ): Promise<void> {
+    const policy = resolveEscalation({ hasUI: ctx.hasUI });
+    if (policy.kind === "deny") throw new Error(policy.reason);
+    const description = `Allow this command to run without sandbox?\n---\n\nReason: ${escapeHtml(reason ?? "(No reason provided by model)")}\n---\n${fenceCodeBlock(command)}`;
+    while (true) {
+      const choice = await ctx.ui.select(
+        description,
+        ["Approve once", "Block", "Block with reason"],
+        {
+          signal: ctx.signal,
+        },
+      );
+      if (choice === undefined) {
+        ctx.abort();
+        throw new Error("User denied the command execution.");
+      }
+      if (choice === "Approve once") return;
+      if (choice === "Block") throw new Error("User denied unsandboxed execution.");
+      const feedback = await ctx.ui.input("Why was this denied?", undefined, {
+        signal: ctx.signal,
+      });
+      if (feedback === undefined) continue;
+      throw new Error(
+        feedback
+          ? `User denied unsandboxed execution: ${feedback}`
+          : "User denied unsandboxed execution.",
+      );
+    }
+  }
+
+  private registerCommands(pi: ExtensionAPI): void {
+    const specs = {
+      bwrap: {
+        name: "bwrap",
+        usage: "",
+        description: "Show bwrap sandbox configuration",
+        flags: Type.Object({}),
+      },
+      "bwrap-allow-all": {
+        name: "bwrap-allow-all",
+        usage: "",
+        description: "Disable bwrap sandbox, full access",
+        flags: Type.Object({}),
+      },
+      "bwrap-workspace-write": {
+        name: "bwrap-workspace-write",
+        usage: "",
+        description: "Sandbox on, network off, workspace writable",
+        flags: Type.Object({}),
+      },
+      "bwrap-allow-net": {
+        name: "bwrap-allow-net",
+        usage: "",
+        description: "Sandbox on, network on, workspace writable",
+        flags: Type.Object({}),
+      },
+      "bwrap-readonly": {
+        name: "bwrap-readonly",
+        usage: "",
+        description: "Sandbox on, network off, no writes",
+        flags: Type.Object({}),
+      },
+    } as const satisfies Record<string, CommandSpec<TObject>>;
+
+    pi.registerCommand("bwrap", {
+      description: specs.bwrap.description,
+      handler: (args, ctx) =>
+        this.runCommand(pi, specs.bwrap, args, ctx, (commandCtx) => {
+          const runtime = this.resolve(commandCtx);
+          if (!runtime.bwrapEnabled) {
+            commandCtx.ui.notify(`bwrap disabled (mode: ${runtime.mode})`, "info");
+            return;
+          }
+          const writable = runtime.writablePaths.map((path) =>
+            resolveBwrapPath(path, commandCtx.cwd),
+          );
+          const tmpfs = runtime.tmpfsPaths.map((path) => resolveBwrapPath(path, commandCtx.cwd));
+          commandCtx.ui.notify(
+            `bwrap ${runtime.mode} ${runtime.network ? "net" : "no-net"} write:[${writable.join(", ")}] tmpfs:[${tmpfs.join(", ") || "-"}]`,
+            "info",
+          );
+        }),
+    });
+
+    for (const [name, mode] of [
+      ["bwrap-allow-all", "allow-all"],
+      ["bwrap-workspace-write", "workspace-write"],
+      ["bwrap-allow-net", "allow-net"],
+      ["bwrap-readonly", "readonly"],
+    ] as const) {
+      pi.registerCommand(name, {
+        description: specs[name].description,
+        handler: (args, ctx) =>
+          this.runCommand(pi, specs[name], args, ctx, (commandCtx) =>
+            this.switchMode(pi, mode, commandCtx),
+          ),
+      });
+    }
+  }
+
+  private switchMode(pi: ExtensionAPI, mode: BwrapMode, ctx: ExtensionCommandContext): void {
+    if (!ctx.hasUI) {
+      ctx.ui.notify("bwrap mode cannot be changed without an interactive UI", "warning");
+      return;
+    }
+    this.setMode(ctx.cwd, mode);
+    ctx.ui.setStatus("bwrap", ctx.ui.theme.fg("accent", `bwrap: ${mode}`));
+    notifyMode(ctx, mode);
+    pi.sendMessage({
+      customType: "info",
+      content: `Bwrap sandbox mode changed to "${mode}".`,
+      display: true,
+    });
+  }
+
+  private runCommand(
+    pi: ExtensionAPI,
+    spec: CommandSpec<TObject>,
+    args: string,
+    ctx: ExtensionCommandContext,
+    run: (ctx: ExtensionCommandContext) => void | Promise<void>,
+  ): Promise<void> {
+    const parsed = parseCommand(spec, args);
+    if (parsed.kind !== "ok") {
+      pi.sendMessage({ customType: "info", content: parsed.text, display: true });
+      return Promise.resolve();
+    }
+    return Promise.resolve(run(ctx));
+  }
+}
+
+export function createBwrapRuntime(): BwrapRuntime {
+  return new BwrapRuntime();
+}
+
+export const bwrapRuntime = createBwrapRuntime();

package/src/claude-code/common.ts

@@ -0,0 +1,29 @@
+import { isAbsolute, normalize } from "node:path";
+
+export interface FileSnapshot {
+  digest: string;
+  textEditable: boolean;
+}
+
+export interface ClaudeCodeState {
+  readonly reads: Map<string, FileSnapshot>;
+}
+
+export function createClaudeCodeState(): ClaudeCodeState {
+  return { reads: new Map() };
+}
+
+export function requireAbsolutePath(filePath: string, parameter = "file_path"): string {
+  if (!isAbsolute(filePath)) {
+    throw new Error(`The ${parameter} parameter must be an absolute path, not a relative path.`);
+  }
+  return normalize(filePath);
+}
+
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new Error("Operation aborted");
+}
+
+export function snapshotsEqual(left: FileSnapshot, right: FileSnapshot): boolean {
+  return left.digest === right.digest;
+}

package/src/claude-code/files.ts

@@ -0,0 +1,320 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, extname } from "node:path";
+
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  generateDiffString,
+  generateUnifiedPatch,
+  withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  type ClaudeCodeState,
+  type FileSnapshot,
+  requireAbsolutePath,
+  snapshotsEqual,
+  throwIfAborted,
+} from "./common.js";
+
+const DEFAULT_READ_LINES = 2000;
+const SAMPLE_BYTES = 4096;
+const IMAGE_MIMES = new Map<string, string>([
+  [".gif", "image/gif"],
+  [".jpeg", "image/jpeg"],
+  [".jpg", "image/jpeg"],
+  [".png", "image/png"],
+  [".webp", "image/webp"],
+]);
+
+export interface FileToolDetails {
+  diff?: string;
+  patch?: string;
+  firstChangedLine?: number;
+}
+
+function snapshotOf(content: Uint8Array | string, textEditable = true): FileSnapshot {
+  return { digest: createHash("sha256").update(content).digest("hex"), textEditable };
+}
+
+async function assertReadableFile(filePath: string): Promise<Awaited<ReturnType<typeof stat>>> {
+  const value = await stat(filePath);
+  if (!value.isFile()) throw new Error(`File not found: ${filePath}`);
+  await access(filePath, constants.R_OK);
+  return value;
+}
+
+function isBinary(sample: Uint8Array): boolean {
+  let suspicious = 0;
+  for (const byte of sample) {
+    if (byte === 0) return true;
+    if (byte < 9 || (byte > 13 && byte < 32)) suspicious++;
+  }
+  return sample.length > 0 && suspicious / sample.length > 0.3;
+}
+
+function splitFileLines(content: string): string[] {
+  if (content === "") return [];
+  const lines = content.split("\n");
+  if (content.endsWith("\n")) lines.pop();
+  return lines;
+}
+
+export function formatReadOutput(
+  content: string,
+  offset = 1,
+  limit = DEFAULT_READ_LINES,
+): { text: string; complete: boolean; totalLines: number } {
+  const lines = splitFileLines(content);
+  const totalLines = lines.length;
+  if (totalLines === 0) {
+    if (offset > 1)
+      return {
+        text: `<system-reminder>Warning: the file exists but has fewer lines than the provided offset (${offset}). The file has 0 lines.</system-reminder>`,
+        complete: false,
+        totalLines,
+      };
+    return {
+      text: "<system-reminder>Warning: the file exists but has empty contents.</system-reminder>",
+      complete: true,
+      totalLines,
+    };
+  }
+  if (offset > totalLines) {
+    return {
+      text: `<system-reminder>Warning: the file exists but has fewer lines than the provided offset (${offset}). The file has ${totalLines} lines.</system-reminder>`,
+      complete: false,
+      totalLines,
+    };
+  }
+
+  const selected = lines.slice(offset - 1, offset - 1 + limit);
+  const numbered = selected
+    .map(
+      (line, index) =>
+        `${String(offset + index).padStart(6)}\t${line.length > 2000 ? line.slice(0, 2000) : line}`,
+    )
+    .join("\n");
+  const complete = offset === 1 && selected.length === totalLines;
+  const hasMore = offset - 1 + selected.length < totalLines;
+  const notice = hasMore
+    ? `\n\n<system-reminder>PARTIAL view: showing lines ${offset}-${offset + selected.length - 1} of ${totalLines}. Use offset and limit to read more.</system-reminder>`
+    : "";
+  return { text: numbered + notice, complete, totalLines };
+}
+
+function countMatches(content: string, needle: string): number {
+  if (needle === "") return 0;
+  let count = 0;
+  let index = 0;
+  while ((index = content.indexOf(needle, index)) !== -1) {
+    count++;
+    index += needle.length;
+  }
+  return count;
+}
+
+export function exactReplace(
+  content: string,
+  oldString: string,
+  newString: string,
+  replaceAll = false,
+): string {
+  if (oldString === newString)
+    throw new Error("No changes to apply: old_string and new_string are identical.");
+  if (oldString === "") throw new Error("old_string must not be empty.");
+  const matches = countMatches(content, oldString);
+  if (matches === 0) throw new Error("String to replace not found in file.");
+  if (!replaceAll && matches > 1) {
+    throw new Error(
+      `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, provide more context to make old_string unique.`,
+    );
+  }
+  if (replaceAll) return content.split(oldString).join(newString);
+  const index = content.indexOf(oldString);
+  return content.slice(0, index) + newString + content.slice(index + oldString.length);
+}
+
+async function requireCurrentRead(state: ClaudeCodeState, filePath: string): Promise<void> {
+  const readSnapshot = state.reads.get(filePath);
+  if (!readSnapshot)
+    throw new Error(`File has not been read yet. Read it first before writing to it: ${filePath}`);
+  if (!readSnapshot.textEditable) {
+    throw new Error(`Cannot edit or overwrite a binary file with a text tool: ${filePath}`);
+  }
+  const currentContent = await readFile(filePath);
+  const current = snapshotOf(currentContent);
+  if (!snapshotsEqual(readSnapshot, current)) {
+    throw new Error(`File has been modified since read. Read it again before writing: ${filePath}`);
+  }
+}
+
+export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): void {
+  pi.registerTool({
+    name: "Read",
+    label: "Read",
+    description: [
+      "Reads a file from the local filesystem. You can access any file directly using this tool.",
+      "The file_path parameter must be an absolute path. By default, it reads up to 2000 lines from the beginning.",
+      "Results use cat -n style line numbers starting at 1. Images are returned visually.",
+      "This tool reads files, not directories.",
+    ].join("\n"),
+    parameters: Type.Object(
+      {
+        file_path: Type.String({ description: "The absolute path to the file to read" }),
+        offset: Type.Optional(
+          Type.Number({ description: "The line number to start reading from" }),
+        ),
+        limit: Type.Optional(Type.Number({ description: "The number of lines to read" })),
+        pages: Type.Optional(
+          Type.String({ description: 'Page range for PDF files (for example "1-5" or "3")' }),
+        ),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id, params, signal) {
+      throwIfAborted(signal);
+      const filePath = requireAbsolutePath(params.file_path);
+      if (
+        params.offset !== undefined &&
+        (!Number.isSafeInteger(params.offset) || params.offset < 1)
+      ) {
+        throw new Error("offset must be a positive integer");
+      }
+      if (params.limit !== undefined && (!Number.isSafeInteger(params.limit) || params.limit < 1)) {
+        throw new Error("limit must be a positive integer");
+      }
+      await assertReadableFile(filePath);
+      throwIfAborted(signal);
+
+      const extension = extname(filePath).toLowerCase();
+      if (extension === ".pdf") {
+        throw new Error(
+          "PDF page rendering is not supported by this pi tool host. Use an external PDF extraction tool before calling Read.",
+        );
+      }
+      const imageMime = IMAGE_MIMES.get(extension);
+      if (imageMime) {
+        const image = await readFile(filePath);
+        const data = image.toString("base64");
+        const content: (TextContent | ImageContent)[] = [
+          { type: "text", text: `Read image file [${imageMime}]` },
+          { type: "image", data, mimeType: imageMime },
+        ];
+        state.reads.set(filePath, snapshotOf(image, false));
+        return { content, details: undefined };
+      }
+
+      const buffer = await readFile(filePath);
+      if (isBinary(buffer.subarray(0, SAMPLE_BYTES)))
+        throw new Error(`Cannot read binary file: ${filePath}`);
+      const formatted = formatReadOutput(
+        buffer.toString("utf8"),
+        params.offset ?? 1,
+        params.limit ?? DEFAULT_READ_LINES,
+      );
+      state.reads.set(filePath, snapshotOf(buffer));
+      return { content: [{ type: "text", text: formatted.text }], details: undefined };
+    },
+  });
+
+  pi.registerTool({
+    name: "Edit",
+    label: "Edit",
+    description: [
+      "Performs exact string replacements in files.",
+      "You must use Read on the file before editing it.",
+      "old_string must match exactly and must be unique unless replace_all is true.",
+      "This tool does not use regular expressions or fuzzy matching.",
+    ].join("\n"),
+    parameters: Type.Object(
+      {
+        file_path: Type.String({ description: "The absolute path to the file to modify" }),
+        old_string: Type.String({ description: "The text to replace" }),
+        new_string: Type.String({ description: "The text to replace it with" }),
+        replace_all: Type.Optional(
+          Type.Boolean({ description: "Replace all occurrences of old_string", default: false }),
+        ),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id, params, signal) {
+      throwIfAborted(signal);
+      const filePath = requireAbsolutePath(params.file_path);
+      return withFileMutationQueue(filePath, async () => {
+        await requireCurrentRead(state, filePath);
+        await access(filePath, constants.R_OK | constants.W_OK);
+        const original = await readFile(filePath, "utf8");
+        throwIfAborted(signal);
+        const updated = exactReplace(
+          original,
+          params.old_string,
+          params.new_string,
+          params.replace_all ?? false,
+        );
+        await writeFile(filePath, updated, "utf8");
+        state.reads.set(filePath, snapshotOf(updated));
+        const diff = generateDiffString(original, updated);
+        return {
+          content: [{ type: "text", text: `The file ${filePath} has been updated successfully.` }],
+          details: {
+            diff: diff.diff,
+            patch: generateUnifiedPatch(filePath, original, updated),
+            firstChangedLine: diff.firstChangedLine,
+          } satisfies FileToolDetails,
+        };
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "Write",
+    label: "Write",
+    description: [
+      "Writes a file to the local filesystem.",
+      "This tool overwrites an existing file with the full content provided.",
+      "If the file exists, you must use Read first. Prefer Edit for partial changes.",
+    ].join("\n"),
+    parameters: Type.Object(
+      {
+        file_path: Type.String({
+          description: "The absolute path to the file to write (must be absolute, not relative)",
+        }),
+        content: Type.String({ description: "The content to write to the file" }),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id, params, signal) {
+      throwIfAborted(signal);
+      const filePath = requireAbsolutePath(params.file_path);
+      return withFileMutationQueue(filePath, async () => {
+        let original: string | undefined;
+        try {
+          const value = await stat(filePath);
+          if (value.isFile()) {
+            await requireCurrentRead(state, filePath);
+            original = await readFile(filePath, "utf8");
+          }
+        } catch (error) {
+          if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+        }
+        throwIfAborted(signal);
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, params.content, "utf8");
+        state.reads.set(filePath, snapshotOf(params.content));
+        const diff = generateDiffString(original ?? "", params.content);
+        return {
+          content: [{ type: "text", text: `File created successfully at: ${filePath}` }],
+          details: {
+            diff: diff.diff,
+            patch: generateUnifiedPatch(filePath, original ?? "", params.content),
+            firstChangedLine: diff.firstChangedLine,
+          } satisfies FileToolDetails,
+        };
+      });
+    },
+  });
+}

package/src/claude-code/index.ts

@@ -0,0 +1,15 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createClaudeCodeState } from "./common.js";
+import { registerFileTools } from "./files.js";
+import { registerSearchTools } from "./search.js";
+import { registerSessionTools } from "./session-tools.js";
+import { registerShellTools } from "./shell.js";
+
+export default function claudeCodeTools(pi: ExtensionAPI): void {
+  const state = createClaudeCodeState();
+  registerFileTools(pi, state);
+  registerSearchTools(pi);
+  registerShellTools(pi);
+  registerSessionTools(pi);
+}