harnessly 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vomesh Atukuri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# Harnessly
+
+A harnessed AI coding agent CLI with guardrails, approval flow, observability, and error recovery. Harnessly can read files, write files, run commands, and search code — all driven by natural language, with safety guardrails wrapping every action.
+
+## Features
+
+### Agent
+- **Multi-provider support** — OpenAI, Azure, Anthropic, or any custom OpenAI-compatible endpoint
+- **Streaming responses** — Token-by-token output in real time
+- **Conversation memory** — Maintains context across turns with auto-summarization
+- **Up to 8 tool calls per turn** — Chained reasoning with tool feedback
+
+### Harness (Safety & Observability)
+- **Guardrails**
+  - Command safety — 12 dangerous command patterns blocked (`rm -rf /`, `format`, `mkfs`, `dd`, `shutdown`, etc.)
+  - Directory scoping — All file operations restricted to working directory
+  - Path containment — Prevents path traversal (`../` attacks)
+- **Approval flow** — Destructive tools (`writeFile`, `runCommand`) prompt for user approval before execution. Non-destructive tools auto-approve.
+- **Observability**
+  - Step logging — Every tool call logged to `~/.harnessly/logs/` with timestamp, input, result, and duration
+  - Token tracking — Cumulative session token usage (input, output, total)
+- **Error recovery** — Automatic retry with exponential backoff (1s, 2s, 4s) on transient API failures (timeout, rate limit, ECONNRESET, 429, 503)
+
+## Installation
+
+```bash
+npm install -g harnessly
+```
+
+Or run without installing:
+
+```bash
+npx harnessly
+```
+
+## Usage
+
+```bash
+harnessly
+```
+
+### First Run Setup
+
+On first run, Harnessly will prompt you to:
+1. Select your AI provider (OpenAI, Azure, Anthropic, or Custom)
+2. Enter your API key (masked input)
+3. Choose a model (or use the default)
+
+Your config is saved at `~/.harnessly/config.json` so you only need to set it up once.
+
+### Environment Variables (Alternative to Setup)
+
+Skip the setup wizard by setting environment variables:
+
+```bash
+# OpenAI
+export OPENAI_API_KEY=sk-...
+harnessly
+
+# Anthropic
+export ANTHROPIC_API_KEY=sk-ant-...
+harnessly
+
+# Azure
+export AZURE_API_KEY=...
+export AZURE_RESOURCE_NAME=my-resource
+harnessly
+```
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/tokens` | Display session token usage |
+| `/logs` | Show log file path |
+| `/clear` | Clear conversation history and reset tokens |
+| `/config` | Switch provider or model |
+| `/history` | Show recent prompt history |
+| `/exit` | Exit Harnessly |
+
+## Examples
+
+```
+>>> read the package.json and tell me what dependencies I have
+
+>>> create a new file called utils.ts with a debounce function
+  ⚠ writeFile(utils.ts)
+  Allow? [y/N] y
+
+>>> run the tests and fix any failures
+  ⚠ runCommand(npm test)
+  Allow? [y/N] y
+
+>>> search for all TODO comments in the project
+```
+
+## Available Tools
+
+| Tool | Description | Approval Required |
+|------|-------------|-------------------|
+| `readFile` | Read the contents of any file | No |
+| `writeFile` | Create or overwrite a file | Yes |
+| `listDirectory` | List files and folders in a directory | No |
+| `runCommand` | Execute any shell command (30s timeout) | Yes |
+| `searchFiles` | Search for text patterns across files | No |
+
+## How It Works
+
+```
+┌─────────────────────────────────────────┐
+│           HARNESS LAYER                  │
+│  ┌───────────────────────────────────┐  │
+│  │         AGENT (LLM)                │  │
+│  │  ┌─────┐  ┌──────┐  ┌──────────┐  │  │
+│  │  │Tools│  │Memory│  │Reasoning │  │  │
+│  │  └─────┘  └──────┘  └──────────┘  │  │
+│  └───────────────────────────────────┘  │
+│                                          │
+│  Guardrails   ✅ Observability          │
+│  Approval     ✅ Token Tracking         │
+│  Retry         ✅ Step Logging          │
+└─────────────────────────────────────────┘
+```
+
+1. You type a message in the terminal
+2. Harnessly sends it to your chosen AI model along with tool definitions
+3. The AI model decides which tools to use and calls them
+4. **Harness layer checks**: Is this tool destructive? → Prompt user. Is this command dangerous? → Block. Is this path outside working dir? → Deny.
+5. Approved tool calls execute and results go back to the model
+6. The model can chain up to 8 tool calls per turn
+7. Final response is displayed with token usage
+
+## Configuration
+
+Config is stored at `~/.harnessly/config.json`:
+
+```json
+{
+  "provider": "OpenAI",
+  "apiKey": "sk-...",
+  "model": "gpt-4o"
+}
+```
+
+To reconfigure, delete the config file and restart Harnessly, or use `/config` to switch providers.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build
+npm run build
+
+# Start from build
+npm start
+```
+
+## Tech Stack
+
+- **AI SDK v7** (Vercel) — model integration, tool execution, and `toolApproval`
+- **Zod v4** — tool input schema validation
+- **clack/prompts** — terminal UI components
+- **cac** — CLI framework
+- **chalk** — terminal styling
+- **ora** — loading spinners
+
+## License
+
+MIT
+
+## Author
+
+Vomesh ([@VomeshAtukuri](https://github.com/VomeshAtukuri))

package/build/agent.d.ts

@@ -0,0 +1,26 @@
+import { type ModelMessage, type LanguageModel } from 'ai';
+import type { ProviderConfig } from './ui';
+export type ApprovalCallback = (toolName: string, args: any) => Promise<boolean>;
+interface AskArgs {
+    userMessage: string;
+    onToolCall?: (toolName: string, args: unknown) => void;
+    signal?: AbortSignal;
+}
+interface AgentOptions {
+    approval?: ApprovalCallback;
+}
+export declare function createModel(config: ProviderConfig): LanguageModel;
+export declare class Agent {
+    private messages;
+    private model;
+    private tools;
+    private approval?;
+    constructor(model: LanguageModel, options?: AgentOptions);
+    getHistory(): readonly ModelMessage[];
+    private summarize;
+    ask({ userMessage, onToolCall, signal }: AskArgs): Promise<{
+        textStream: import("ai").AsyncIterableStream<string>;
+        done: () => Promise<void>;
+    }>;
+}
+export {};

package/build/agent.js

@@ -0,0 +1,163 @@
+import { createAzure } from '@ai-sdk/azure';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { generateText, streamText, stepCountIs, } from 'ai';
+import { createTools } from './tools';
+import { trackTokens, withRetry } from './harness';
+function getEnvKeyName(provider) {
+    switch (provider) {
+        case 'OpenAI': return 'OPENAI_API_KEY';
+        case 'Anthropic': return 'ANTHROPIC_API_KEY';
+        case 'Azure': return 'AZURE_API_KEY';
+        case 'Custom': return 'CUSTOM_API_KEY';
+        default: return `${provider.toUpperCase()}_API_KEY`;
+    }
+}
+function getEnvKey(provider) {
+    return process.env[getEnvKeyName(provider)];
+}
+const MAX_MESSAGES = 25;
+// Keep the last N *complete* turns when summarizing, never a raw slice —
+// see trimToCompleteTurns() for why a raw slice is unsafe.
+const KEEP_RECENT_MESSAGES = 4;
+const SYSTEM_PROMPT = `You are a powerful coding agent running in the user's terminal.
+You have access to tools that let you read files, write files, run shell commands, list directories, and search code.
+
+Working directory: ${process.cwd()}
+
+Guidelines:
+- When asked to do something, USE your tools to accomplish it. Don't just suggest code — actually make changes.
+- Read files before modifying them to understand the current state.
+- After making changes, verify them if possible (e.g. run tests, check output).
+- Be concise in your responses. Show what you did, not lengthy explanations.
+- If a task requires multiple steps, do them all in one turn.`;
+export function createModel(config) {
+    const { provider, model, resourceName, baseURL } = config;
+    const apiKey = config.apiKey || getEnvKey(provider);
+    if (!apiKey) {
+        throw new Error(`No API key found. Set ${getEnvKeyName(provider)} env var or run setup.`);
+    }
+    switch (provider) {
+        case 'OpenAI': {
+            const openai = createOpenAI({ apiKey });
+            return openai.chat(model || 'gpt-4o');
+        }
+        case 'Azure': {
+            const azure = createAzure({ resourceName: resourceName, apiKey });
+            return azure.chat(model || 'gpt-4o');
+        }
+        case 'Anthropic': {
+            // Anthropic's API isn't OpenAI-compatible — use the dedicated provider,
+            // not createOpenAI (which would call OpenAI's endpoint with the wrong key/shape).
+            const anthropic = createAnthropic({ apiKey });
+            return anthropic(model || 'claude-sonnet-4-5');
+        }
+        case 'Custom': {
+            const custom = createOpenAI({ apiKey, baseURL });
+            return custom.chat(model || 'custom-model');
+        }
+        default:
+            throw new Error(`Unknown provider: ${provider}`);
+    }
+}
+/**
+ * A tool-result message must always immediately follow the assistant message
+ * that requested it. Slicing `messages.slice(-N)` blindly can land in the
+ * middle of such a pair and produce an invalid history. This walks backward
+ * from the end and only stops at a safe boundary (a user message, or an
+ * assistant message with no pending tool calls).
+ */
+function trimToCompleteTurns(history, keep) {
+    if (history.length <= keep)
+        return history.slice();
+    let start = history.length - keep;
+    while (start > 0) {
+        const msg = history[start];
+        const prev = history[start - 1];
+        const prevIsToolCall = prev.role === 'assistant' &&
+            Array.isArray(prev.content) &&
+            prev.content.some((p) => p.type === 'tool-call');
+        const isDanglingToolResult = msg.role === 'tool' || prevIsToolCall;
+        if (!isDanglingToolResult)
+            break;
+        start--;
+    }
+    return history.slice(start);
+}
+export class Agent {
+    messages = [];
+    model;
+    tools;
+    approval;
+    constructor(model, options) {
+        this.model = model;
+        this.tools = createTools();
+        this.approval = options?.approval;
+    }
+    getHistory() {
+        return this.messages;
+    }
+    async summarize() {
+        const transcript = this.messages
+            .map((m) => `[${m.role}]: ${typeof m.content === 'string' ? m.content : JSON.stringify(m.content)}`)
+            .join('\n');
+        const { text: summary } = await generateText({
+            model: this.model,
+            system: 'You are a summarizer. Condense the following conversation into a brief summary. ' +
+                'Include: what the user asked, what tools were used, what files were changed, and the current state. ' +
+                'Be concise but preserve all important context.',
+            prompt: transcript,
+        });
+        const recent = trimToCompleteTurns(this.messages, KEEP_RECENT_MESSAGES);
+        this.messages = [
+            { role: 'user', content: `[Previous conversation summary]: ${summary}` },
+            ...recent,
+        ];
+    }
+    async ask({ userMessage, onToolCall, signal }) {
+        this.messages.push({ role: 'user', content: userMessage });
+        try {
+            const result = await withRetry(() => Promise.resolve(streamText({
+                model: this.model,
+                system: SYSTEM_PROMPT,
+                messages: this.messages,
+                tools: this.tools,
+                stopWhen: stepCountIs(8),
+                abortSignal: signal,
+                toolApproval: this.approval ? async ({ toolCall }) => {
+                    const approved = await this.approval(toolCall.toolName, toolCall.input);
+                    return approved ? 'approved' : 'denied';
+                } : undefined,
+                onStepFinish: ({ toolCalls }) => {
+                    for (const tc of toolCalls ?? []) {
+                        onToolCall?.(tc.toolName, tc.input);
+                    }
+                },
+            })));
+            return {
+                textStream: result.textStream,
+                done: async () => {
+                    try {
+                        const response = await result.response;
+                        this.messages.push(...response.messages);
+                        // Track token usage
+                        const usage = await result.totalUsage;
+                        trackTokens(usage);
+                        if (this.messages.length > MAX_MESSAGES) {
+                            await this.summarize();
+                        }
+                    }
+                    catch (err) {
+                        this.messages.pop();
+                        throw err;
+                    }
+                },
+            };
+        }
+        catch (err) {
+            // Roll back the optimistic push so a failed call doesn't corrupt history.
+            this.messages.pop();
+            throw err;
+        }
+    }
+}

package/build/config.d.ts

@@ -0,0 +1,8 @@
+import type { ProviderConfig } from './ui';
+export declare function getConfig(): ProviderConfig | null;
+export declare function saveConfig(config: ProviderConfig): void;
+export declare function deleteConfig(): void;
+export declare function getHistory(): string[];
+export declare function appendHistory(entry: string): void;
+export declare function getConfigDir(): string;
+export declare function clearHistory(): void;

package/build/config.js

@@ -0,0 +1,58 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+const CONFIG_DIR = path.join(os.homedir(), '.harnessly');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const HISTORY_PATH = path.join(CONFIG_DIR, 'history.json');
+function ensureDir() {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+}
+// ─── Config ──────────────────────────────────────────────
+export function getConfig() {
+    try {
+        if (fs.existsSync(CONFIG_PATH)) {
+            return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+        }
+    }
+    catch {
+        // corrupted config — treat as missing
+    }
+    return null;
+}
+export function saveConfig(config) {
+    ensureDir();
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+export function deleteConfig() {
+    try {
+        fs.unlinkSync(CONFIG_PATH);
+    }
+    catch { }
+}
+// ─── Session History (optional persistence) ──────────────
+export function getHistory() {
+    try {
+        if (fs.existsSync(HISTORY_PATH)) {
+            return JSON.parse(fs.readFileSync(HISTORY_PATH, 'utf-8'));
+        }
+    }
+    catch { }
+    return [];
+}
+export function appendHistory(entry) {
+    ensureDir();
+    const history = getHistory();
+    history.push(entry);
+    // keep last 100 entries
+    const trimmed = history.slice(-100);
+    fs.writeFileSync(HISTORY_PATH, JSON.stringify(trimmed, null, 2));
+}
+export function getConfigDir() {
+    return CONFIG_DIR;
+}
+export function clearHistory() {
+    try {
+        fs.unlinkSync(HISTORY_PATH);
+    }
+    catch { }
+}

package/build/harness.d.ts

@@ -0,0 +1,31 @@
+export declare function checkPath(filePath: string): {
+    allowed: boolean;
+    reason?: string;
+};
+export declare function checkCommand(command: string): {
+    allowed: boolean;
+    reason?: string;
+};
+interface LogEntry {
+    timestamp: string;
+    tool: string;
+    input: any;
+    result: string;
+    durationMs: number;
+}
+export declare function logToolCall(entry: LogEntry): void;
+export declare function getLogPath(): string;
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+export declare function trackTokens(usage: {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}): void;
+export declare function getSessionTokens(): TokenUsage;
+export declare function resetSessionTokens(): void;
+export declare function withRetry<T>(fn: () => Promise<T>, maxRetries?: number, baseDelayMs?: number): Promise<T>;
+export {};

package/build/harness.js

@@ -0,0 +1,94 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+// ─── Directory Scoping ───────────────────────────────────
+const WORKING_DIR = process.cwd();
+function isWithinWorkingDir(targetPath) {
+    const resolved = path.resolve(targetPath);
+    const relative = path.relative(WORKING_DIR, resolved);
+    return !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+export function checkPath(filePath) {
+    if (!isWithinWorkingDir(filePath)) {
+        return {
+            allowed: false,
+            reason: `Path "${filePath}" is outside the working directory (${WORKING_DIR}). Access denied.`,
+        };
+    }
+    return { allowed: true };
+}
+// ─── Command Safety ───────────────────────────────────────
+const DANGEROUS_PATTERNS = [
+    { pattern: /\brm\s+-rf\s+\//i, reason: 'Recursive delete from root' },
+    { pattern: /\brm\s+-rf\s+~/i, reason: 'Recursive delete of home directory' },
+    { pattern: /\brm\s+-rf\s+\.\./i, reason: 'Recursive delete of parent directory' },
+    { pattern: /\bdel\s+\/s/i, reason: 'Windows recursive delete' },
+    { pattern: /\bformat\s+[a-z]:/i, reason: 'Disk format command' },
+    { pattern: /\bmkfs/i, reason: 'Filesystem format command' },
+    { pattern: /\bdd\s+if=/i, reason: 'Raw disk write command' },
+    { pattern: /\b:()\{.*\|.*&\};:/i, reason: 'Fork bomb' },
+    { pattern: /\bshutdown\b/i, reason: 'System shutdown command' },
+    { pattern: /\breboot\b/i, reason: 'System reboot command' },
+    { pattern: /\btaskkill\s+\/f/i, reason: 'Force kill all processes' },
+    { pattern: /\breg\s+delete/i, reason: 'Registry deletion' },
+];
+export function checkCommand(command) {
+    for (const { pattern, reason } of DANGEROUS_PATTERNS) {
+        if (pattern.test(command)) {
+            return { allowed: false, reason: `Blocked: ${reason}` };
+        }
+    }
+    return { allowed: true };
+}
+// ─── Step Logging (Observability) ────────────────────────
+const LOG_DIR = path.join(os.homedir(), '.harnessly', 'logs');
+const LOG_PATH = path.join(LOG_DIR, `harnessly-${new Date().toISOString().slice(0, 10)}.log`);
+function ensureLogDir() {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+}
+export function logToolCall(entry) {
+    ensureLogDir();
+    const line = `[${entry.timestamp}] ${entry.tool} (${entry.durationMs}ms)\n  input: ${JSON.stringify(entry.input).slice(0, 200)}\n  result: ${entry.result.slice(0, 200)}\n\n`;
+    fs.appendFileSync(LOG_PATH, line);
+}
+export function getLogPath() {
+    return LOG_PATH;
+}
+let sessionTokens = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+export function trackTokens(usage) {
+    sessionTokens.inputTokens += usage.inputTokens ?? 0;
+    sessionTokens.outputTokens += usage.outputTokens ?? 0;
+    sessionTokens.totalTokens += usage.totalTokens ?? 0;
+}
+export function getSessionTokens() {
+    return { ...sessionTokens };
+}
+export function resetSessionTokens() {
+    sessionTokens = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+}
+// ─── Retry Logic (Error Recovery) ─────────────────────────
+export async function withRetry(fn, maxRetries = 3, baseDelayMs = 1000) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt === maxRetries)
+                break;
+            // Only retry on transient errors (timeout, rate limit, network)
+            const isTransient = err.message?.includes('timeout') ||
+                err.message?.includes('rate limit') ||
+                err.message?.includes('ECONNRESET') ||
+                err.message?.includes('socket hang up') ||
+                err.statusCode === 429 ||
+                err.statusCode === 503;
+            if (!isTransient)
+                break;
+            const delay = baseDelayMs * Math.pow(2, attempt);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};