@harperfast/agent 0.10.6

package/README.md

@@ -0,0 +1,172 @@
+![](assets/logo.png) ![npx -y harper-agent](./README.svg)
+
+AI to help you with Harper app creation and management.
+
+## Prerequisites
+
+- Node.js (v24 or higher recommended)
+- An API key for your preferred AI model:
+  - **OpenAI**: https://platform.openai.com/api-keys
+  - **Anthropic**: https://console.anthropic.com/settings/keys
+  - **Google Gemini**: https://aistudio.google.com/app/apikey
+  - **Ollama**: (No API key required, see [Ollama Support](#ollama-support-local-models) below)
+
+## 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.
+
+If you prefer to set it 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.)
+
+Now install harper-agent:
+
+```bash
+npm install -g @harperfast/agent
+```
+
+Or run it with npx:
+
+```
+npx -y @harperfast/agent
+```
+
+You're ready to go!
+
+```bash
+> harper-agent
+
+Working directory: /Users/dawson/Code/softwork-beats
+Harper app detected: Yes
+Press Ctrl+C or hit enter twice to exit.
+
+Harper: What do you want to do together today?
+
+>
+```
+
+## Model Selection
+
+By default, `harper-agent` uses OpenAI. You can switch to other models using the `--model` (or `-m`) flag:
+
+```bash
+# Use Claude 3.5 Sonnet
+harper-agent --model claude-3-5-sonnet-20241022
+
+# Use Gemini 1.5 Pro
+harper-agent --model gemini-1.5-pro
+
+# Use a specific OpenAI model
+harper-agent --model gpt-4o-mini
+```
+
+You can also set the default model via the `HARPER_AGENT_MODEL` environment variable.
+
+### Compaction Model
+
+By default, `harper-agent` uses `gpt-4o-mini` for session memory compaction. You can switch this to another model using the `--compaction-model` (or `-c`) flag:
+
+```bash
+# Use a different compaction model
+harper-agent --compaction-model claude-3-haiku-20240307
+```
+
+You can also set the default compaction model via the `HARPER_AGENT_COMPACTION_MODEL` environment variable.
+
+### 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:
+
+```bash
+# Persist session to a file
+harper-agent --session ./my-session.db
+```
+
+This will save all conversation history to the specified file. If the file already exists, `harper-agent` will resume the session from where you left off.
+
+You can also set the default session path via the `HARPER_AGENT_SESSION` environment variable.
+
+### Service Tier (OpenAI Only)
+
+By default, `harper-agent` uses the `auto` service tier. You can force the `flex` tier to be used with the `--flex-tier` flag:
+
+```bash
+# Use flex service tier
+harper-agent --flex-tier
+```
+
+Forcing the `flex` tier can help reduce costs, although it may result in more frequent errors during periods of high system load.
+
+You can also set this via the `HARPER_AGENT_FLEX_TIER=true` environment variable.
+
+### Ollama Support (Local Models)
+
+To use local models with [Ollama](https://ollama.com/), use the `ollama-` prefix:
+
+```bash
+# Use Llama 3 via Ollama
+harper-agent --model ollama-llama3
+```
+
+If your Ollama instance is running on a custom URL, you can set the `OLLAMA_BASE_URL` environment variable:
+
+```bash
+export OLLAMA_BASE_URL=http://localhost:11434
+harper-agent --model ollama-llama3
+```
+
+### OpenAI API Key Permissions
+
+If you are using a restricted API key, ensure the following permissions are enabled:
+
+- **Models**: `Write` access for `gpt-5.2` (the main model) and `gpt-4o-mini` (the memory summarizer)
+- **Model capabilities**: `Write` (to allow tool calling and completions).
+
+No other permissions (like Assistants, Threads, or Files) are required as `harper-agent` runs its tools locally.
+
+# Contributing to Our Development
+
+If you want to help us advance the source code that powers harper-agent, take a look at the steps below!
+
+## Local Development
+
+### Setup
+
+1. Clone the repository.
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Create a `.env` file in the root directory and add your API key:
+   ```env
+   OPENAI_API_KEY=your_api_key_here
+   # OR ANTHROPIC_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY
+   HARPER_AGENT_SKIP_UPDATE=true
+   ```
+
+### Running the Agent
+
+To use the `harper-agent` command globally from your local source so you can use it on other projects:
+
+```bash
+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/README.svg

@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  viewBox="0 0 1280 200"
+  width="640"
+  height="200"
+  role="img"
+  aria-label="npx -y harper-agent"
+>
+  <defs>
+    <!-- Brand-ish gradient for the wordmark -->
+    <linearGradient id="harperGrad" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#45b581" />
+      <stop offset="55%" stop-color="#2fe7a4" />
+      <stop offset="100%" stop-color="#45b581" />
+    </linearGradient>
+
+    <!-- Subtle shadow -->
+    <filter id="softShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="2" stdDeviation="3" flood-opacity="0.18" />
+    </filter>
+
+    <!-- Palette classes -->
+    <style>
+    .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; }
+    .sans { font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, "Apple Color Emoji","Segoe UI Emoji"; }
+    </style>
+  </defs>
+
+  <!-- Wordmark + tagline -->
+  <g transform="translate(50 58)">
+    <text
+      class="sans"
+      x="0"
+      y="62"
+      font-size="200"
+      font-weight="800"
+      letter-spacing="-1.5"
+      fill="url(#harperGrad)"
+    >harper agent</text>
+
+    <!-- little “terminal” capsule -->
+    <g transform="translate(0 120)">
+      <rect
+        x="0"
+        y="0"
+        rx="14"
+        ry="14"
+        width="800"
+        height="56"
+        fill="#0b1020"
+        opacity="0.92"
+      />
+      <circle cx="22" cy="28" r="6" fill="#ff5f56" />
+      <circle cx="42" cy="28" r="6" fill="#ffbd2e" />
+      <circle cx="62" cy="28" r="6" fill="#27c93f" />
+
+      <text
+        class="mono"
+        x="90"
+        y="37"
+        font-size="22"
+        fill="#e6f7ff"
+        opacity="0.96"
+      >$ npx -y harper-agent</text>
+
+      <!-- blinking cursor -->
+      <rect x="380" y="17" width="12" height="24" fill="#e6f7ff" opacity="0.55">
+        <animate
+          attributeName="opacity"
+          values="0.1;0.8;0.1"
+          dur="1.1s"
+          repeatCount="indefinite"
+        />
+      </rect>
+    </g>
+  </g>
+</svg>

package/dist/agent.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node