@aaroncql/pim-agent 0.0.1 → 0.2.0

package/src/extensions/apply-patch/schema.ts

@@ -0,0 +1,43 @@
+import { type Static, Type } from "typebox";
+
+export const applyPatchSchema = Type.Object({
+  input: Type.String({
+    description: "Patch text wrapped in *** Begin Patch / *** End Patch.",
+  }),
+});
+
+export type ApplyPatchInput = Static<typeof applyPatchSchema>;
+
+const ALIAS_KEYS = ["patch", "patchText", "patch_text"] as const;
+
+/**
+ * Forgive the JSON-key choice, trust the grammar. Accepts `{input}` (canonical,
+ * handled above), `{patch}`, `{patchText}`/`{patch_text}`, or a bare string,
+ * normalizing to `{input}` and stripping the alias key so the unknown-key
+ * rejection in `Tools.wrap` passes. Validation of the actual envelope happens
+ * in the parser.
+ */
+export function prepareApplyPatchArguments(rawArgs: unknown): ApplyPatchInput {
+  if (typeof rawArgs === "string") {
+    return { input: rawArgs };
+  }
+
+  if (rawArgs === null || typeof rawArgs !== "object") {
+    return rawArgs as ApplyPatchInput;
+  }
+
+  const record = rawArgs as Record<string, unknown>;
+  if (typeof record.input === "string") {
+    return rawArgs as ApplyPatchInput;
+  }
+
+  for (const key of ALIAS_KEYS) {
+    const value = record[key];
+    if (typeof value === "string") {
+      const { [key]: _dropped, ...rest } = record;
+      return { ...rest, input: value } as ApplyPatchInput;
+    }
+  }
+
+  return rawArgs as ApplyPatchInput;
+}

package/src/extensions/apply-patch/types.ts

@@ -0,0 +1,30 @@
+export type UpdateChunk = {
+  readonly changeContext: string | undefined;
+  readonly oldLines: readonly string[];
+  readonly newLines: readonly string[];
+  readonly isEndOfFile: boolean;
+};
+
+export type AddHunk = {
+  readonly kind: "add";
+  readonly path: string;
+  readonly contents: string;
+};
+
+export type DeleteHunk = {
+  readonly kind: "delete";
+  readonly path: string;
+};
+
+export type UpdateHunk = {
+  readonly kind: "update";
+  readonly path: string;
+  readonly movePath: string | undefined;
+  readonly chunks: readonly UpdateChunk[];
+};
+
+export type Hunk = AddHunk | DeleteHunk | UpdateHunk;
+
+export type Patch = {
+  readonly hunks: readonly Hunk[];
+};

package/src/extensions/bash/index.ts

