@computesdk/pi-morph 1.0.1 → 1.0.3

package/README.md

@@ -1,12 +1,16 @@
 # @computesdk/pi-morph
 
-[Morph](https://www.morphllm.com) as a Pi provider: the open-weight coding models on Morph's OpenAI-compatible API.
+[Morph](https://www.morphllm.com) for Pi: the open-weight coding models as a provider, and Morph's single-purpose models as tools.
 
 ```sh
 pi install npm:@computesdk/pi-morph      # or: pi -e /path/to/pi-extensions/packages/pi-morph
 ```
 
-Set `MORPH_API_KEY` in your environment and the models show up in `/model` as `morph/morph-kimik3` and friends.
+Run `/login morph` and paste your key, or set `MORPH_API_KEY` in your environment; one credential covers both halves (the models and the tools), and the environment wins when both are set.
+
+## Models
+
+Set the key and the models show up in `/model` as `morph/morph-kimik3` and friends.
 
 | Model | Input | Context | $/1M in | $/1M out |
 | --- | --- | --- | --- | --- |
@@ -18,13 +22,31 @@ Set `MORPH_API_KEY` in your environment and the models show up in `/model` as `m
 | `morph-dsv41flash-1017` — DeepSeek V4.1 Flash 1017 | text, image | 1M | 0.12 | 0.80 |
 | `morph-dsv4flash` — DeepSeek V4 Flash 0731 | text | 1M | 0.14 | 0.40 |
 
-Endpoint `https://api.morphllm.com/v1`, bearer auth, `api: "openai-completions"` — Pi's built-in implementation does the request, stream and tool-call plumbing, so the whole extension is one `pi.registerProvider` call with the catalog above. Prices are per 1M tokens from [morphllm.com/pricing](https://www.morphllm.com/pricing); `cacheWrite` is not billed. `service_tier: "standby"` halves the price on supported models — Pi can send it through `samplingParams`.
+Endpoint `https://api.morphllm.com/v1`, bearer auth, `api: "openai-completions"` — Pi's built-in implementation does the request, stream and tool-call plumbing, so the provider is one `pi.registerProvider` call with the catalog above. Prices are per 1M tokens from [morphllm.com/pricing](https://www.morphllm.com/pricing); `cacheWrite` is not billed. `service_tier: "standby"` halves the price on supported models — Pi can send it through `samplingParams`.
 
 Pi's thinking levels map onto Morph's `reasoning_effort` ladder (`none | low | high | xhigh | max`). DeepSeek documents `none`, so `off` maps to it; for the other models `off` is marked unsupported (`null`) rather than sent.
 
+## Tools
+
+The same package adds three tools. Morph's single-purpose models take request shapes of their own rather than chat completions, so they are tools here, not entries in the catalog above.
+
+| Tool | What it does | Endpoint |
+| --- | --- | --- |
+| `morph_apply` | Applies an edit to a file with Fast Apply (~10.5k tok/s, ~98% accuracy) | `POST /v1/code/apply` |
+| `morph_compact` | Compresses long text, keeping the parts a follow-up question needs | `POST /v1/compact` |
+| `morph_search` | Answers a code question with the WarpGrep search subagent (~6s) | `POST /v1/chat/completions` with `morph-warp-grep-v2.1` |
+
+`morph_apply` rewrites the file it is given: you pass the lines that change plus `// ... existing code ...` markers for the unchanged spans, and Morph merges the edit in. It is marked `destructiveHint`, so a permission extension can gate it. The other two only read.
+
+`morph_search` is a subagent, not a grep wrapper. It explores the repository in its own context window for up to six turns and returns only the file/line spans it settled on, with their code, so the dead ends never reach your context. Its search tools (`grep_search`, `read`, `list_directory`, `glob`, `finish`) are built into Morph's model; this package executes them locally and feeds the results back.
+
+That local implementation never runs a shell. Morph asks for directory listings as shell commands (`ls -la src`), which are parsed here rather than executed, and every read is confined to the directory the search was given. `node_modules`, `.git`, and build or virtualenv trees are skipped.
+
+Usage from these endpoints is reported to Pi without a cost, because Morph does not publish per-token prices for them.
+
 ## Not included
 
-Morph's single-purpose models — Fast Apply (`morph-v3-fast`, `morph-v3-large`, `auto`), WarpGrep (`morph-warp-grep-v2.1`), Compact and the Router — take bespoke request shapes (XML-edit bodies, `POST /v1/code/apply`, `POST /v1/compact`) rather than chat completions, so they are not chat models and are left out. If they come back it will be as tools in this package, not as models.
+The Model Router (`/v1/router/classify`, `/v1/router/multimodel`) labels how complex a prompt is so a caller can choose a model. It is left out because Pi already picks the model for a session, so there is nothing for a tool to decide.
 
 ## Development
 
@@ -32,6 +54,6 @@ Morph's single-purpose models — Fast Apply (`morph-v3-fast`, `morph-v3-large`,
 pnpm test     # tsc --noEmit && node test.ts
 ```
 
-`test.ts` loads the extension with a fake Pi and checks every registered model: id, name, modalities, context/output limits, costs, uniqueness, and that every Pi thinking level is either mapped to a provider value or explicitly unsupported.
+`test.ts` loads both extensions with a fake Pi. It checks every registered model — id, name, modalities, context and output limits, costs, uniqueness, and that each Pi thinking level is either mapped to a provider value or explicitly unsupported — then exercises the tools' local search implementation against a scratch directory: the repo structure WarpGrep is handed, argument coercion for `grep`/`read`/`list_directory`/`glob`, span parsing, path confinement, and usage mapping. Nothing in the suite touches the network.
 
 MIT licensed.

package/index.ts

@@ -1,5 +1,5 @@
 // Morph — open-weight coding models on an OpenAI-compatible API, plus specialized apply/grep/compact models.
-// Base URL: https://api.morphllm.com/v1 · Auth: Authorization: Bearer <MORPH_API_KEY>.
+// Base URL: https://api.morphllm.com/v1 · Auth: `/login morph` (stored in auth.json) or MORPH_API_KEY in the environment.
 // Docs: https://docs.morphllm.com · Models: https://docs.morphllm.com/sdk/components/fast-models
 //
 // This is a Pi provider extension: `pi.registerProvider` adds the endpoint and its model catalog, and Pi's
@@ -14,11 +14,15 @@
 // Prices are USD per 1M tokens from https://www.morphllm.com/pricing (live at /api/models/json). Update them
 // there when they change.
 
-import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createProvider, envApiKeyAuth, type Model, type ThinkingLevelMap } from "@earendil-works/pi-ai";
+import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
 
-/** Pi's chat-model shape: the chat arm of the provider model union. */
-type ChatModel = Extract<ProviderModelConfig, { type?: "chat" }>;
-type ThinkingLevelMap = NonNullable<ChatModel["thinkingLevelMap"]>;
+const ID = "morph";
+const BASE_URL = "https://api.morphllm.com/v1";
+
+/** Pi's chat-model shape for the one API Morph speaks. */
+type ChatModel = Model<"openai-completions">;
 // Pi thinking levels (off/minimal/low/medium/high/xhigh/max) → the provider's `reasoning_effort` value.
 // Morph documents the ladder for DeepSeek: none | low | high | xhigh | max (`medium`→high, `minimal`→low).
 // For the other models `off` is not documented, so it is marked unsupported (`null`) rather than sent.
@@ -35,6 +39,9 @@ const model = (id: string, name: string, { input = ["text"], cost, effort = EFFO
   type: "chat",
   id,
   name,
+  provider: ID,
+  api: "openai-completions",
+  baseUrl: BASE_URL,
   reasoning: true,
   thinkingLevelMap: effort,
   input,
@@ -54,11 +61,17 @@ export const MODELS: ChatModel[] = [
 ];
 
 export default function morphProvider(pi: ExtensionAPI) {
-  pi.registerProvider("morph", {
-    name: "Morph",
-    baseUrl: "https://api.morphllm.com/v1",
-    apiKey: "$MORPH_API_KEY",
-    api: "openai-completions",
-    models: MODELS,
-  });
+  // A complete provider rather than the name+config form, because that is what carries native
+  // auth: envApiKeyAuth gives `/login morph` a key prompt, stores the credential in auth.json,
+  // and falls back to MORPH_API_KEY in the environment when nothing is stored.
+  pi.registerProvider(
+    createProvider({
+      id: ID,
+      name: "Morph",
+      baseUrl: BASE_URL,
+      auth: { apiKey: envApiKeyAuth("Morph API key", ["MORPH_API_KEY"]) },
+      models: MODELS,
+      api: openAICompletionsApi(),
+    }),
+  );
 }

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@computesdk/pi-morph",
-  "version": "1.0.1",
-  "description": "Morph provider for Pi: open-weight coding models (Kimi K3, GLM 5.3, DeepSeek V4) on Morph's OpenAI-compatible API.",
+  "version": "1.0.3",
+  "description": "Morph for Pi: open-weight coding models (Kimi K3, GLM 5.3, DeepSeek V4) on Morph's OpenAI-compatible API, plus Fast Apply, Compact, and WarpGrep as tools.",
   "keywords": [
     "pi-package",
     "pi",
     "pi-extension",
     "provider",
+    "tools",
     "morph",
     "morphllm",
+    "warpgrep",
     "openai-compatible"
   ],
   "license": "MIT",
@@ -30,11 +32,13 @@
   },
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./index.ts",
+      "./tools/index.ts"
     ]
   },
   "files": [
     "index.ts",
+    "tools",
     "README.md",
     "LICENSE"
   ],
@@ -43,11 +47,15 @@
     "test": "tsc --noEmit && node test.ts"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": "catalog:",
     "@earendil-works/pi-coding-agent": "catalog:",
     "@types/node": "catalog:",
+    "typebox": "catalog:",
     "typescript": "catalog:"
   }
 }

package/tools/api.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared plumbing for Morph's single-purpose endpoints.
+ *
+ * The chat models in `../index.ts` go through Pi's OpenAI-compatible provider implementation.
+ * Fast Apply, Compact, and WarpGrep have bespoke request shapes, so the tools call them directly.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const BASE_URL = "https://api.morphllm.com/v1";
+
+/** Morph reports OpenAI-style token counts. */
+export interface MorphUsage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+}
+
+/** Structurally the `Usage` that `AgentToolResult` carries. */
+export interface Usage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number };
+}
+
+/**
+ * Morph does not publish per-token prices for the specialized endpoints, so their usage is
+ * reported with no cost rather than a guessed one.
+ */
+export function usageFrom(usage: MorphUsage | undefined): Usage {
+  const input = usage?.prompt_tokens ?? 0;
+  const output = usage?.completion_tokens ?? 0;
+  return {
+    input,
+    output,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: usage?.total_tokens ?? input + output,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+}
+
+/**
+ * One credential covers models and tools: `MORPH_API_KEY` in the environment, or the key
+ * `/login morph` stored in the agent directory's auth.json (the provider resolves the same two,
+ * stored first; here the env var wins so the shell can override a stored key).
+ */
+export function apiKey(): string {
+  const key = process.env.MORPH_API_KEY?.trim() || storedKey();
+  if (!key) throw new Error("MORPH_API_KEY is not set and no Morph credential is stored; set it or run /login morph");
+  return key;
+}
+
+/** Read the key `/login morph` wrote. Only literal keys: a "!command" credential is Pi-side resolution. */
+function storedKey(): string | undefined {
+  try {
+    const dir = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+    const key = JSON.parse(fs.readFileSync(path.join(dir, "auth.json"), "utf8"))?.morph?.key;
+    return typeof key === "string" && !key.startsWith("!") ? key : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** POST JSON to Morph. A non-2xx response becomes a tool error. */
+export async function post<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${apiKey()}`, "content-type": "application/json" },
+    body: JSON.stringify(body),
+    signal,
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Morph ${path} failed: ${res.status} ${res.statusText}${text ? ` — ${text.slice(0, 400)}` : ""}`);
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`Morph ${path} returned a non-JSON body: ${text.slice(0, 200)}`);
+  }
+}
+
+/** Cap a model-facing result and say what was dropped. */
+export function cap(lines: string[], max: number, hint: string): string {
+  if (lines.length <= max) return lines.join("\n");
+  return `${lines.slice(0, max).join("\n")}\n... ${lines.length - max} more lines dropped; ${hint}`;
+}

package/tools/apply.ts

@@ -0,0 +1,71 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { defineTool, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { post, usageFrom, type MorphUsage } from "./api.ts";
+
+/** Fast Apply merges an edit snippet into an existing file. `auto` lets Morph pick the model. */
+export const APPLY_MODELS = ["auto", "morph-v3-fast", "morph-v3-large"] as const;
+
+export const ApplyParams = Type.Object({
+  path: Type.String({ description: "File to edit, relative to the working directory" }),
+  instructions: Type.String({
+    description: 'One first-person sentence describing the change, e.g. "I am adding error handling to divide()". Used to disambiguate the edit.',
+  }),
+  edit: Type.String({
+    description: "Only the lines that change, with `// ... existing code ...` marking the unchanged spans in between",
+  }),
+  model: Type.Optional(
+    Type.Union(
+      APPLY_MODELS.map((model) => Type.Literal(model)),
+      { description: "Fast Apply model. Default: auto." },
+    ),
+  ),
+});
+
+interface ApplyResponse {
+  mergedCode?: string;
+  merged_code?: string;
+  usage?: MorphUsage;
+}
+
+export const applyTool = defineTool({
+  name: "morph_apply",
+  label: "Fast Apply",
+  description:
+    "Edit a file with Morph's Fast Apply model (10,500+ tok/s, ~98% accuracy). Send the lines that change plus `// ... existing code ...` markers for the unchanged spans between them, and the file is rewritten with the edit merged in. Use it when you know what to write but the edit is spread across a large file; use `edit` for exact, mechanical replacements.",
+  promptSnippet: "morph_apply: edit a file through Morph's Fast Apply model",
+  parameters: ApplyParams,
+  annotations: { destructiveHint: true, openWorldHint: true },
+  async execute(_toolCallId, params, signal, onUpdate, ctx) {
+    const file = path.resolve(ctx.cwd, params.path);
+    const model = params.model ?? "auto";
+    return withFileMutationQueue(file, async () => {
+      let original: string;
+      try {
+        original = await fs.readFile(file, "utf8");
+      } catch {
+        throw new Error(`cannot read ${params.path}; Fast Apply merges into an existing file`);
+      }
+      onUpdate?.({
+        content: [{ type: "text", text: `Fast Apply (${model}) → ${params.path}` }],
+        details: { path: params.path, model },
+      });
+      const res = await post<ApplyResponse>(
+        "/code/apply",
+        { initial_code: original, edit_snippet: params.edit, instructions: params.instructions, model },
+        signal,
+      );
+      const merged = res.mergedCode ?? res.merged_code;
+      if (typeof merged !== "string") throw new Error("Morph returned no merged code");
+      await fs.writeFile(file, merged, "utf8");
+      const before = original.split("\n").length;
+      const after = merged.split("\n").length;
+      return {
+        content: [{ type: "text", text: `Applied ${params.path} with ${model}: ${before} → ${after} lines` }],
+        details: { path: params.path, model, lines: { before, after } },
+        usage: usageFrom(res.usage),
+      };
+    });
+  },
+});

