@ssweens/pi-leash 0.12.0

package/src/lib/timing.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared timing utilities for tool and subagent execution.
+ */
+
+/** Minimal shape that supports timing fields. */
+export interface TimedExecution {
+  startedAt?: number;
+  endedAt?: number;
+  durationMs?: number;
+}
+
+/** Mark execution start time (epoch ms). */
+export function markExecutionStart<T extends TimedExecution>(
+  target: T,
+  startedAt = Date.now(),
+): T {
+  target.startedAt = startedAt;
+  return target;
+}
+
+/** Mark execution end time and compute duration (epoch ms / ms). */
+export function markExecutionEnd<T extends TimedExecution>(
+  target: T,
+  endedAt = Date.now(),
+): T {
+  target.endedAt = endedAt;
+  if (target.startedAt !== undefined) {
+    target.durationMs = Math.max(0, endedAt - target.startedAt);
+  }
+  return target;
+}
+
+/** Simple wall-clock timer for a full operation (e.g., subagent call). */
+export function createExecutionTimer(startedAt = Date.now()): {
+  startedAt: number;
+  getDurationMs: (endedAt?: number) => number;
+} {
+  return {
+    startedAt,
+    getDurationMs: (endedAt = Date.now()) => Math.max(0, endedAt - startedAt),
+  };
+}

package/src/lib/types.ts

@@ -0,0 +1,115 @@
+import type { AgentTool, ThinkingLevel } from "@mariozechner/pi-agent-core";
+import type { Model } from "@mariozechner/pi-ai";
+import type { Skill, ToolDefinition } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Configuration for a subagent.
+ */
+export interface SubagentConfig {
+  /** Subagent name (for logging and run ID) */
+  name: string;
+
+  /** Model instance to use */
+  // biome-ignore lint/suspicious/noExplicitAny: Model type requires any for generic API
+  model: Model<any>;
+
+  /** System prompt for the subagent */
+  systemPrompt: string;
+
+  /** Built-in tools (AgentTool[]) - e.g., from createReadOnlyTools() */
+  tools?: AgentTool[];
+
+  /** Custom tools (ToolDefinition[]) - e.g., GitHub tools */
+  customTools?: ToolDefinition[];
+
+  /** Skills to load into system prompt */
+  skills?: Skill[];
+
+  /** Thinking level. Default: "low" */
+  thinkingLevel?: ThinkingLevel;
+
+  /** Logging options */
+  logging?: {
+    /** Enable logging. Default: false */
+    enabled: boolean;
+    /** Include raw events in debug.jsonl. Default: false */
+    debug?: boolean;
+  };
+}
+
+/**
+ * Tool call state for tracking subagent tool executions.
+ */
+export interface SubagentToolCall {
+  toolCallId: string;
+  toolName: string;
+  args: Record<string, unknown>;
+  status: "running" | "done" | "error";
+  /** Epoch ms when tool execution started */
+  startedAt?: number;
+  /** Epoch ms when tool execution ended */
+  endedAt?: number;
+  /** Duration in milliseconds (set when ended) */
+  durationMs?: number;
+  result?: unknown;
+  error?: string;
+  /** Partial result from tool updates (for progress display) */
+  partialResult?: {
+    content: Array<{ type: string; text?: string }>;
+    details?: unknown;
+  };
+}
+
+/**
+ * Usage/cost information from the model response.
+ */
+export interface SubagentUsage {
+  /** Input tokens from API (if available) */
+  inputTokens?: number;
+  /** Output tokens from API (if available) */
+  outputTokens?: number;
+  /** Cache read tokens (if available) */
+  cacheReadTokens?: number;
+  /** Cache write tokens (if available) */
+  cacheWriteTokens?: number;
+  /** Estimated tokens from response length (chars/4) */
+  estimatedTokens: number;
+  /** LLM cost in USD (if available) */
+  llmCost?: number;
+  /** Tool/API cost in USD (e.g., Exa, GitHub) */
+  toolCost?: number;
+  /** Total cost in USD (llmCost + toolCost) */
+  totalCost?: number;
+}
+
+/**
+ * Result from executing a subagent.
+ */
+export interface SubagentResult {
+  /** Final text content from the subagent */
+  content: string;
+
+  /** Whether the subagent was aborted */
+  aborted: boolean;
+
+  /** Final tool call states */
+  toolCalls: SubagentToolCall[];
+
+  /** Total subagent execution duration in milliseconds */
+  totalDurationMs: number;
+
+  /** Error message if the subagent failed */
+  error?: string;
+
+  /** Unique run identifier */
+  runId: string;
+
+  /** Usage/cost information */
+  usage: SubagentUsage;
+}
+
+/** Callback for text streaming updates */
+export type OnTextUpdate = (delta: string, accumulated: string) => void;
+
+/** Callback for tool execution updates */
+export type OnToolUpdate = (toolCalls: SubagentToolCall[]) => void;

