agent-governance/agents/llm-planner-ts

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

# 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

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

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:

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:

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

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

# 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.

See also:

• LLM Planner Python - Python variant
• Multi-Agent - Orchestration system

---

Last updated: 2026-01-24