Simple Agent Harness

A tiny, extension-first AI harness inspired by the same design instinct as pi: keep the core small, make the seams obvious, and add capability through tools.

What is here

src/agent.ts — the agent loop
src/model/openai.ts — the OpenAI Responses API adapter
src/events.ts — typed lifecycle events
src/commands.ts — slash-command registry
src/tools/registry.ts — tool registration and lookup
src/tools/builtins.ts — two read-only built-in tools
src/extensions.ts — project-local extension loader
src/logger.ts — ordered lifecycle logging
extensions/example.ts — an example extension that registers echo

Quick start

npm install
export OPENAI_API_KEY="..."
npm run dev

That starts a simple terminal chat loop:

Simple Agent Harness
Type a message, "/help" for commands, or "/exit" to quit.
you>

You can also keep using one-shot mode when scripting:

npm run dev -- "List the files in this project."

Optional:

export SYSTEM_PROMPT="You are a terse coding agent."

Design

The core is deliberately narrow:

the model adapter asks the model what to do next
the agent loop executes requested tools
tool outputs are fed back into the next turn
extensions add tools, commands, event listeners, and prompt fragments without changing the loop

The harness also emits ordered trace logs to stderr so you can see the control flow:

[01] tool.registered {"tool":"list_files"}
[02] tool.registered {"tool":"read_file"}
[03] extension.loading {"extension":"example.ts"}
[04] tool.registered {"tool":"echo"}
[05] extension.loaded {"extension":"example.ts"}
[06] agent.started {"maxTurns":8}
[07] agent.turn.started {"turn":1}
[08] model.request {"model":"gpt-5","messages":1,"tools":["list_files","read_file","echo"]}

Commands

Commands run before the model loop. They are a lightweight control plane for things that do not need inference:

npm run dev -- "/help"
npm run dev -- "/tools"

The core provides:

/help — show available commands
/reset — clear the current conversation history
/exit — leave the interactive session

Extensions can register their own commands.

System prompt

Yes, there is now an explicit system prompt. By default it is:

You are a helpful agent. Use tools when they are useful, and answer clearly.

Override it with the SYSTEM_PROMPT environment variable. Extensions can also append fragments to the final system prompt with addSystemPrompt(...).

That gives us a clean path to later add:

more providers
write/edit/bash tools
permissions
session persistence
lifecycle hooks
streaming or a TUI

Add a tool with an extension

Create a file in extensions/ that exports a default function:

import type { Extension } from "../src/types.js";

const myExtension: Extension = async ({
  registerTool,
  registerCommand,
  on,
  addSystemPrompt
}) => {
  await registerTool({
    name: "greet",
    description: "Greet a person by name.",
    parameters: {
      type: "object",
      properties: { name: { type: "string" } },
      required: ["name"],
      additionalProperties: false
    },
    execute(input: { name: string }) {
      return `Hello, ${input.name}!`;
    }
  });

  await registerCommand({
    name: "greet",
    description: "Greet someone without calling the model.",
    execute(args) {
      return `Hello, ${args || "friend"}!`;
    }
  });

  addSystemPrompt("Prefer the greet tool when a greeting is explicitly requested.");

  on("tool.call.completed", ({ tool }) => {
    if (tool === "greet") {
      // Observe tool usage, persist metrics, etc.
    }
  });
};

export default myExtension;

Then use either path:

npm run dev -- "Use the greet tool for Ada."
npm run dev -- "/greet Ada"

Intentional omissions

This first version does not include file writes, shell execution, approval gates, or persistent sessions. Those are useful, but adding them after the core shape is visible keeps the harness easier to reason about.

4.0 KiB Raw Blame History