package/src/utils/events.ts

@@ -0,0 +1,32 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export const LEASH_BLOCKED_EVENT = "leash:blocked";
+export const LEASH_DANGEROUS_EVENT = "leash:dangerous";
+
+export interface LeashBlockedEvent {
+  feature: "policies" | "permissionGate";
+  toolName: string;
+  input: Record<string, unknown>;
+  reason: string;
+  userDenied?: boolean;
+}
+
+export interface LeashDangerousEvent {
+  command: string;
+  description: string;
+  pattern: string;
+}
+
+export function emitBlocked(
+  pi: ExtensionAPI,
+  event: LeashBlockedEvent,
+): void {
+  pi.events.emit(LEASH_BLOCKED_EVENT, event);
+}
+
+export function emitDangerous(
+  pi: ExtensionAPI,
+  event: LeashDangerousEvent,
+): void {
+  pi.events.emit(LEASH_DANGEROUS_EVENT, event);
+}

package/src/utils/glob-expander.ts

@@ -0,0 +1,128 @@
+/**
+ * Glob expansion using `fd` for env file protection.
+ *
+ * When a bash command contains shell globs referencing env files
+ * (e.g. `.env*`), we expand them against the filesystem to check
+ * if any expanded path matches a protected pattern.
+ */
+
+import { execFile } from "node:child_process";
+import { resolve } from "node:path";
+
+interface ExpandGlobOptions {
+  cwd?: string;
+  maxDepth?: number;
+  maxResults?: number;
+  timeout?: number;
+}
+
+/**
+ * Expand a glob pattern using `fd`.
+ * Returns matching file paths, or empty array on failure.
+ *
+ * fd is available at `~/.pi/agent/bin/fd` (in pi's PATH).
+ */
+export async function expandGlob(
+  pattern: string,
+  options: ExpandGlobOptions = {},
+): Promise<string[]> {
+  const {
+    cwd = process.cwd(),
+    maxDepth = 3,
+    maxResults = 50,
+    timeout = 2000,
+  } = options;
+
+  // Convert glob to fd-compatible regex.
+  // fd uses regex by default, so we convert glob chars.
+  const fdPattern = globToFdRegex(pattern);
+
+  return new Promise((res) => {
+    const args = [
+      "--type",
+      "f",
+      "--max-depth",
+      String(maxDepth),
+      "--max-results",
+      String(maxResults),
+      "--no-ignore",
+      "--hidden",
+      fdPattern,
+    ];
+
+    const child = execFile("fd", args, { cwd, timeout }, (err, stdout) => {
+      if (err) {
+        res([]);
+        return;
+      }
+
+      const files = stdout
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((f) => resolve(cwd, f));
+
+      res(files);
+    });
+
+    // Safety net: kill if timeout isn't handled by execFile
+    setTimeout(() => {
+      child.kill();
+      res([]);
+    }, timeout + 500);
+  });
+}
+
+/**
+ * Convert a shell glob to an fd-compatible regex pattern.
+ * Handles `*`, `?`, and character classes `[...]`.
+ */
+function globToFdRegex(glob: string): string {
+  let regex = "";
+  let i = 0;
+  while (i < glob.length) {
+    const ch = glob[i] as string;
+    switch (ch) {
+      case "*":
+        regex += "[^/]*";
+        break;
+      case "?":
+        regex += "[^/]";
+        break;
+      case "[": {
+        // Pass character classes through
+        const end = glob.indexOf("]", i + 1);
+        if (end !== -1) {
+          regex += glob.slice(i, end + 1);
+          i = end;
+        } else {
+          regex += "\\[";
+        }
+        break;
+      }
+      case ".":
+      case "(":
+      case ")":
+      case "+":
+      case "^":
+      case "$":
+      case "{":
+      case "}":
+      case "|":
+      case "\\":
+        regex += `\\${ch}`;
+        break;
+      default:
+        regex += ch;
+    }
+    i++;
+  }
+  return `^${regex}$`;
+}
+
+/**
+ * Check if a string contains shell glob characters.
+ */
+export function hasGlobChars(s: string): boolean {
+  return /[*?[\]]/.test(s);
+}

