j1m-agent

Overview

An agentic answer engine in the shape of Perplexity, built to learn how an agent harness actually works. The loop is hand-rolled; everything else is rented. Ask a question and it runs a model → tools → observation loop — searching and fetching the web, then streaming back a grounded answer with citations.

Architecture

The core is a single loop (src/harness/loop.ts) that only ever calls emit(event) — it never touches a terminal or a socket. Two front-ends supply their own emit: a terminal renderer that runs the loop from the CLI, and a TanStack Start route (POST /api/chat) that streams the loop’s events to the browser as SSE. The loop is identical in both.

The server is stateless — every request carries the full conversation, and all persistence is client-side localStorage. The web UI (src/client/*) renders a live trace of the loop next to the streaming answer and its sources, with multi-session history and background-safe streaming.

Tools split in two. SERVER_TOOLS (web search/fetch + datetime) run inside OpenRouter’s server-tool runtime, and their url_citation annotations become the sources list. USER_TOOLS run in this client loop — the seam left open for a future client-side run_script tool.

Design decisions

• Emit-only core. Making the loop’s sole output an emit(event) call is what lets the same code drive both a terminal and an SSE stream — the transport is somebody else’s problem.
• Stateless server. No session store; the client owns the conversation. The server scales trivially and a refresh never loses history.
• Rent the hard parts. Search, fetching, and citations come from OpenRouter server tools rather than a bespoke retrieval stack, keeping the project focused on the harness itself.

Stack

Bun + TanStack Start (React 19) across the client and server; OpenRouter for the model and its server tools; deployed on Render as a native Bun service behind a shared-password gate.