@princetheprogrammerbtw/husk 0.1.1 → 0.3.0

package/README.md

@@ -3,13 +3,16 @@
 > The agent harness that gives your LLM memory, hands, and a nervous system.
 
 [![npm version](https://img.shields.io/npm/v/%40princetheprogrammerbtw%2Fhusk.svg)](https://www.npmjs.com/package/@princetheprogrammerbtw/husk)
+[![npm downloads](https://img.shields.io/npm/dm/%40princetheprogrammerbtw%2Fhusk.svg)](https://www.npmjs.com/package/@princetheprogrammerbtw/husk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node](https://img.shields.io/node/v/%40princetheprogrammerbtw%2Fhusk.svg)](https://nodejs.org)
-[![CI](https://github.com/10xdev4u-alt/husk/actions/workflows/ci.yml/badge.svg)](./.github/workflows/ci.yml)
+[![CI](https://github.com/10xdev4u-alt/husk/actions/workflows/ci.yml/badge.svg)](https://github.com/10xdev4u-alt/husk/actions/workflows/ci.yml)
+[![GitHub stars](https://img.shields.io/github/stars/10xdev4u-alt/husk.svg)](https://github.com/10xdev4u-alt/husk/stargazers)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/%40princetheprogrammerbtw%2Fhusk.svg)](https://bundlephobia.com/package/@princetheprogrammerbtw/husk)
 
 ## What is Husk?
 
-Most LLM calls are a brain in a jar — they can think, but can't act, remember, verify their own work, or show you what they did. **Husk** is the body, hands, memory, and nervous system you wrap around any LLM (Claude, GPT, Gemini, local models) to turn it into a real agent.
+Most LLM calls are a **brain in a jar** — they can think, but can't act, remember, verify their own work, or show you what they did. **Husk** is the body, hands, memory, and nervous system you wrap around any LLM (Claude, GPT, Gemini, local models) to turn it into a real agent.
 
 ```ts
 import { Agent, AnthropicProvider, Read, Write, Edit, Bash, Grep, FileStore } from '@princetheprogrammerbtw/husk';
@@ -31,16 +34,27 @@ const result = await agent.run('Review src/core/agent.ts');
 console.log(result.output);
 ```
 
+## Why Husk?
+
+| You're used to… | Husk gives you… |
+|---|---|
+| One-shot LLM calls with no memory | Persistent file-backed or in-memory memory across calls |
+| Hand-rolled tool-calling loops | A small, typed event stream you can subscribe to |
+| Tied to one provider's SDK | Provider-agnostic core; swap Anthropic ↔ OpenAI in one line |
+| Reinventing agent loops in every project | Drop-in `Agent` class with stop conditions, parallel tool execution, and error recovery |
+| No observability into what the model actually did | Typed events for every iteration, tool call, and provider response |
+
 ## Features
 
 - 🧠 **Provider-agnostic** — Anthropic, OpenAI, more coming. Bring your own model.
-- 🛠️ **5 built-in tools** — `Read`, `Write`, `Edit`, `Bash` (with safety denylist), `Grep` (ripgrep with grep fallback)
+- 🛠️ **5 built-in tools** — `Read`, `Write`, `Edit`, `Bash` (with safety denylist for `rm -rf /`, fork bombs, etc.), `Grep` (ripgrep with grep fallback)
 - 💾 **Memory** — `InMemoryStore` for sessions, `FileStore` for persistence
 - 👀 **Observability** — typed event emitter, drop in any logger or tracer
 - 🧭 **Steering** — system prompts, numbered rules, few-shot examples
 - 🤝 **Sub-agents** — compose agents inside agents (see [multi-agent example](./examples/03-multi-agent))
-- 📦 **Batteries included** — 35KB ESM bundle, full TypeScript types
+- 📦 **Batteries included** — 35KB ESM bundle, 26KB d.ts, zero runtime deps except the provider SDKs
 - 🖥️ **CLI** — `husk run "<prompt>"` for one-shot invocations
+- 🔒 **Type-safe** — strict TypeScript, no `any`, full type definitions shipped
 
 ## Install
 
@@ -50,6 +64,8 @@ npm install @princetheprogrammerbtw/husk
 pnpm add @princetheprogrammerbtw/husk
 # or
 bun add @princetheprogrammerbtw/husk
+# or
+yarn add @princetheprogrammerbtw/husk
 ```
 
 You'll also need an API key for the provider you choose:
@@ -61,7 +77,7 @@ export OPENAI_API_KEY=sk-...           # for GPT
 
 ## Quickstart
 
-The smallest possible agent:
+The smallest possible agent — model, prompt, done:
 
 ```ts
 import { Agent, AnthropicProvider } from '@princetheprogrammerbtw/husk';
@@ -74,6 +90,41 @@ const result = await agent.run('What is the capital of France? Answer in one sen
 console.log(result.output); // "Paris"
 ```
 
+A more realistic agent — with tools, memory, and steering:
+
+```ts
+import {
+  Agent, AnthropicProvider, Read, Write, Edit, Bash, Grep,
+  FileStore, InMemoryStore,
+} from '@princetheprogrammerbtw/husk';
+
+const agent = new Agent({
+  model: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
+  tools: [Read, Write, Edit, Bash, Grep],
+  memory: new FileStore({ path: './.husk/memory' }),
+  steering: {
+    systemPrompt: 'You are a careful code reviewer.',
+    rules: [
+      'Read the file in full before commenting.',
+      'Cite specific line numbers for every finding.',
+    ],
+  },
+});
+
+const result = await agent.run('Review src/core/agent.ts');
+```
+
+Swapping to OpenAI is a one-line change:
+
+```ts
+import { OpenAIProvider } from '@princetheprogrammerbtw/husk';
+
+const agent = new Agent({
+  model: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  // ...same config otherwise
+});
+```
+
 ## CLI
 
 ```bash
@@ -84,9 +135,11 @@ husk run "Summarize README.md" --provider openai --model gpt-5
 husk run --help
 ```
 
+The CLI wraps the same `Agent` class — flags map directly to `AgentConfig` fields.
+
 ## Examples
 
-Three worked examples in the `examples/` directory:
+Three worked examples in the [`examples/`](./examples) directory:
 
 - **[01-hello-agent](./examples/01-hello-agent)** — minimal agent, no tools
 - **[02-code-reviewer](./examples/02-code-reviewer)** — full tool set + steering for code review
@@ -96,9 +149,10 @@ Run any example with `bun run examples/0X-name/index.ts`.
 
 ## Documentation
 
-- **[Learning Journal](./LEARNING.md)** — design decisions, trade-offs, and lessons learned
-- **[Changelog](./CHANGELOG.md)** — release history
-- **[Contributing](./CONTRIBUTING.md)** — how to contribute
+- 📓 **[Learning Journal](./LEARNING.md)** — design decisions, trade-offs, and lessons learned while building
+- 📋 **[Changelog](./CHANGELOG.md)** — release history
+- 🤝 **[Contributing](./CONTRIBUTING.md)** — how to contribute
+- 🏗️ **[Architecture](#architecture)** — the module layout, below
 
 ## Architecture
 
@@ -111,15 +165,26 @@ src/
 └── index.ts       # public API surface
 ```
 
-Every piece composes through a typed event stream. The agent loop is ~150 lines. Provider adapters are the only files that know about provider-specific wire formats.
+Every piece composes through a **typed event stream**. The agent loop is ~150 lines. Provider adapters are the only files that know about provider-specific wire formats. Tools are plain objects implementing a 4-field interface — register by passing an array to the Agent.
 
 ## Roadmap
 
 - **v0.1.0** ✅ Core loop, Anthropic + OpenAI, 5 built-in tools, memory, observability, CLI
+- **v0.1.1** ✅ CLI shebang fix, version bump
 - **v0.2.0** Eval runner, OTel export, Ollama adapter
 - **v0.3.0** Vector memory, hosted dashboard
 - **v1.0.0** Stable API, marketplace, enterprise features
 
+## Contributing
+
+PRs welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for the dev setup, scripts, and commit conventions.
+
+The project follows Conventional Commits. Every commit body explains *why*, not what — the diff already shows what.
+
+## Show your support
+
+If Husk saves you time, ⭐️ the [GitHub repo](https://github.com/10xdev4u-alt/husk) — it helps others find the project. Issues, PRs, and feedback all welcome.
+
 ## License
 
-MIT © 2026 princetheprogrammerbtw
+MIT © 2026 [princetheprogrammerbtw](https://github.com/10xdev4u-alt)

package/dist/cli/index.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
+import { existsSync, statSync, promises } from 'fs';
+import { readdir } from 'fs/promises';
+import { resolve, extname, dirname, join } from 'path';
+import { pathToFileURL } from 'url';
 import { promisify, parseArgs } from 'util';
-import { promises } from 'fs';
-import { resolve, dirname, join } from 'path';
 import Anthropic from '@anthropic-ai/sdk';
 import OpenAI from 'openai';
 import { exec } from 'child_process';
@@ -1042,6 +1044,71 @@ function truncateOutput(output, limit) {
 ... (${lines.length - limit} more matches truncated)`;
 }
 
+// src/evals/runner.ts
+async function runSuite(suite, factory, options = {}) {
+  const start = Date.now();
+  const results = [];
+  let passed = 0;
+  for (const c of suite.cases) {
+    options.onCaseStart?.(c.name);
+    const caseResult = await runCase(c, factory);
+    results.push(caseResult);
+    if (caseResult.passed) passed += 1;
+    options.onCaseEnd?.(caseResult);
+    if (options.failFast && !caseResult.passed) {
+      break;
+    }
+  }
+  return {
+    suiteName: suite.name,
+    results,
+    passed,
+    total: suite.cases.length,
+    durationMs: Date.now() - start
+  };
+}
+async function runCase(c, factory) {
+  const start = Date.now();
+  const agent = await factory();
+  let agentResult;
+  try {
+    agentResult = await agent.run(c.input);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const errorAssertionResult = {
+      pass: false,
+      name: "agent.run",
+      message: `agent.run threw: ${message}`
+    };
+    return {
+      caseName: c.name,
+      passed: false,
+      assertionResults: [errorAssertionResult],
+      agentResult: {
+        output: "",
+        messages: [],
+        iterations: 0,
+        usage: { inputTokens: 0, outputTokens: 0 },
+        durationMs: Date.now() - start
+      },
+      durationMs: Date.now() - start
+    };
+  }
+  const assertionResults = [];
+  for (const a of c.assertions) {
+    const r = await a(agentResult);
+    assertionResults.push(r);
+  }
+  const allPassed = assertionResults.every((r) => r.pass);
+  return {
+    caseName: c.name,
+    passed: allPassed,
+    assertionResults,
+    agentResult,
+    durationMs: Date.now() - start
+  };
+}
+
 // src/cli/index.ts
 var TOOL_REGISTRY = { read: Read, write: Write, edit: Edit, bash: Bash, grep: Grep };
 async function main() {
@@ -1054,6 +1121,10 @@ async function main() {
     await runCommand();
     return;
   }
+  if (subcommand === "eval") {
+    await evalCommand();
+    return;
+  }
   if (subcommand === "version" || subcommand === "--version" || subcommand === "-v") {
     console.log(`husk ${VERSION}`);
     return;
@@ -1079,7 +1150,7 @@ async function runCommand() {
     printHelp();
     return;
   }
-  const prompt = values.help === void 0 ? process.argv[3] : void 0;
+  const prompt = process.argv[3];
   if (!prompt) {
     console.error("Error: husk run requires a prompt argument.");
     console.error('Usage: husk run "your prompt here"');
@@ -1111,13 +1182,95 @@ async function runCommand() {
   console.log(result.output);
   process.exit(0);
 }
+async function evalCommand() {
+  const target = process.argv[3];
+  if (!target) {
+    console.error("Error: husk eval requires a path argument.");
+    console.error("Usage: husk eval <file-or-dir>");
+    process.exit(2);
+  }
+  const resolved = resolve(target);
+  if (!existsSync(resolved)) {
+    console.error(`Error: path not found: ${resolved}`);
+    process.exit(2);
+  }
+  const stat = statSync(resolved);
+  const files = [];
+  if (stat.isDirectory()) {
+    const entries = await readdir(resolved, { withFileTypes: true });
+    for (const e of entries) {
+      if (!e.isFile()) continue;
+      const ext = extname(e.name);
+      if (ext === ".ts" || ext === ".js" || ext === ".mjs") {
+        files.push(resolve(resolved, e.name));
+      }
+    }
+  } else {
+    files.push(resolved);
+  }
+  if (files.length === 0) {
+    console.error(`Error: no .ts/.js/.mjs files found in ${resolved}`);
+    process.exit(2);
+  }
+  let totalPassed = 0;
+  let totalCases = 0;
+  let anyFailed = false;
+  for (const file of files) {
+    console.log(`
+=== ${file} ===`);
+    try {
+      const mod = await import(pathToFileURL(file).href);
+      const suites = [];
+      for (const value of Object.values(mod)) {
+        if (value && typeof value === "object" && "name" in value && "cases" in value && Array.isArray(value.cases)) {
+          suites.push(value);
+        }
+      }
+      if (suites.length === 0) {
+        console.error(`  No EvalSuite found in ${file}`);
+        continue;
+      }
+      for (const suite of suites) {
+        const factory = () => Promise.resolve(makeDefaultAgent());
+        const result = await runSuite(suite, factory);
+        totalPassed += result.passed;
+        totalCases += result.total;
+        for (const r of result.results) {
+          const icon = r.passed ? "\u2713" : "\u2717";
+          console.log(`  ${icon} ${r.caseName}`);
+          if (!r.passed) {
+            anyFailed = true;
+            for (const a of r.assertionResults) {
+              console.log(`     \u2717 ${a.name}: ${a.message ?? "failed"}`);
+            }
+          }
+        }
+        console.log(`  ${result.passed}/${result.total} passed in ${result.durationMs}ms`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`  Error loading ${file}: ${message}`);
+      anyFailed = true;
+    }
+  }
+  console.log(`
+=== Total: ${totalPassed}/${totalCases} cases passed ===`);
+  process.exit(anyFailed ? 1 : 0);
+}
+function makeDefaultAgent() {
+  const providerName = process.env.HUSK_PROVIDER ?? "anthropic";
+  const modelId = process.env.HUSK_MODEL ?? "claude-opus-4-6";
+  const provider = providerName === "openai" ? new OpenAIProvider({ model: modelId, apiKey: process.env.OPENAI_API_KEY }) : new AnthropicProvider({ model: modelId, apiKey: process.env.ANTHROPIC_API_KEY });
+  return new Agent({ model: provider });
+}
 function printHelp() {
-  console.log(`husk \u2014 run an agent from the command line
+  console.log(`husk \u2014 run an agent or eval suite from the command line
 
 Usage:
   husk run "<prompt>" [options]
+  husk eval <file-or-dir>
 
-Options:
+Run options:
   --model <id>       Model id (default: claude-opus-4-6)
   --provider <name>  'anthropic' (default) or 'openai'
   --tools <list>     Comma-separated tool names: read,write,edit,bash,grep
@@ -1127,6 +1280,10 @@ Options:
   -h, --help         Show this help
   -v, --version      Show version
 
+Eval options:
+  <file>             A .ts/.js/.mjs file exporting one or more EvalSuite
+  <dir>              A directory; all *.ts/*.js/*.mjs files are loaded
+
 Environment:
   ANTHROPIC_API_KEY   Required for Anthropic provider
   OPENAI_API_KEY      Required for OpenAI provider
@@ -1137,9 +1294,10 @@ Examples:
   husk run "What is the capital of France?"
   husk run "Refactor src/foo.ts" --tools read,edit,write
   husk run "Summarize README.md" --provider openai --model gpt-5
+  husk eval ./evals/geography.ts
 `);
 }
-var VERSION = "0.1.0";
+var VERSION = "0.3.0-dev.0";
 await main();
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map