Local AI Agent Lab

A from-scratch agent in TypeScript, planned in nine phases. Phases 1–2 are done — configuration, environment doctor, tests, an Ollama adapter and a local chat API; tools and the agent loop come next.

A deliberately framework-free project for understanding agents: context building, decisions, tool validation, policy and approvals, written out explicitly.

Status: phase 2 of 9 (19 Oct 2026). You can chat with the local model from the terminal or the local API. There is no tool use or agent loop yet — the architecture below is the plan, and the interfaces exist in code.

What it includes

• Config validation & `npm run doctor`Checks Node, Ollama and the model before anything runs.
• Local-only guardRejects cloud models and non-loopback addresses.
• Ollama adapter, health check & chat APIRaw HTTP adapter with per-call timeouts; /api/health and /api/chat; a terminal chat.
• Request limitsBody size, message count and length limits; only user and assistant roles accepted.
• TestsVitest, run with npm test.
• ToolsPlannedCalculator, workspace read/search, notes — sandboxed to workspace/.
• Agent loop, approvals, SQLite memory, dashboardPlanned

How it is put together

1. ContextTask + history
2. Model decisionOllama, local
3. ValidateZod tool schemas
4. PolicyAllow / approve / deny
5. Execute & verifySandboxed tools

• Human approval step
• Workspace sandbox
• Local models only

Planned architecture — phases 1–2 of 9 are implemented.

Agent profile

Objective

Understand each part of an agent by implementing it explicitly.

Input

Planned: a task from a local dashboard.

Reasoning

Planned loop: build context → call the model → parse its decision → validate tool arguments with Zod → policy check (allow / require approval / deny).

Tools

Planned: calculator, Planned: workspace read & search, Planned: notes

Execution

Planned: execute, observe, verify, persist to SQLite.

Safety

Designed in from the start: an approval manager that waits for a human decision, and file tools confined to a workspace folder.

Models

Local only — Ollama with qwen3:4b; cloud models are rejected by configuration.