Hamr SDK API

Hamr can be consumed as a library (SDK) in your own TypeScript or Bun applications. This allows you to build custom agents, UI clients, or long-running daemons around the core agent logic.

Installation

bun add hamr

Ensure your project uses TypeScript and supports ES modules or CommonJS appropriate for your target environment.

The Public Surface

The stable public API is exported from the root hamr package and explicit subpaths. Internal CLI and parsing details are intentionally not exported.

Primary entry points

• hamr: Session, HandoffManager, HolographicMemory, RecoveryManager, ActionExecutor, SkillLoader.
• hamr/llm: LLM types (ChatResponse, client configurations).
• hamr/events: EventBus and strongly-typed engine events.
• hamr/tools: Tool definitions and registry interfaces.
• hamr/memory: Memory indexing details.
• hamr/session: Conversation shapes and agent constraints.

Basic Usage

The core orchestration class is the Session. A session wires together the conversation, LLM client, tool registry, and execution environment.

1. Instantiate the LLM Client

Using hamr/llm, create a client.

import { createAgentClient } from 'hamr/llm';

const client = createAgentClient({
  provider: 'openai',
  config: { apiKey: process.env.OPENAI_API_KEY },
  model: 'gpt-4o',
});

2. Configure and Run a Session

You provide the client, repo root, and initial configuration to Session.

import { Session } from 'hamr';

async function main() {
  const session = new Session({
    repoRoot: process.cwd(),
    client,
    mode: 'plan', // Or 'patch'
    bashEnabled: true,
  });

  // Start a turn
  const result = await session.startTurnWithRecovery('Find all TODO comments in src/ and list them.');

  console.log('Final Answer:', result.finalAnswer);
}

main().catch(console.error);

Adding Custom Tools

The ActionExecutor handles executing tools generated by the model. You can extend the ToolRegistry and add your own execution handlers to support application-specific capabilities.

import { ToolRegistry } from 'hamr/tools';
import { ActionExecutor } from 'hamr';

// Assume you created a custom registry and a list of tool schema definitions
const registry = new ToolRegistry();
registry.registerTool({
  name: 'say_hello',
  description: 'Say hello to someone.',
  inputSchema: { type: 'object', properties: { name: { type: 'string' } } },
});

const executor = new ActionExecutor({
  repoRoot: process.cwd(),
  registry,
  handlers: {
    say_hello: async (args: any) => ({
      success: true,
      toolResult: `Hello, ${args.name}!`,
    }),
  },
});

Consuming Events

The EventBus allows external apps to observe what the session is checking out.

import { Session } from 'hamr';
import { EventBus } from 'hamr/events';

// ... Session setup ...

session.eventBus.on('tool_execution_start', (event) => {
  console.log(`Tool starting: ${event.toolName}`);
});

(Note: In earlier versions of Session, onActivity, onEvent, and onBudget handlers could be passed to the constructor. EventBus offers deeper observability.)