package/tools/compact.ts

@@ -0,0 +1,54 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { post, usageFrom, type MorphUsage } from "./api.ts";
+
+export const CompactParams = Type.Object({
+  input: Type.String({ description: "Text to compress: source code, a log, a chat transcript, or a mix" }),
+  query: Type.Optional(
+    Type.String({ description: "What the follow-up needs; without it Morph infers the intent from the input" }),
+  ),
+  ratio: Type.Optional(
+    Type.Number({ minimum: 0, maximum: 1, description: "Target compression ratio, e.g. 0.5 keeps about half" }),
+  ),
+  preserve_recent: Type.Optional(Type.Number({ minimum: 0, description: "Trailing messages to keep verbatim" })),
+});
+
+interface CompactResponse {
+  output?: string;
+  messages?: unknown;
+  usage?: MorphUsage;
+}
+
+export const compactTool = defineTool({
+  name: "morph_compact",
+  label: "Compact",
+  description:
+    "Compress text with Morph's Compact model (~33k tok/s), keeping the parts a follow-up question needs. Use it on long code, logs, or transcripts before they go into context. Returns the compressed text; nothing else changes.",
+  promptSnippet: "morph_compact: compress long text through Morph's Compact model",
+  parameters: CompactParams,
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+  async execute(_toolCallId, params, signal) {
+    const res = await post<CompactResponse>(
+      "/compact",
+      {
+        input: params.input,
+        query: params.query,
+        compression_ratio: params.ratio,
+        preserve_recent: params.preserve_recent,
+      },
+      signal,
+    );
+    const output = res.output;
+    if (typeof output !== "string") throw new Error("Morph returned no compacted output");
+    const before = params.input.length;
+    const after = output.length;
+    return {
+      content: [{ type: "text", text: output }],
+      details: {
+        chars: { before, after },
+        ratio: before > 0 ? Number((after / before).toFixed(3)) : 1,
+      },
+      usage: usageFrom(res.usage),
+    };
+  },
+});

