agent-governance/agents/llm-planner-ts/README.md

# LLM Planner TypeScript

> Tier 0 Observer agent with LLM capabilities - TypeScript/Bun variant

## Overview

The TypeScript LLM Planner is the Bun-native variant of the LLM Planner agent. It provides the same Tier 0 Observer capabilities with LLM-powered plan generation, optimized for the Bun runtime.

## Capabilities

| Capability | Allowed |
|------------|---------|
| Read documentation | Yes |
| Read inventory | Yes |
| Generate plans | Yes |
| LLM inference | Yes |
| Execute commands | **No** |
| Modify files | **No** |

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                   LLM Planner TypeScript                        │
├─────────────────────────────────────────────────────────────────┤
│  index.ts            Entry point and core agent                 │
│  governed-agent.ts   Governance wrapper and state management    │
└─────────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
    ┌─────────┐        ┌───────────┐        ┌──────────┐
    │OpenRouter│        │   Vault   │        │  Ledger  │
    │   LLM    │        │ (Secrets) │        │ (SQLite) │
    └─────────┘        └───────────┘        └──────────┘
```

## Quick Start

```bash
# Enter directory
cd /opt/agent-governance/agents/llm-planner-ts

# Install dependencies (if needed)
bun install

# Run the agent
bun run index.ts

# Or run with specific task
bun run index.ts --task "Plan deployment for service X"
```

## Configuration

### Agent Metadata

```typescript
const AGENT_METADATA = {
  agent_id: "llm-planner-ts-001",
  agent_role: "observer",
  tier: 0,
  version: "0.1.0",
  confidence_threshold: 0.7,
  allowed_side_effects: [
    "read_docs",
    "read_inventory",
    "read_logs",
    "generate_plan",
    "llm_inference"
  ],
  forbidden_actions: [
    "ssh",
    "create_vm",
    "modify_vm",
    "delete_vm",
    "run_ansible",
    "run_terraform"
  ]
};
```

## Modules

### index.ts (280 lines)

Core agent implementation:
- Task request/response types
- Vault secret retrieval
- Ledger logging
- LLM inference

```typescript
interface TaskRequest {
  task_type: "plan" | "analyze";
  description: string;
  context?: Record<string, any>;
  constraints?: string[];
}

interface AgentOutput {
  agent_id: string;
  version: string;
  timestamp: string;
  action: string;
  decision: "EXECUTE" | "SKIP" | "ESCALATE" | "ERROR";
  confidence: number;
  assumptions: string[];
  side_effects: SideEffect[];
  notes_for_humans: string;
  llm_model?: string;
  llm_response?: string;
  plan?: Record<string, any>;
}
```

### governed-agent.ts (870 lines)

Governance integration:
- State tracking
- Phase management
- Compliance checks
- Error handling

## Vault Integration

Secrets are retrieved automatically from Vault:

```typescript
async function getVaultSecret(path: string): Promise<Record<string, any>> {
  const initKeys = await Bun.file("/opt/vault/init-keys.json").json();
  const token = initKeys.root_token;
  const result = await $`curl -sk -H "X-Vault-Token: ${token}" \
    https://127.0.0.1:8200/v1/secret/data/${path}`.json();
  return result.data.data;
}
```

## Ledger Logging

All actions are logged to SQLite:

```typescript
function logToLedger(output: AgentOutput, success: boolean) {
  const db = new Database("/opt/agent-governance/ledger/governance.db");
  db.run(`
    INSERT INTO agent_actions
    (timestamp, agent_id, agent_version, tier, action, decision, confidence, success)
    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
  `, [
    output.timestamp,
    output.agent_id,
    output.version,
    AGENT_METADATA.tier,
    output.action,
    output.decision,
    output.confidence,
    success ? 1 : 0
  ]);
}
```

## Example Usage

```typescript
import { LLMPlannerAgent } from "./index";

const agent = new LLMPlannerAgent();

const result = await agent.processTask({
  task_type: "plan",
  description: "Deploy Redis cluster",
  constraints: ["Sandbox only", "No persistent storage"]
});

console.log(`Decision: ${result.decision}`);
console.log(`Confidence: ${result.confidence}`);
console.log(`Plan: ${result.plan}`);
```

## Testing

```bash
# Type check
bun run tsc --noEmit

# Run tests
bun test

# Quick import test
bun -e "import './index.ts'; console.log('OK')"
```

## Dependencies

| Package | Purpose |
|---------|---------|
| openai | OpenRouter API client |
| zod | Runtime type validation |
| bun:sqlite | SQLite database access |

## Comparison with Python Variant

| Feature | Python | TypeScript |
|---------|--------|------------|
| Runtime | Python 3.11+ | Bun 1.0+ |
| Async model | asyncio | Native Promises |
| Type system | Pydantic | Zod + TypeScript |
| Startup time | ~500ms | ~50ms |
| Memory | ~50MB | ~30MB |

## Architecture Reference

Part of the [Agent Governance System](../../docs/ARCHITECTURE.md).

See also:
- [LLM Planner Python](../llm-planner) - Python variant
- [Multi-Agent](../multi-agent) - Orchestration system

---
*Last updated: 2026-01-24*