Model-agnostic agent orchestration framework.

An agent is a decision loop that improves over time. The model is optional — it enhances specific decision points, but doesn't enable the system. Rule-based agents handle 90% of real-world situations at zero cost.

The alpha isn't the model. The alpha is the harness.

@harnesskit/core
├── tool-registry       — Zod schemas, permission levels, validated execution
├── permission-engine   — deny → ask → allow cascade, denial tracking, circuit breaker
├── query-loop          — input → context → decide → tool calls → repeat
├── memory              — 4-type taxonomy, side-query selection, auto-dream  (planned)
├── context-manager     — cache-aware compaction pipeline                    (planned)
├── agent-spawner       — fork with shared context, worktree isolation       (planned)
├── hook-system         — lifecycle events, 4 hook types                     (planned)
├── model-router        — tiered selection, retry, fallback                  (planned)
├── drift-detector      — golden image + snapshot + diff                     (planned)
└── bridge              — WebSocket/SSE bidirectional, crash recovery        (planned)

@harnesskit/providers
├── ollama              — Local model adapter (Qwen 7B, etc.)               (planned)
└── together            — Together.ai cloud adapter                         (planned)

Three agent intelligence levels, same architecture:

v0.1.0 — core triad shipped. 22 tests passing.

npm install @harnesskit/core

import { z } from "zod";
import {
  ToolRegistry,
  PermissionEngine,
  QueryLoop,
  type DecisionFn,
} from "@harnesskit/core";

// 1. Register tools
const registry = new ToolRegistry();
registry.register({
  name: "greet",
  description: "Greets a person",
  schema: z.object({ name: z.string() }),
  permissionLevel: "allow",
  execute: async ({ name }) => `Hello, ${name}!`,
});

// 2. Set up permissions
const permissions = new PermissionEngine({
  onAsk: async (req) => true, // auto-approve for demo
});

// 3. Define decision logic (Level 1: pure rules)
const decide: DecisionFn = async (messages) => {
  const lastMsg = messages.at(-1);
  if (lastMsg?.role === "user") {
    return {
      type: "tool_call",
      toolCall: { name: "greet", input: { name: "world" } },
    };
  }
  return { type: "response", response: `Result: ${lastMsg?.content}` };
};

// 4. Run the loop
const loop = new QueryLoop({ registry, permissionEngine: permissions, decide });
const result = await loop.run("Say hello");
console.log(result.messages.at(-1)?.content);
// → "Result: Hello, world!"

See examples/file-organizer/ for a complete Level 1 agent that classifies and organizes files using zero model calls.

DecisionFn — the core abstraction. Not a model interface. A function that takes messages and returns a decision (tool call, response, or done). Level 1 implements this with switch/case. Level 2+ with a model. The framework doesn't care.

Permission cascade — every tool call passes through the permission engine. Tools declare their level (allow/ask/deny). The engine tracks denials and circuit-breaks after repeated rejections.

Gate-Decide-Act-Learn — the meta-pattern applied to every intelligent feature:

• Gate: Should I run? (permission check, drift detection, circuit breaker)
• Decide: How? (rule-based or model-enhanced)
• Act: Execute with validation and error handling
• Learn: Track denials, log results, feed back into gates

pnpm install
pnpm -r build
pnpm -r test       # 22 tests

MIT