@@ -37,9 +37,9 @@ export default function (pi: ExtensionAPI): void {
     name: "bash",
     label: "bash",
     description:
-      `Execute a bash command in the cwd. ` +
-      `Returns exit code, signal (if any), and stdout/stderr captured separately. ` +
-      `Prefer commands that emit only what you need; keep output as small as possible.`,
+      "Execute a bash command in the cwd. " +
+      "Returns exit code, signal (if any), and stdout/stderr captured separately. " +
+      "Prefer commands that emit only what you need; keep output as small as possible.",
     parameters: bashSchema,
     renderShell: "self",
     executionMode: "sequential",

package/src/extensions/edit/index.ts

@@ -12,7 +12,8 @@ export default function (pi: ExtensionAPI): void {
     name: "edit",
     label: "edit",
     description:
-      "Replace strings in a UTF-8 text file. Prefer edit over write for changes to existing files.",
+      "Replace strings in a UTF-8 text file. " +
+      "Prefer edit over write for changes to existing files.",
     parameters: editSchema,
     renderShell: "self",
     executionMode: "sequential",

package/src/extensions/glob/index.ts

@@ -52,7 +52,9 @@ export default function (pi: ExtensionAPI): void {
     name: "glob",
     label: "glob",
     description:
-      "Find files by glob pattern under a directory, sorted newest first. Skips gitignored paths and dotfiles unless requested. Use glob to enumerate files instead of bash with find, fd, ls -R, or similar.",
+      "Find files by glob pattern under a directory, sorted newest first. " +
+      "Skips gitignored paths and dotfiles unless requested. " +
+      "Use glob to enumerate files instead of bash with find, fd, ls -R, or similar.",
     parameters: globSchema,
     renderShell: "self",
     executionMode: "parallel",

package/src/extensions/glob/schema.ts

@@ -7,7 +7,8 @@ export const GLOB_PATH_FORMATS = ["relative", "absolute"] as const;
 
 export const globSchema = Type.Object({
   pattern: Type.String({
-    description: "Glob pattern relative to path (eg. **/*.ts).",
+    description:
+      "Glob pattern relative to path (eg. **/*.ts). Brace expansion spans sibling dirs (eg. {src,docs}/**/*.ts).",
   }),
   path: Type.Optional(
     Type.String({

package/src/extensions/grep/index.ts

@@ -55,7 +55,9 @@ export default function (pi: ExtensionAPI): void {
     name: "grep",
     label: "grep",
     description:
-      "Search UTF-8 text files with a JavaScript regex. Directory scans skip binary files, gitignored paths, and dotfiles unless requested; direct file paths are always searched. Use grep to search file contents instead of bash with grep, rg, ag, find -exec, or similar.",
+      "Search UTF-8 text files with a JavaScript regex. " +
+      "Directory scans skip binary files, gitignored paths, and dotfiles unless requested; direct file paths are always searched. " +
+      "Use grep to search file contents instead of bash with grep, rg, ag, find -exec, or similar.",
     parameters: grepSchema,
     renderShell: "self",
     executionMode: "parallel",

package/src/extensions/grep/render.ts

@@ -84,17 +84,31 @@ export type TitleOptions = {
 
 export function formatTitle(options: TitleOptions): string {
   const pattern = formatPattern(options.pattern);
-  const resolvedPath =
+  const resolved =
     options.path === undefined
       ? undefined
       : Paths.resolve(options.path, options.cwd);
-  const target = Paths.titleOr(resolvedPath, options.cwd, ".");
-  const glob = options.glob ? ` ${options.glob}` : "";
+  const dir =
+    resolved === undefined || resolved === options.cwd
+      ? undefined
+      : Paths.displayRelative(resolved, options.cwd);
+  const target = joinTarget(dir, options.glob);
+  const location = target ? ` in ${target}` : "";
   const suffix =
     options.fileCount === undefined
       ? ""
       : ` (${options.fileCount} ${options.fileCount === 1 ? "file" : "files"})`;
-  return `${pattern} in ${target}${glob}${suffix}`;
+  return `${pattern}${location}${suffix}`;
+}
+
+function joinTarget(
+  dir: string | undefined,
+  glob: string | undefined
+): string | undefined {
+  if (glob === undefined) {
+    return dir;
+  }
+  return dir === undefined ? glob : `${dir}/${glob}`;
 }
 
 function formatPattern(pattern: string | undefined): string {

package/src/extensions/grep/schema.ts

@@ -25,7 +25,7 @@ export const grepSchema = Type.Object({
   glob: Type.Optional(
     Type.String({
       description:
-        "Relative glob filter under path when path is a directory. Gitignored files and dotfiles are skipped during directory scans unless includeIgnored/includeDotfiles is true.",
+        "Relative glob filter under path when path is a directory. Brace expansion spans sibling dirs (eg. {src,docs}/**/*.ts). Gitignored files and dotfiles are skipped during directory scans unless includeIgnored/includeDotfiles is true.",
     })
   ),
   exclude: Type.Optional(

package/src/extensions/read/index.ts

@@ -3,18 +3,23 @@ import { Paths } from "../../shared/Paths";
 import { Renderer } from "../../shared/Renderer";
 import { Tools } from "../../shared/Tools";
 import { buildReadRange, readFile } from "./read";
-import { formatTitlePath } from "./render";
+import { renderTitlePath, type ReadTitleOutcome } from "./render";
 import { type ReadInput, readSchema } from "./schema";
 
 const PREVIEW_LINES = 10;
 
+type ReadRenderState = {
+  outcome?: ReadTitleOutcome;
+};
+
 export default function (pi: ExtensionAPI): void {
   Tools.register(pi, {
     name: "read",
     label: "read",
     description:
-      "Read a local UTF-8 text file. Output is `LINE:CONTENT` with no space after the colon. Capped at 32KB per call; lines longer than 2000 chars are truncated.",
-    promptSnippet: "Read text files.",
+      "Read a local UTF-8 text file. " +
+      "Output is `LINE:CONTENT` with no space after the colon. " +
+      "Capped at 32KB per call; lines longer than 2000 chars are truncated.",
     parameters: readSchema,
     renderShell: "self",
     executionMode: "parallel",
@@ -58,12 +63,17 @@ export default function (pi: ExtensionAPI): void {
     },
     renderCall(args, theme, context) {
       const input = (args ?? {}) as Partial<ReadInput>;
-      const title = formatTitlePath({
-        path: input.path,
-        cwd: context.cwd,
-        start: input.start,
-        end: input.end,
-      });
+      const state = context.state as ReadRenderState;
+      const title = renderTitlePath(
+        {
+          path: input.path,
+          cwd: context.cwd,
+          start: input.start,
+          end: input.end,
+          outcome: state.outcome,
+        },
+        theme
+      );
       return Renderer.renderToolCallTitle({
         label: "Read",
         title,
@@ -72,6 +82,23 @@ export default function (pi: ExtensionAPI): void {
       });
     },
     renderResult(result, options, theme, context) {
+      const state = context.state as ReadRenderState;
+
+      if (!options.isPartial && state.outcome === undefined) {
+        const details = result.details as ReadTitleOutcome | undefined;
+
+        if (
+          typeof details?.visibleStart === "number" &&
+          typeof details.visibleEnd === "number"
+        ) {
+          state.outcome = {
+            visibleStart: details.visibleStart,
+            visibleEnd: details.visibleEnd,
+          };
+          context.invalidate();
+        }
+      }
+
       return Renderer.renderBorderedResult({
         result,
         options,

package/src/extensions/read/render.ts

@@ -1,24 +1,52 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Paths } from "../../shared/Paths";
 
+export type ReadTitleOutcome = {
+  readonly visibleStart: number;
+  readonly visibleEnd: number;
+};
+
 export type TitlePathOptions = {
   readonly path: string | undefined;
   readonly cwd: string;
   readonly start: number | undefined;
   readonly end: number | undefined;
+  readonly outcome?: ReadTitleOutcome;
 };
 
 export function formatTitlePath(options: TitlePathOptions): string {
+  const { path, range } = formatTitlePathParts(options);
+  return `${path}${range}`;
+}
+
+export function renderTitlePath(
+  options: TitlePathOptions,
+  theme: Theme
+): string {
+  const { path, range } = formatTitlePathParts(options);
+  return `${path}${range === "" ? "" : theme.fg("muted", range)}`;
+}
+
+function formatTitlePathParts(options: TitlePathOptions): {
+  readonly path: string;
+  readonly range: string;
+} {
   const path = options.path
     ? Paths.displayRelative(options.path, options.cwd)
     : "...";
-  const range = formatRange(options.start, options.end);
-  return `${path}${range}`;
+  const range = formatRange(options.start, options.end, options.outcome);
+  return { path, range };
 }
 
 function formatRange(
   start: number | undefined,
-  end: number | undefined
+  end: number | undefined,
+  outcome: ReadTitleOutcome | undefined
 ): string {
+  if (outcome !== undefined) {
+    return `:${outcome.visibleStart}-${outcome.visibleEnd}`;
+  }
+
   if (start === undefined && end === undefined) {
     return "";
   }

package/src/extensions/subagent/index.ts

@@ -9,7 +9,10 @@ export default function (pi: ExtensionAPI): void {
     name: "subagent",
     label: "subagent",
     description:
-      "Delegate a task to an isolated subagent to keep your main context clean. The subagent inherits your currently active tools (except subagent itself) and runs in a fresh in-memory session. Multiple subagent calls in one turn run in parallel. Subagent responses are capped at 32KB; the full output is preserved in tool details.",
+      "Run a task in an isolated subagent with a fresh context. " +
+      "The subagent inherits the currently active tools, except subagent itself. " +
+      "Multiple subagent calls in one turn run in parallel. " +
+      "Subagent output returned to the main agent is capped at 32KB.",
     parameters: subagentSchema,
     renderShell: "self",
     executionMode: "parallel",

package/src/extensions/todo/index.ts

@@ -61,9 +61,10 @@ export default function (pi: ExtensionAPI): void {
     name: "todo",
     label: "todo",
     description:
-      "Manage your to-dos. ALWAYS use for tasks with 3+ steps; skip only for trivial one-step tasks. " +
-      "Each call replaces the entire list; include every item in priority order. " +
-      "Keep at most one item in_progress, mark items completed immediately after finishing, and preserve skipped work as cancelled.",
+      "Update the session task list. " +
+      "Each call replaces the entire list; include every item that should remain, in priority order. " +
+      "Status values are pending, in_progress, completed, and cancelled. " +
+      "At most one item may be in_progress.",
     parameters: todoSchema,
     renderShell: "self",
     executionMode: "sequential",

package/src/extensions/web-search/index.ts

@@ -49,7 +49,8 @@ export default function (pi: ExtensionAPI): void {
     name: "web_search",
     label: "web_search",
     description:
-      "Search the web. Returns ranked results with title, URL, and a short snippet.",
+      "Search the web. " +
+      "Returns ranked results with title, URL, and a short snippet.",
     parameters: webSearchSchema,
     renderShell: "self",
     executionMode: "parallel",

package/src/extensions/write/index.ts

@@ -12,7 +12,8 @@ export default function (pi: ExtensionAPI): void {
     name: "write",
     label: "write",
     description:
-      "Create or overwrite UTF-8 text files. Use write only for new files or full rewrites - prefer edit for changes to existing files.",
+      "Create or overwrite UTF-8 text files. " +
+      "Use write only for new files or full rewrites.",
     parameters: writeSchema,
     renderShell: "self",
     executionMode: "sequential",

package/src/shared/PatchSummary.ts

@@ -0,0 +1,82 @@
+export type PatchOp = {
+  readonly kind: "add" | "delete" | "update";
+  readonly path: string;
+  readonly movePath?: string;
+};
+
+const MOVE_TO_MARKER = "*** Move to:";
+const FILE_MARKERS: ReadonlyArray<readonly [PatchOp["kind"], string]> = [
+  ["add", "*** Add File: "],
+  ["delete", "*** Delete File: "],
+  ["update", "*** Update File: "],
+];
+
+type MutableOp = {
+  readonly kind: PatchOp["kind"];
+  readonly path: string;
+  movePath?: string;
+};
+
+/**
+ * Lightweight, fault-tolerant scan of V4A patch text into a per-file summary.
+ * For renderers that need to label a patch without depending on the apply-patch
+ * grammar parser; unrecognized lines are ignored rather than throwing.
+ */
+export class PatchSummary {
+  public static fromText(input: string): readonly PatchOp[] {
+    const ops: MutableOp[] = [];
+
+    for (const raw of input.split("\n")) {
+      const line = raw.trim();
+      const op = PatchSummary.fileOp(line);
+      if (op) {
+        ops.push(op);
+      } else if (line.startsWith(MOVE_TO_MARKER)) {
+        const current = ops.at(-1);
+        if (current?.kind === "update") {
+          current.movePath = PatchSummary.clean(
+            line.slice(MOVE_TO_MARKER.length)
+          );
+        }
+      }
+    }
+
+    return ops;
+  }
+
+  // The first affected path, without building the full per-file summary — for
+  // callers that only need a title (e.g. a tool-call header on the render path).
+  public static firstPath(input: string): string | undefined {
+    for (const raw of input.split("\n")) {
+      const op = PatchSummary.fileOp(raw.trim());
+      if (op) {
+        return op.path;
+      }
+    }
+    return undefined;
+  }
+
+  private static fileOp(line: string): MutableOp | undefined {
+    for (const [kind, marker] of FILE_MARKERS) {
+      if (line.startsWith(marker)) {
+        return { kind, path: PatchSummary.clean(line.slice(marker.length)) };
+      }
+    }
+    return undefined;
+  }
+
+  private static clean(raw: string): string {
+    let path = raw.trim();
+    if (path.startsWith("@")) {
+      path = path.slice(1).trim();
+    }
+    if (path.length >= 2) {
+      const first = path[0]!;
+      const last = path.at(-1)!;
+      if ((first === '"' || first === "'" || first === "`") && first === last) {
+        path = path.slice(1, -1);
+      }
+    }
+    return path;
+  }
+}