npm package: @sschepis/tinyagent
Description: A minimal, pluggable autonomous agent library with built-in VFS, memory, and AST mutation
Latest version: 0.1.0

# tinyagent

A minimal, pluggable autonomous agent library for TypeScript/JavaScript. Ships with a built-in virtual filesystem, dual memory system, AST mutation engine, lifecycle hooks, and a reflection-driven agent loop. Every component is replaceable.

## Install

```bash
npm install tinyagent
```

## Quick Start

```typescript
import { TinyAgent, type LLMProvider } from 'tinyagent';

// 1. Implement the LLMProvider interface for your model
const provider: LLMProvider = {
  async generate(history, systemPrompt) {
    const res = await fetch('https://api.example.com/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ messages: history, system: systemPrompt }),
    });
    return res.json(); // must return { reflection, reasoning, commands }
  },
};

// 2. Create an agent
const agent = new TinyAgent({ provider });

// 3. Run it
const history = await agent.run('Create a file called hello.txt with "Hello World" inside it.');
console.log(history);
```

## Execution Modes

```typescript
// Run to completion
const history = await agent.run('do something');

// Step through one turn at a time
const turn1 = await agent.step('my task');
const turn2 = await agent.step(); // continues same task

// Stream turns as an async iterator
for await (const turn of agent.stream('my task')) {
  console.log(`Turn ${turn.turn}: ${turn.agent.reasoning}`);
  if (turn.finished) break;
}
```

## Key Concepts

- **LLMProvider** — Bring your own model. Implement one method: `generate(history, systemPrompt) → { reflection, reasoning, commands }`.
- **Commands** — CLI-style tools the agent can invoke (`ls`, `read`, `write`, `rm`, `mv`, `append`, `mutate`, etc.). Register your own or replace the built-ins entirely. `eval`/`spawn` are opt-in via `createUnsafeCommands()`.
- **VFS** — An in-memory virtual filesystem with configurable root path.
- **Dual Memory** — Voluntary (agent-controlled) and involuntary (automatic context capture) memory stores with optional semantic search, configurable capacity, and similarity threshold.
- **Hooks** — Lifecycle hooks (`beforeLLMCall`, `afterLLMCall`, `beforeCommand`, `afterCommand`, `onError`, `onTurnStart`, `onTurnEnd`) for intercepting and modifying agent behavior.
- **Symbolic Continuity** — On task completion, the agent emits context-sensitive symbols encoding its internal state. A configurable-depth stack of these states is injected into the next run's prompt, giving the agent a warm cognitive start.
- **Prompts** — Default persona and system prompt are exported and fully customizable.
- **Error Classes** — Typed errors (`AgentRunningError`, `MaxTurnsExceededError`, `ProviderError`, `CommandError`) for structured error handling.

## Documentation

- [Configuration](docs/configuration.md) — All config options and runtime API
- [Commands](docs/commands.md) — Built-in commands and writing custom ones
- [LLM Providers](docs/providers.md) — Implementing providers for different models
- [Memory](docs/memory.md) — Memory system and semantic embeddings
- [VFS](docs/vfs.md) — Virtual filesystem usage
- [AST Pipeline](docs/pipeline.md) — Code mutation engine
- [Symbolic Continuity](docs/continuity.md) — Persistent internal state across runs
- [Hooks](docs/hooks.md) — Lifecycle hooks and middleware

## Architecture

```
TinyAgent
├── LLMProvider (pluggable)    — Any LLM backend
├── VirtualFileSystem          — In-memory file operations (ls, read, write, rm, mv, append)
├── AssociativeMemory x2       — Voluntary + Involuntary stores (lexical + semantic)
├── Command Registry           — Built-in + custom commands, runtime register/unregister
├── PipelineEngine             — AST-based code mutations with rollback
├── Hooks                      — Lifecycle interception points
├── Continuity Stack           — Symbolic state persistence across runs
└── Prompt Builder (pluggable) — System prompt generation
```

## Testing

```bash
npm test          # run tests once
npm run test:watch  # watch mode
```

93 tests covering VFS, memory, pipeline, commands, and the full agent lifecycle.

## License

MIT