package/src/utils/matching.ts

@@ -0,0 +1,111 @@
+/**
+ * Pattern compilation for guardrails matching.
+ *
+ * Two contexts with different default semantics:
+ * - File context: default is glob matching against filename.
+ * - Command context: default is substring matching against raw command string.
+ *
+ * Both support `regex: true` for full regex matching.
+ */
+
+import { matchesGlob } from "node:path";
+import type { PatternConfig } from "../config";
+
+export interface CompiledPattern {
+  test: (input: string) => boolean;
+  source: PatternConfig;
+}
+
+/**
+ * Normalize file paths before matching.
+ * - Use forward slashes for cross-platform consistency.
+ * - Drop leading "./" segments.
+ * - Collapse duplicate slashes.
+ */
+export function normalizeFilePath(input: string): string {
+  const normalized = input
+    .replaceAll("\\", "/")
+    .replace(/^(?:\.\/)+/, "")
+    .replace(/\/{2,}/g, "/");
+  return normalized;
+}
+
+/**
+ * Compile a single pattern for file-context matching.
+ * Default: glob matching.
+ * - If pattern includes `/`, match full normalized relative path.
+ * - Otherwise, match basename only (backward compatible).
+ * regex: true -> full regex (case-insensitive) against normalized path.
+ */
+export function compileFilePattern(config: PatternConfig): CompiledPattern {
+  if (config.regex) {
+    try {
+      const re = new RegExp(config.pattern, "i");
+      return {
+        test: (input) => re.test(normalizeFilePath(input)),
+        source: config,
+      };
+    } catch {
+      console.warn(
+        `[pi-leash] Invalid regex in config: ${config.pattern}`,
+      );
+      return { test: () => false, source: config };
+    }
+  }
+
+  const matchFullPath = config.pattern.includes("/");
+
+  return {
+    test: (input) => {
+      const normalized = normalizeFilePath(input);
+      const candidate = matchFullPath
+        ? normalized
+        : (normalized.split("/").pop() ?? normalized);
+
+      return matchesGlob(candidate, config.pattern);
+    },
+    source: config,
+  };
+}
+
+/**
+ * Compile a single pattern for command-context matching.
+ * Default: substring match against raw command string.
+ * regex: true -> full regex against raw command string.
+ */
+export function compileCommandPattern(config: PatternConfig): CompiledPattern {
+  if (config.regex) {
+    try {
+      const re = new RegExp(config.pattern);
+      return { test: (input) => re.test(input), source: config };
+    } catch {
+      console.warn(
+        `[pi-leash] Invalid regex in config: ${config.pattern}`,
+      );
+      return { test: () => false, source: config };
+    }
+  }
+
+  return {
+    test: (input) => input.includes(config.pattern),
+    source: config,
+  };
+}
+
+/**
+ * Compile an array of patterns for file-context matching.
+ */
+export function compileFilePatterns(
+  configs: PatternConfig[],
+): CompiledPattern[] {
+  return configs.map(compileFilePattern);
+}
+
+/**
+ * Compile an array of patterns for command-context matching.
+ */
+export function compileCommandPatterns(
+  configs: PatternConfig[],
+): CompiledPattern[] {
+  return configs.map(compileCommandPattern);
+}

package/src/utils/shell-utils.ts