package/tools/index.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { applyTool } from "./apply.ts";
+import { compactTool } from "./compact.ts";
+import { searchTool } from "./search.ts";
+
+/**
+ * Morph's specialized models as Pi tools: Fast Apply, Compact, and WarpGrep.
+ *
+ * The provider in `../index.ts` serves the chat models. These three endpoints take bespoke
+ * request shapes, so they are tools rather than entries in the provider's model catalog.
+ */
+export default function morphTools(pi: ExtensionAPI) {
+  pi.registerTool?.(applyTool);
+  pi.registerTool?.(compactTool);
+  pi.registerTool?.(searchTool);
+}

package/tools/search.ts

@@ -0,0 +1,487 @@
+/**
+ * WarpGrep: a code-search subagent.
+ *
+ * `morph-warp-grep-v2.1` explores a repository in its own context window and returns only the
+ * file/line spans it settled on. The model has its search tools built in, so this module executes
+ * its calls locally and feeds the results back, turn by turn, until it calls `finish`.
+ *
+ * These tools never shell out. Morph's reference implementation pipes the model's own
+ * `list_directory` command through a shell; that command is model-written text influenced by
+ * whatever is in the repository, so here a bare `ls <path>` is parsed and every read is confined
+ * to the search root.
+ */
+
+import fs from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import path from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { BASE_URL, cap, post, usageFrom, type MorphUsage, type Usage } from "./api.ts";
+
+export const WARP_GREP_MODEL = "morph-warp-grep-v2.1";
+
+const MAX_TURNS = 6;
+const MAX_STRUCTURE_LINES = 2000;
+const MAX_WALKED_FILES = 20_000;
+const MAX_FILE_BYTES = 1_000_000;
+const LIMITS = { grep: 200, read: 800, list: 500, glob: 100 };
+const SKIP = new Set([".git", "node_modules", ".pi", ".venv", "__pycache__", ".next", "dist", "build"]);
+
+export const SearchParams = Type.Object({
+  query: Type.String({ description: "What to find, in plain language, e.g. \"where are rate limits enforced?\"" }),
+  path: Type.Optional(Type.String({ description: "Directory to search. Default: the working directory." })),
+  turns: Type.Optional(
+    Type.Number({ minimum: 1, maximum: 10, description: `Exploration turns to allow. Default: ${MAX_TURNS}.` }),
+  ),
+});
+
+export interface Span {
+  path: string;
+  ranges: { start: number; end: number }[];
+}
+
+interface ChatToolCall {
+  id: string;
+  type?: string;
+  function?: { name?: string; arguments?: string };
+}
+
+interface ChatMessage {
+  role: string;
+  content?: string | null;
+  tool_calls?: ChatToolCall[];
+  tool_call_id?: string;
+}
+
+interface ChatResponse {
+  choices?: { message?: { content?: string | null; tool_calls?: ChatToolCall[] } }[];
+  usage?: MorphUsage;
+}
+
+interface SearchDetails {
+  query: string;
+  turns: number;
+  spans: Span[];
+}
+
+/* ------------------------------------------------------------------ arguments */
+
+const asStr = (value: unknown): string | undefined =>
+  typeof value === "string" && value.trim() ? value.trim() : undefined;
+
+/** Morph sends loose argument types: `limit` may be the string "50", `case_sensitive` the string "false". */
+const asInt = (value: unknown): number | undefined => {
+  const n = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : Number.NaN;
+  return Number.isFinite(n) ? n : undefined;
+};
+
+const asBool = (value: unknown): boolean | undefined => {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    if (/^(true|1|yes)$/i.test(value)) return true;
+    if (/^(false|0|no)$/i.test(value)) return false;
+  }
+  return undefined;
+};
+
+export function parseArgs(raw: unknown): Record<string, unknown> {
+  if (typeof raw !== "string" || !raw.trim()) return {};
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Resolve a model-supplied path and keep it inside the search root. */
+export function within(root: string, candidate: string | undefined): string {
+  const abs = path.resolve(root, candidate ?? ".");
+  const rel = path.relative(root, abs);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(`refusing to leave the search root: ${candidate}`);
+  }
+  return abs;
+}
+
+/** `**`, `*`, and `?` against a relative path. */
+export function globToRegExp(pattern: string): RegExp {
+  let out = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i] as string;
+    if (char === "*") {
+      if (pattern[i + 1] === "*") {
+        out += ".*";
+        i++;
+        if (pattern[i + 1] === "/") i++;
+      } else {
+        out += "[^/]*";
+      }
+    } else if (char === "?") {
+      out += "[^/]";
+    } else {
+      out += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/* ---------------------------------------------------------------------- files */
+
+async function walk(dir: string, out: string[]): Promise<void> {
+  if (out.length >= MAX_WALKED_FILES) return;
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (out.length >= MAX_WALKED_FILES) return;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP.has(entry.name)) continue;
+      await walk(full, out);
+    } else if (entry.isFile()) {
+      out.push(full);
+    }
+  }
+}
+
+async function collect(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  await walk(dir, out);
+  return out;
+}
+
+/** Text of a file, or undefined when it is binary, unreadable, or oversized. */
+async function readText(file: string): Promise<string | undefined> {
+  try {
+    const stat = await fs.stat(file);
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return undefined;
+    const text = await fs.readFile(file, "utf8");
+    return text.includes("\0") ? undefined : text;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Flat list of absolute paths: the root, then everything to `depth`, as WarpGrep expects. */
+export async function repoStructure(root: string, depth = 2): Promise<string> {
+  const out = [root];
+  let level = [root];
+  for (let d = 1; d <= depth; d++) {
+    const next: string[] = [];
+    for (const dir of level) {
+      let entries: Dirent[];
+      try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.isSymbolicLink() || SKIP.has(entry.name)) continue;
+        if (!entry.isDirectory() && !entry.isFile()) continue;
+        const full = path.join(dir, entry.name);
+        out.push(full);
+        if (entry.isDirectory()) next.push(full);
+        if (out.length >= MAX_STRUCTURE_LINES) return out.join("\n");
+      }
+    }
+    level = next;
+  }
+  return out.join("\n");
+}
+
+/* ------------------------------------------------------------------ the tools */
+
+export async function grepSearch(root: string, args: Record<string, unknown>): Promise<string> {
+  const pattern = asStr(args.pattern) ?? asStr(args.query) ?? asStr(args.search);
+  if (!pattern) return "grep_search needs a `pattern`.";
+  const dir = within(root, asStr(args.path));
+  const limit = asInt(args.limit ?? args.output_lines) ?? LIMITS.grep;
+  const context = asInt(args.output_context_lines ?? args.context_lines) ?? 0;
+  const caseSensitive = asBool(args.case_sensitive) ?? false;
+  let re: RegExp;
+  try {
+    re = new RegExp(pattern, caseSensitive ? "" : "i");
+  } catch (err) {
+    return `grep_search: invalid pattern ${pattern} — ${(err as Error).message}`;
+  }
+  const hits: string[] = [];
+  for (const file of await collect(dir)) {
+    const text = await readText(file);
+    if (text === undefined) continue;
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      if (!re.test(lines[i] as string)) continue;
+      const from = Math.max(0, i - context);
+      const to = Math.min(lines.length - 1, i + context);
+      for (let c = from; c <= to; c++) hits.push(`${path.relative(root, file)}:${c + 1}:${lines[c]}`);
+      if (hits.length >= limit) return cap(hits, limit, "narrow the pattern or lower `limit`");
+    }
+  }
+  return hits.length ? cap(hits, limit, "narrow the pattern") : "no matches";
+}
+
+export async function readLines(root: string, args: Record<string, unknown>): Promise<string> {
+  const target = asStr(args.path) ?? asStr(args.file) ?? asStr(args.file_path) ?? asStr(args.target_file);
+  if (!target) return "read needs a `path`.";
+  const text = await readText(within(root, target));
+  if (text === undefined) return `read: cannot read ${target} (missing, binary, or larger than ${MAX_FILE_BYTES} bytes)`;
+  const all = text.split("\n");
+  const spec = asStr(args.lines);
+  const selected: number[] = [];
+  if (spec) {
+    for (const part of spec.split(",")) {
+      const [start, end] = part.split("-").map((value) => Number.parseInt(value, 10));
+      if (!Number.isFinite(start)) continue;
+      const last = Number.isFinite(end as number) ? (end as number) : (start as number);
+      for (let i = start as number; i <= last; i++) if (i >= 1 && i <= all.length) selected.push(i);
+    }
+  } else {
+    const start = asInt(args.start) ?? asInt(args.start_line) ?? 1;
+    const end = asInt(args.end) ?? asInt(args.end_line) ?? Math.min(all.length, start + LIMITS.read - 1);
+    for (let i = start; i <= end && i <= all.length; i++) selected.push(i);
+  }
+  if (!selected.length) return `read: no lines in range for ${target}`;
+  return cap(
+    selected.slice(0, LIMITS.read).map((n) => `${n}|${all[n - 1]}`),
+    LIMITS.read,
+    "ask for a narrower line range",
+  );
+}
+
+/** Morph asks for listings as shell commands (`ls -la src`). Parse them; never run them. */
+export async function listDirectory(root: string, args: Record<string, unknown>): Promise<string> {
+  const raw = asStr(args.command) ?? asStr(args.path) ?? ".";
+  const parsed = raw
+    .replace(/^\s*ls\b/, "")
+    .split(/\s+/)
+    .filter((token) => token && !token.startsWith("-"))
+    .join(" ");
+  const target = parsed || asStr(args.path) || ".";
+  const dir = within(root, target);
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return `list_directory: cannot list ${target}`;
+  }
+  const lines = entries
+    .filter((entry) => !SKIP.has(entry.name))
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((entry) => `${path.join(target, entry.name)}${entry.isDirectory() ? "/" : ""}`);
+  return lines.length ? cap(lines, LIMITS.list, "list a subdirectory") : `${target} is empty`;
+}
+
+export async function globFiles(root: string, args: Record<string, unknown>): Promise<string> {
+  const pattern = asStr(args.pattern) ?? asStr(args.glob) ?? "*";
+  const base = within(root, asStr(args.path));
+  const re = globToRegExp(pattern);
+  const matched: string[] = [];
+  for (const file of await collect(base)) {
+    const rel = path.relative(base, file);
+    if (re.test(rel) || re.test(path.basename(file))) matched.push(file);
+  }
+  const stamped = await Promise.all(
+    matched.map(async (file) => ({
+      file,
+      mtime: await fs.stat(file).then((stat) => stat.mtimeMs).catch(() => 0),
+    })),
+  );
+  stamped.sort((a, b) => b.mtime - a.mtime);
+  if (!stamped.length) return `no files match ${pattern}`;
+  return cap(
+    stamped.map((entry) => path.relative(root, entry.file)),
+    LIMITS.glob,
+    "narrow the pattern",
+  );
+}
+
+export async function runSearchTool(root: string, call: ChatToolCall): Promise<string> {
+  const name = (call.function?.name ?? "").toLowerCase();
+  const args = parseArgs(call.function?.arguments);
+  try {
+    switch (name) {
+      case "grep":
+      case "grep_search":
+        return await grepSearch(root, args);
+      case "read":
+      case "read_file":
+        return await readLines(root, args);
+      case "list_directory":
+      case "ls":
+        return await listDirectory(root, args);
+      case "glob":
+      case "find":
+        return await globFiles(root, args);
+      default:
+        return `unknown tool ${name}; available: grep_search, read, list_directory, glob, finish`;
+    }
+  } catch (err) {
+    return `${name}: ${(err as Error).message}`;
+  }
+}
+
+/* --------------------------------------------------------------------- finish */
+
+/** `finish` reports spans as newline-separated `path:1-50,60-70` or `path:*` specs. */
+export function parseSpans(files: unknown): Span[] {
+  const specs = Array.isArray(files)
+    ? files.map((entry) => (typeof entry === "string" ? entry : String((entry as { path?: string })?.path ?? "")))
+    : typeof files === "string"
+      ? files.split("\n")
+      : [];
+  const spans: Span[] = [];
+  for (const raw of specs) {
+    const spec = raw.trim();
+    if (!spec) continue;
+    const colon = spec.lastIndexOf(":");
+    const hasRange = colon > 0 && !spec.endsWith(":*");
+    const file = hasRange ? spec.slice(0, colon) : spec.replace(/:\*$/, "");
+    const range = hasRange ? spec.slice(colon + 1) : "";
+    const ranges = range
+      .split(",")
+      .map((part) => {
+        const [start, end] = part.split("-").map((value) => Number.parseInt(value, 10));
+        return Number.isFinite(start) ? { start: start as number, end: Number.isFinite(end as number) ? (end as number) : (start as number) } : undefined;
+      })
+      .filter((entry): entry is { start: number; end: number } => entry !== undefined);
+    spans.push({ path: file, ranges });
+  }
+  return spans;
+}
+
+/** The code the spans point at, which is all the parent agent sees of the search. */
+export async function spanText(root: string, spans: Span[]): Promise<string> {
+  const parts: string[] = [];
+  for (const span of spans) {
+    let text: string | undefined;
+    try {
+      text = await readText(within(root, span.path));
+    } catch {
+      text = undefined;
+    }
+    if (text === undefined) {
+      parts.push(`${span.path} (unreadable)`);
+      continue;
+    }
+    const all = text.split("\n");
+    const ranges = span.ranges.length ? span.ranges : [{ start: 1, end: Math.min(all.length, LIMITS.read) }];
+    const body: string[] = [];
+    for (const range of ranges) {
+      for (let i = Math.max(1, range.start); i <= Math.min(all.length, range.end); i++) body.push(`${i}|${all[i - 1]}`);
+    }
+    parts.push(`${span.path}\n${cap(body, LIMITS.read, "read the file for the rest")}`);
+  }
+  return parts.join("\n\n");
+}
+
+/* ----------------------------------------------------------------------- loop */
+
+export interface SearchResult {
+  answer: string;
+  spans: Span[];
+  turns: number;
+  usage: Usage;
+}
+
+function turnNote(turn: number, maxTurns: number): string {
+  const remaining = maxTurns - turn;
+  const note = `You have used ${turn} turn${turn === 1 ? "" : "s"} and have ${remaining} remaining.`;
+  return remaining <= 1 ? `${note} You have run out of turns to explore the code base and MUST call the finish tool now.` : note;
+}
+
+export interface SearchOptions {
+  signal?: AbortSignal;
+  maxTurns?: number;
+  onTurn?: (turn: number, tools: string[]) => void;
+}
+
+export async function warpgrep(root: string, query: string, options: SearchOptions = {}): Promise<SearchResult> {
+  const maxTurns = Math.min(Math.max(options.maxTurns ?? MAX_TURNS, 1), 10);
+  const structure = await repoStructure(root);
+  const messages: ChatMessage[] = [
+    { role: "user", content: `<repo_structure>\n${structure}\n</repo_structure>\n\n<search_string>\n${query}\n</search_string>` },
+  ];
+  const total: MorphUsage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+
+  for (let turn = 1; turn <= maxTurns; turn++) {
+    const res = await post<ChatResponse>(
+      "/chat/completions",
+      { model: WARP_GREP_MODEL, messages, temperature: 0, max_tokens: 2048 },
+      options.signal,
+    );
+    total.prompt_tokens = (total.prompt_tokens ?? 0) + (res.usage?.prompt_tokens ?? 0);
+    total.completion_tokens = (total.completion_tokens ?? 0) + (res.usage?.completion_tokens ?? 0);
+    total.total_tokens = (total.total_tokens ?? 0) + (res.usage?.total_tokens ?? 0);
+
+    const message = res.choices?.[0]?.message;
+    const calls = message?.tool_calls ?? [];
+    options.onTurn?.(turn, calls.map((call) => call.function?.name ?? "?"));
+
+    const finish = calls.find((call) => (call.function?.name ?? "").toLowerCase() === "finish");
+    if (finish) {
+      const spans = parseSpans(parseArgs(finish.function?.arguments).files);
+      return { answer: await spanText(root, spans), spans, turns: turn, usage: usageFrom(total) };
+    }
+    if (!calls.length) {
+      const prose = typeof message?.content === "string" ? message.content.trim() : "";
+      return { answer: prose, spans: [], turns: turn, usage: usageFrom(total) };
+    }
+
+    messages.push({ role: "assistant", content: message?.content ?? null, tool_calls: calls });
+    const results = await Promise.all(calls.map((call) => runSearchTool(root, call)));
+    for (let i = 0; i < calls.length; i++) {
+      messages.push({ role: "tool", tool_call_id: (calls[i] as ChatToolCall).id, content: results[i] as string });
+    }
+    messages.push({ role: "user", content: turnNote(turn, maxTurns) });
+  }
+  return { answer: "", spans: [], turns: maxTurns, usage: usageFrom(total) };
+}
+
+/* ----------------------------------------------------------------------- tool */
+
+export const searchTool = defineTool({
+  name: "morph_search",
+  label: "WarpGrep",
+  description:
+    "Search a codebase with Morph's WarpGrep subagent (~6s). Give it a plain-language question such as \"where are rate limits enforced?\" and it explores the repository in its own context window for a few turns, then returns only the file/line spans it settled on and their code. Use it for where/what/why questions that span many files; use `grep` when you already know the exact string.",
+  promptSnippet: "morph_search: answer a code question with Morph's WarpGrep search subagent",
+  parameters: SearchParams,
+  annotations: { readOnlyHint: true, openWorldHint: true },
+  async execute(_toolCallId, params, signal, onUpdate, ctx) {
+    const root = path.resolve(ctx.cwd, params.path ?? ".");
+    const result = await warpgrep(root, params.query, {
+      signal,
+      maxTurns: params.turns,
+      onTurn: (turn, tools) =>
+        onUpdate?.({
+          content: [{ type: "text", text: `WarpGrep turn ${turn}: ${tools.join(", ") || "thinking"}` }],
+          details: { query: params.query, turns: turn, spans: [] },
+        }),
+    });
+    const details: SearchDetails = { query: params.query, turns: result.turns, spans: result.spans };
+    if (!result.answer) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `WarpGrep did not converge within ${result.turns} turns on: ${params.query}. Try a narrower query, or grep for a string you can name.`,
+          },
+        ],
+        details,
+        usage: result.usage,
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: result.answer }],
+      details,
+      usage: result.usage,
+    };
+  },
+});
+
+export { BASE_URL };