@harperfast/agent 0.13.8-ink → 0.14.0

package/README.md

@@ -13,22 +13,11 @@ AI to help you with Harper app creation and management.
 
 ## Getting Started
 
-When you first run `harper-agent`, it will prompt you for an API key if one is not found in your environment. It will then automatically save it to a `.env` file in your current working directory.
+When you first run `harper-agent`, it will guide you through setting up your environment.
 
-If you prefer to set it manually, you can create a `.env` file:
+![What model provider would you like to use today? OpenAI, Anthropic, Google or Ollama](guidance/pick-a-provider.png)
 
-```bash
-# For OpenAI (default)
-OPENAI_API_KEY=your_api_key_here
-
-# For Anthropic
-ANTHROPIC_API_KEY=your_api_key_here
-
-# For Google Gemini
-GOOGLE_GENERATIVE_AI_API_KEY=your_api_key_here
-```
-
-(If you'd rather export these environment variables from within your .zshrc or equivalent file, you can do that instead.)
+It will then automatically save it to either `~/.harper/harper-agent-env` or your local `.env` file in your current working directory.
 
 Now install harper-agent:
 
@@ -44,33 +33,44 @@ npx -y @harperfast/agent
 
 You're ready to go!
 
-```bash
-> harper-agent
+![What would you like to create together?](guidance/what-would-you-like-to-create-together.png)
 
-Working directory: /Users/dawson/Code/softwork-beats
-Harper app detected: Yes
-Press Ctrl+C or hit enter twice to exit.
+## Usage
 
-Harper: What do you want to do together today?
+Once installed or running, you can ask harper-agent to help you with tasks in your current directory, such as applying patches or managing your Harper application.
 
->
-```
+Press `Ctrl+C` or type "exit" or hit enter twice to exit.
 
-### Non-interactive: pipe an initial prompt
+### Non-interactive: pass an initial prompt
 
-You can pass an initial chat dump via stdin. This runs a one-shot interaction and exits after responding:
+You can pass an initial `--prompt=`. Harper Agent will turn that into an actionable plan, and then it will iterate until it completes it.
 
 ```bash
-cat somePrompt.md | harper-agent
-# or
-harper-agent < somePrompt.md
+harper-agent --prompt="Write a poem generation app, please"
 ```
 
 In this mode, the initial greeting question is suppressed, and the agent processes the provided prompt immediately.
 
+## Manual Environment Configuration
+
+If you prefer to set up your environment manually, you can create a `.env` file:
+
+```bash
+# For OpenAI (default)
+OPENAI_API_KEY=your_api_key_here
+
+# For Anthropic
+ANTHROPIC_API_KEY=your_api_key_here
+
+# For Google Gemini
+GOOGLE_GENERATIVE_AI_API_KEY=your_api_key_here
+```
+
+(If you'd rather export these environment variables from within your .zshrc or equivalent file, you can do that instead.)
+
 ## Model Selection
 
-By default, `harper-agent` uses OpenAI. You can switch to other models using the `--model` (or `-m`) flag:
+When you first fire up Harper Agent, it will ask you what model you want to use. You can also control this with command line arguments:
 
 ```bash
 # Use Claude 3.5 Sonnet
@@ -83,11 +83,11 @@ harper-agent --model gemini-3-pro
 harper-agent --model gpt-5.2
 ```
 
-You can also set the default model via the `HARPER_AGENT_MODEL` environment variable.
+Or you can set the default model via the `HARPER_AGENT_MODEL` environment variable in your `.env` file or in `~/.harper/harper-agent-env`
 
 ### Compaction Model
 
-By default, `harper-agent` uses `gpt-5-nano` for session memory compaction. You can switch this to another model using the `--compaction-model` (or `-c`) flag:
+A smaller model will be used for compaction, depending on your chosen LLM provider. You can specify your model using the `--compaction-model` (or `-c`) flag:
 
 ```bash
 # Use a different compaction model
@@ -98,7 +98,7 @@ You can also set the default compaction model via the `HARPER_AGENT_COMPACTION_M
 
 ### Session Persistence
 
-By default, `harper-agent` uses an in-memory session that is lost when you exit. You can persist your chat session to a SQLite database on disk using the `--session` (or `-s`) flag:
+Harper Agent will ask if it can persist your chat session to a JSON database on disk using the `--session` (or `-s`) flag:
 
 ```bash
 # Persist session to a file
@@ -176,9 +176,3 @@ npm link
 ```
 
 Now you can run `harper-agent` from any directory.
-
-## Usage
-
-Once installed or running, you can ask harper-agent to help you with tasks in your current directory, such as applying patches or managing your Harper application.
-
-Press `Ctrl+C` or hit enter twice to exit.

package/dist/agent.js

@@ -994,6 +994,25 @@ var WorkspaceEditor = class {
       return { status: "failed", output: `Error updating ${operation.path}: ${String(err)}` };
     }
   }
+  async overwriteFile(operation) {
+    try {
+      const targetPath = resolvePath(this.root(), operation.path);
+      await mkdir(path4.dirname(targetPath), { recursive: true });
+      const normalizedInput = normalizeDiff(operation.diff);
+      const lines = normalizedInput.split(/\r?\n/);
+      const hasDiffMarkers = lines.some((line) => line.startsWith("+") || line.startsWith("-"));
+      let finalContent;
+      if (hasDiffMarkers) {
+        finalContent = lines.filter((line) => !line.startsWith("-")).map((line) => line.startsWith("+") || line.startsWith(" ") ? line.slice(1) : line).join("\n");
+      } else {
+        finalContent = normalizedInput;
+      }
+      await writeFile(targetPath, finalContent, "utf8");
+      return { status: "completed", output: `Overwrote ${operation.path}` };
+    } catch (err) {
+      return { status: "failed", output: `Error overwriting ${operation.path}: ${String(err)}` };
+    }
+  }
   async deleteFile(operation) {
     try {
       const targetPath = resolvePath(this.root(), operation.path);
@@ -1010,10 +1029,12 @@ var WorkspaceEditor = class {
 
 // tools/files/applyPatchTool.ts
 var ApplyPatchParameters = z11.object({
-  type: z11.enum(["create_file", "update_file", "delete_file"]).describe("The type of operation to perform."),
+  type: z11.enum(["create_file", "update_file", "delete_file", "overwrite_file"]).describe(
+    "The type of operation to perform."
+  ),
   path: z11.string().describe("The path to the file to operate on."),
   diff: z11.string().optional().default("").describe(
-    'The diff to apply. For create_file, every line must start with "+". For update_file, use a headerless unified diff format (start sections with "@@", and use "+", "-", or " " for lines). Do not include markers like "*** Begin Patch" or "*** Add File:".'
+    'The diff to apply. For create_file, every line must start with "+". For update_file, use a headerless unified diff format (start sections with "@@", and use "+", "-", or " " for lines). For overwrite_file, the diff is the raw content of the file. Do not include markers like "*** Begin Patch" or "*** Add File:".'
   )
 });
 function normalizedPath(p) {
@@ -1108,6 +1129,11 @@ async function execute11(operation) {
           return { status: "failed", output: "Error: diff is required for update_file" };
         }
         return await editor.updateFile(operation);
+      case "overwrite_file":
+        if (!operation.diff) {
+          return { status: "failed", output: "Error: diff is required for overwrite_file" };
+        }
+        return await editor.overwriteFile(operation);
       case "delete_file":
         return await editor.deleteFile(operation);
       default:
@@ -2683,9 +2709,96 @@ function excludeFalsy(item) {
   return !!item;
 }
 
+// utils/models/estimateTokens.ts
+function estimateTokens(items) {
+  let chars = 0;
+  for (const it of items) {
+    if (!it) {
+      continue;
+    }
+    if (Array.isArray(it.content)) {
+      for (const c of it.content) {
+        if (!c) {
+          continue;
+        }
+        if (typeof c.text === "string") {
+          chars += c.text.length;
+        } else if (typeof c.content === "string") {
+          chars += c.content.length;
+        } else if (typeof c === "string") {
+          chars += c.length;
+        }
+      }
+    }
+    if (typeof it.content === "string") {
+      chars += it.content.length;
+    }
+    if (typeof it.text === "string") {
+      chars += it.text.length;
+    }
+    if (it.type === "function_call" && it.call) {
+      chars += JSON.stringify(it.call).length;
+    }
+    if (it.type === "function_call_result" && it.result) {
+      chars += JSON.stringify(it.result).length;
+    }
+  }
+  return Math.ceil(chars / 4);
+}
+
 // utils/sessions/compactConversation.ts
 import { Agent, run, system } from "@openai/agents";
 
+// utils/models/splitItemsIntelligently.ts
+function splitItemsIntelligently(items, targetRecentCount = 3) {
+  let splitIndex = Math.max(0, items.length - targetRecentCount);
+  while (splitIndex > 0 && splitIndex < items.length) {
+    const itemAtSplit = items[splitIndex];
+    if (itemAtSplit.type === "function_call_result") {
+      splitIndex--;
+    } else {
+      break;
+    }
+  }
+  return {
+    itemsToCompact: items.slice(0, splitIndex),
+    recentItems: items.slice(splitIndex)
+  };
+}
+
+// utils/sessions/modelContextLimits.ts
+function getModelContextLimit(modelName) {
+  if (!modelName) {
+    return DEFAULT_LIMIT;
+  }
+  const name = modelName.toLowerCase();
+  if (name.startsWith("gpt-")) {
+    if (name.startsWith("gpt-4")) {
+      return 128e3;
+    }
+    return 2e5;
+  }
+  if (name.startsWith("claude-")) {
+    if (name.startsWith("claude-3.7") || name.startsWith("claude-3.5") || name.startsWith("claude-3")) {
+      return 2e5;
+    }
+    return 1e6;
+  }
+  if (name.startsWith("gemini-")) {
+    return 1e6;
+  }
+  if (name.startsWith("ollama-")) {
+    return 8e3;
+  }
+  return DEFAULT_LIMIT;
+}
+function getCompactionTriggerTokens(modelName, fraction = 0.5) {
+  const limit = getModelContextLimit(modelName);
+  const f = Math.min(Math.max(fraction, 0.5), 0.95);
+  return Math.floor(limit * f);
+}
+var DEFAULT_LIMIT = 128e3;
+
 // utils/sessions/modelSettings.ts
 var modelsRequiringMediumVerbosity = [
   "gpt-4o"
@@ -2706,17 +2819,9 @@ function getModelSettings(modelName) {
 
 // utils/sessions/compactConversation.ts
 async function compactConversation(items) {
-  let splitIndex = Math.max(0, items.length - 3);
-  while (splitIndex > 0 && splitIndex < items.length) {
-    const itemAtSplit = items[splitIndex];
-    if (itemAtSplit.type === "function_call_result") {
-      splitIndex--;
-    } else {
-      break;
-    }
-  }
-  const recentItems = items.slice(splitIndex);
-  const itemsToCompact = items.slice(0, splitIndex);
+  const { itemsToCompact, recentItems } = splitItemsIntelligently(items);
+  const contextLimit = getModelContextLimit(trackedState.compactionModel);
+  const targetLimit = Math.floor(contextLimit * 0.9);
   let noticeContent = "... conversation history compacted ...";
   if (trackedState.compactionModel && itemsToCompact.length > 0) {
     try {
@@ -2726,15 +2831,38 @@ async function compactConversation(items) {
         modelSettings: getModelSettings(trackedState.compactionModel),
         instructions: "Compact the provided conversation history.\n- Focus on what is NOT completed and needs to be remembered for later.\n- Do NOT include file content or patches, it is available on the filesystem already. \n- Be concise."
       });
-      emitToListeners("SetCompacting", true);
-      const result = await run(
-        agent,
-        itemsToCompact
-      );
-      const summary = result.finalOutput;
-      if (summary && summary.trim().length > 0) {
+      const summaries = [];
+      let remainingItems = itemsToCompact;
+      while (remainingItems.length > 0) {
+        let currentBatch = [];
+        let lastGoodBatch = [];
+        let splitIdx = remainingItems.length;
+        while (splitIdx > 0) {
+          currentBatch = remainingItems.slice(0, splitIdx);
+          if (estimateTokens(currentBatch) <= targetLimit) {
+            lastGoodBatch = currentBatch;
+            break;
+          }
+          splitIdx = Math.floor(splitIdx * 0.8);
+        }
+        if (lastGoodBatch.length === 0) {
+          lastGoodBatch = [remainingItems[0]];
+          splitIdx = 1;
+        }
+        emitToListeners("SetCompacting", true);
+        const result = await run(
+          agent,
+          lastGoodBatch
+        );
+        const summary = result.finalOutput;
+        if (summary && summary.trim().length > 0) {
+          summaries.push(summary.trim());
+        }
+        remainingItems = remainingItems.slice(splitIdx);
+      }
+      if (summaries.length > 0) {
         noticeContent = `Key observations from earlier:
-${summary.trim()}`;
+${summaries.join("\n\n")}`;
       }
     } catch (err) {
       const msg = String(err?.message || err || "");
@@ -2742,6 +2870,9 @@ ${summary.trim()}`;
       if (!isNoTrace) {
         console.warn("Compaction summarization failed:", msg);
       }
+      const totalItems = itemsToCompact.length;
+      const toolCalls = itemsToCompact.filter((it) => it.type === "function_call").length;
+      noticeContent = `... conversation history compacted (${totalItems} items, ${toolCalls} tool calls) ...`;
     } finally {
       emitToListeners("SetCompacting", false);
     }
@@ -2750,41 +2881,38 @@ ${summary.trim()}`;
   return { noticeContent, itemsToAdd };
 }
 
-// utils/sessions/modelContextLimits.ts
-function getModelContextLimit(modelName) {
-  if (!modelName) {
-    return DEFAULT_LIMIT;
-  }
-  const name = modelName.toLowerCase();
-  if (name.startsWith("gpt-4o") || name.startsWith("gpt-5")) {
-    return 2e5;
-  }
-  if (name.startsWith("gpt-4")) {
-    return 128e3;
-  }
-  if (name.startsWith("claude-3.5") || name.startsWith("claude-3")) {
-    return 2e5;
-  }
-  if (name.startsWith("claude-4.6") || name.startsWith("claude-4.5")) {
-    return 1e6;
-  }
-  if (name.startsWith("gemini-1.5") || name.startsWith("gemini-3")) {
-    return 1e6;
+// utils/sessions/removeHarperInternalProviderData.ts
+function removeHarperInternalProviderData(it) {
+  if (!it || typeof it !== "object") {
+    return it;
   }
-  if (name.startsWith("gemini-")) {
-    return 128e3;
+  const out = { ...it };
+  if ("harper" in out) {
+    try {
+      delete out.harper;
+    } catch {
+    }
   }
-  if (name.startsWith("ollama-")) {
-    return 8e3;
+  const pd = out.providerData && typeof out.providerData === "object" ? { ...out.providerData } : void 0;
+  if (pd) {
+    if ("harper" in pd) {
+      try {
+        delete pd.harper;
+      } catch {
+      }
+    }
+    if (Object.keys(pd).length === 0) {
+      try {
+        delete out.providerData;
+      } catch {
+        out.providerData = void 0;
+      }
+    } else {
+      out.providerData = pd;
+    }
   }
-  return DEFAULT_LIMIT;
-}
-function getCompactionTriggerTokens(modelName, fraction = 0.5) {
-  const limit = getModelContextLimit(modelName);
-  const f = Math.min(Math.max(fraction, 0.5), 0.95);
-  return Math.floor(limit * f);
+  return out;
 }
-var DEFAULT_LIMIT = 128e3;
 
 // utils/sessions/MemoryCompactionSession.ts
 var MemoryCompactionSession = class {
@@ -2859,7 +2987,7 @@ var MemoryCompactionSession = class {
   }
   async getItems(limit) {
     const items = await this.underlyingSession.getItems(limit);
-    return items.map((it) => sanitizeItem(it));
+    return items.map((it) => removeHarperInternalProviderData(it));
   }
   /**
    * Returns the provider-stamped timestamp of the latest-added item, or null when unavailable.
@@ -2906,7 +3034,7 @@ var MemoryCompactionSession = class {
    *   forcing flag is provided in args.
    * - If history is trivially small (<= 4 items), it skips compaction.
    * - Otherwise, it keeps the first item, adds a compaction notice (optionally
-   *   summarized by the model), and retains the last 3 recent items.
+   *   summarized by the model), and retains the last ~3 recent items.
    */
   async runCompaction(args) {
     const items = await this.getItems();
@@ -2930,66 +3058,6 @@ var MemoryCompactionSession = class {
     return null;
   }
 };
-function sanitizeItem(it) {
-  if (!it || typeof it !== "object") {
-    return it;
-  }
-  const out = { ...it };
-  if ("harper" in out) {
-    try {
-      delete out.harper;
-    } catch {
-    }
-  }
-  const pd = out.providerData && typeof out.providerData === "object" ? { ...out.providerData } : void 0;
-  if (pd) {
-    if ("harper" in pd) {
-      try {
-        delete pd.harper;
-      } catch {
-      }
-    }
-    if (Object.keys(pd).length === 0) {
-      try {
-        delete out.providerData;
-      } catch {
-        out.providerData = void 0;
-      }
-    } else {
-      out.providerData = pd;
-    }
-  }
-  return out;
-}
-function estimateTokens(items) {
-  let chars = 0;
-  for (const it of items) {
-    if (!it) {
-      continue;
-    }
-    if (Array.isArray(it.content)) {
-      for (const c of it.content) {
-        if (!c) {
-          continue;
-        }
-        if (typeof c.text === "string") {
-          chars += c.text.length;
-        } else if (typeof c.content === "string") {
-          chars += c.content.length;
-        } else if (typeof c === "string") {
-          chars += c.length;
-        }
-      }
-    }
-    if (typeof it.content === "string") {
-      chars += it.content.length;
-    }
-    if (typeof it.text === "string") {
-      chars += it.text.length;
-    }
-  }
-  return Math.ceil(chars / 4);
-}
 
 // utils/sessions/createSession.ts
 function createSession(sessionPath = null) {
@@ -3760,9 +3828,25 @@ var AgentManager = class {
       }
     }
     this.isInitialized = true;
+    if (trackedState.prompt?.trim?.()?.length) {
+      trackedState.autonomous = true;
+      setTimeout(
+        curryEmitToListeners("PushNewMessages", [
+          { type: "prompt", text: trackedState.prompt.trim(), version: 1 }
+        ]),
+        500
+      );
+    } else if (!this.initialMessages?.length) {
+      setTimeout(
+        curryEmitToListeners("PushNewMessages", [
+          { type: "agent", text: "What would you like to create together?", version: 1 }
+        ]),
+        500
+      );
+    }
   }
   enqueueUserInput(text) {
-    if (typeof text === "string" && text.trim().length > 0) {
+    if (text.trim().length > 0) {
       this.queuedUserInputs.push(text);
     }
   }
@@ -5519,6 +5603,21 @@ function DiffApprovalView() {
       result.push({ text: "Delete file: " + payload.path, color: "red" });
       return result;
     }
+    if (payload.type === "overwrite_file") {
+      for (const line of diffLines) {
+        let color;
+        if (line.startsWith("+")) {
+          color = "green";
+        } else if (line.startsWith("-")) {
+          color = "red";
+        }
+        const wrapped = wrapText(line, size.columns - 4);
+        for (const w of wrapped) {
+          result.push({ text: w, color });
+        }
+      }
+      return result;
+    }
     if (payload.type === "code_interpreter" && payload.code) {
       const lines = payload.code.split("\n");
       for (const line of lines) {
@@ -6576,10 +6675,4 @@ function ensureApiKey() {
   }
   await agentManager.initialize();
   bootstrapMain();
-  if (trackedState.prompt?.trim?.()?.length) {
-    trackedState.autonomous = true;
-    emitToListeners("PushNewMessages", [
-      { type: "prompt", text: trackedState.prompt.trim(), version: 1 }
-    ]);
-  }
 })();

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@harperfast/agent",
 	"description": "AI to help you with Harper app management",
-	"version": "0.13.8-ink",
+	"version": "0.14.0",
 	"main": "dist/agent.js",
 	"repository": "github:HarperFast/harper-agent",
 	"bugs": {
@@ -11,7 +11,6 @@
 	"scripts": {
 		"dev": "tsup agent.ts --format esm --clean --dts --watch --external puppeteer",
 		"link": "npm run build && npm link",
-		"attempt": "(cd ~/Downloads && harper-agent -p \"lets make a random-lofi-noise-generator app, please\" --max-turns=8)",
 		"build": "tsup agent.ts --format esm --clean --dts --external puppeteer",
 		"commitlint": "commitlint --edit",
 		"start": "node ./dist/agent.js",