@@ -0,0 +1,139 @@
+/**
+ * Shared shell AST helpers used by guardrails hooks.
+ *
+ * Each hook imports `parse` from the vendored shell parser and uses these
+ * for common AST operations.
+ */
+
+import type {
+  Command,
+  Program,
+  SimpleCommand,
+  Statement,
+  Word,
+  WordPart,
+} from "../vendor/aliou-sh/index.js";
+
+/**
+ * Resolve a Word node to its literal string value.
+ * Concatenates Literal, SglQuoted, and simple DblQuoted parts.
+ * For parts containing parameter expansions, command substitutions, etc.,
+ * includes the raw text representation (e.g. `$VAR`).
+ */
+export function wordToString(word: Word): string {
+  return word.parts.map(partToString).join("");
+}
+
+function partToString(part: WordPart): string {
+  switch (part.type) {
+    case "Literal":
+      return part.value;
+    case "SglQuoted":
+      return part.value;
+    case "DblQuoted":
+      return part.parts.map(partToString).join("");
+    case "ParamExp":
+      return part.short
+        ? `$${part.param.value}`
+        : `\${${part.param.value}${part.op ?? ""}${part.value ? wordToString(part.value) : ""}}`;
+    case "CmdSubst":
+      return "$(...)";
+    case "ArithExp":
+      return `$((${part.expr}))`;
+    case "ProcSubst":
+      return `${part.op}(...)`;
+  }
+}
+
+/**
+ * Walk the AST and call `callback` for every SimpleCommand found at any
+ * nesting depth. Returns early if callback returns `true`.
+ */
+export function walkCommands(
+  node: Program,
+  callback: (cmd: SimpleCommand) => boolean | undefined,
+): void {
+  for (const stmt of node.body) {
+    if (walkStatement(stmt, callback)) return;
+  }
+}
+
+function walkStatement(
+  stmt: Statement,
+  callback: (cmd: SimpleCommand) => boolean | undefined,
+): boolean {
+  return walkCommand(stmt.command, callback);
+}
+
+function walkStatements(
+  stmts: Statement[],
+  callback: (cmd: SimpleCommand) => boolean | undefined,
+): boolean {
+  for (const stmt of stmts) {
+    if (walkStatement(stmt, callback)) return true;
+  }
+  return false;
+}
+
+function walkCommand(
+  cmd: Command,
+  callback: (cmd: SimpleCommand) => boolean | undefined,
+): boolean {
+  switch (cmd.type) {
+    case "SimpleCommand":
+      return callback(cmd) === true;
+
+    case "Pipeline":
+      return walkStatements(cmd.commands, callback);
+
+    case "Logical":
+      return (
+        walkStatement(cmd.left, callback) || walkStatement(cmd.right, callback)
+      );
+
+    case "Subshell":
+    case "Block":
+      return walkStatements(cmd.body, callback);
+
+    case "IfClause":
+      return (
+        walkStatements(cmd.cond, callback) ||
+        walkStatements(cmd.then, callback) ||
+        (cmd.else ? walkStatements(cmd.else, callback) : false)
+      );
+
+    case "ForClause":
+    case "SelectClause":
+    case "WhileClause":
+      return (
+        ("cond" in cmd && cmd.cond
+          ? walkStatements(cmd.cond, callback)
+          : false) || walkStatements(cmd.body, callback)
+      );
+
+    case "CaseClause":
+      for (const item of cmd.items) {
+        if (walkStatements(item.body, callback)) return true;
+      }
+      return false;
+
+    case "FunctionDecl":
+      return walkStatements(cmd.body, callback);
+
+    case "TimeClause":
+      return walkStatement(cmd.command, callback);
+
+    case "CoprocClause":
+      return walkStatement(cmd.body, callback);
+
+    case "CStyleLoop":
+      return walkStatements(cmd.body, callback);
+
+    // These don't contain nested commands we need to walk
+    case "TestClause":
+    case "ArithCmd":
+    case "DeclClause":
+    case "LetClause":
+      return false;
+  }
+}

package/src/vendor/aliou-sh/NOTICE.md

@@ -0,0 +1,13 @@
+Vendored from `@aliou/sh@0.1.0` (MIT).
+
+Source tarball:
+https://registry.npmjs.org/@aliou/sh/-/sh-0.1.0.tgz
+
+Files copied into this directory:
+- index.js
+- index.d.ts
+- parse.d.ts
+- ast.d.ts
+- upstream.package.json
+
+This vendoring removes runtime dependency on external module resolution for local path installs.