@roackb2/heddle 0.0.18 → 0.0.20

package/README.md

@@ -1,741 +1,267 @@
 # Heddle
 
-Heddle is a terminal coding agent runtime and CLI with semantic drift detection.
-
-It is built to feel like a terminal partner that understands your project, keeps continuity across real work, and becomes more useful over time.
-
-It is open source, provider-agnostic, supports OpenAI and Anthropic models, and can build memory across sessions. For agentic-system builders, Heddle also exposes heartbeat primitives for autonomous wake cycles, checkpointing, and long-running background work.
-
-Heddle is designed to make live agent runs more observable, not just easier to launch. With CyberLoop installed, Heddle can show whether the agent's outputs are moving away from the recent response trajectory, surface `drift=unknown|low|medium|high` in chat, and write drift annotations into saved traces instead of leaving you to infer that only from token usage and tool calls.
-
-If you are interested in the underlying methodology, Heddle's drift telemetry is powered by [CyberLoop on npm](https://www.npmjs.com/package/cyberloop). See the [CyberLoop repository](https://github.com/roackb2/cyberloop) and [paper](https://zenodo.org/records/18138161) for the geometric-control and trajectory-based details.
-
-## Agenda
-
-- [Chat And CLI Usage](#chat-and-cli-usage)
-- [Control Plane](#control-plane)
-- [Knowledge Persistence](#knowledge-persistence)
-- [Semantic Drift](#semantic-drift)
-- [Heartbeat](#heartbeat)
-- [Programmatic Use](#programmatic-use)
-- [Capability Details](#capability-details)
-- [Supported Providers And Models](#supported-providers-and-models)
-- [Project Config](#project-config)
-- [Design Direction](#design-direction)
-
-## How Heddle Helps
-
-- daily development work in real coding projects
-- understanding unfamiliar repositories and carrying fixes through inspection, edits, and verification
-- infrastructure and environment inspection through approval-gated shell commands
-- broader terminal-based agent workflows whenever the needed CLI tools already exist in the environment
-- tasks such as image, media, or document processing through existing command-line tools like `ffmpeg`, ImageMagick, or project-specific scripts
-- long-running multi-step work that benefits from chat continuity, short plans, and explicit operator control
-
-## Advanced Capabilities
-
-- provider-agnostic model support across OpenAI and Anthropic
-- embeddable `runAgentLoop` API for building non-CLI agent hosts
-- `runAgentHeartbeat` for scheduler-driven autonomous wake cycles without chat by default
-- reorganized core runtime modules under `src/core` for agent, runtime, llm, tools, prompts, trace, and shared utilities
-- native React/Vite control plane served by `heddle daemon` for local browser-based oversight
-- serializable checkpoints for resume, background execution, and hosted workers
-- host-facing heartbeat task/run views plus websocket-friendly status/progress/response adapters
-- provider-backed hosted web search through `web_search`
-- local image viewing from referenced file paths through `view_image`
-- inline `@file` mentions that tell the agent which workspace files to inspect first
-- multi-turn sessions with save, switch, continue, rename, and close flows
-- automatic conversation compaction for longer chats, plus manual `/compact` when needed
-- persistent workspace knowledge through `.heddle/memory/`
-- lightweight working-plan tracking through `update_plan`
-- approval-gated shell execution with remembered per-project approvals
-- trace logs, persistent chat state, and project instruction loading under `.heddle/`
+Heddle is an open-source terminal coding agent runtime and CLI for real project work.
 
-## Install
-
-Global install:
-
-```bash
-npm install -g @roackb2/heddle
-```
-
-Run without a global install:
-
-```bash
-npx @roackb2/heddle
-```
-
-The installed CLI command remains `heddle`.
-
-If you want CyberLoop drift telemetry in chat, or you want to import `cyberloop/advanced` in your own host, install `cyberloop` in the same environment as Heddle:
-
-```bash
-npm install -g cyberloop
-# or for project-local usage
-npm install cyberloop
-```
-
-The plain `npx @roackb2/heddle` path does not include optional peer dependencies. For one-off drift-enabled usage, install both packages locally or run:
+It is designed for workflows where an agent needs to inspect a live repository, make bounded changes, verify results, keep continuity across sessions, and stay observable to the operator. Heddle supports OpenAI and Anthropic models, stores local workspace state under `.heddle/`, and includes both a terminal chat experience and a browser control plane.
 
-```bash
-npx -p @roackb2/heddle -p cyberloop heddle
-```
-
-If you are developing inside the Heddle repo itself, `yarn install` also installs `cyberloop` through `devDependencies`, so `yarn chat:dev` can use the published package path without extra setup.
-
-For local development against the full CLI entrypoint, use `yarn cli:dev`. The `chat:dev` scripts intentionally start chat mode directly and do not route subcommands such as `heartbeat`.
-
-## Chat And CLI Usage
-
-### Quick Start
-
-1. Set an API key for a supported provider.
-
-```bash
-export OPENAI_API_KEY=your_key_here
-# or
-export ANTHROPIC_API_KEY=your_key_here
-```
+In plain terms: Heddle is for people who want an agent that can work inside an actual project, not just answer isolated prompts.
 
-2. Move into the project you want Heddle to work on.
-
-```bash
-cd /path/to/project
-```
+## What Heddle Does
 
-3. Start chat mode.
+At a high level, Heddle helps with:
 
-```bash
-heddle
-```
+- understanding unfamiliar repositories
+- making code or doc changes inside a real workspace
+- running bounded verification like builds, tests, and repo review
+- keeping multi-step work going across sessions instead of starting from scratch each time
+- exposing more operator visibility than a black-box chat tool
 
-Heddle uses the current directory as the workspace root unless you pass `--cwd`.
+If you want a terminal-first coding agent with local state, review traces, and a path toward longer-running workflows, that is the problem Heddle is trying to solve.
 
-The default workflow is interactive chat, not one-shot prompts. You keep a session open, inspect the repo, switch models, run direct shell commands when needed, and continue earlier sessions later.
+## Major Features
 
-### Chat Workflow
+### Terminal chat for real coding work
 
-Start chat in the current repo:
+The main way to use Heddle is interactive chat in a repository:
 
 ```bash
 heddle
-heddle chat
-heddle --cwd /path/to/project
-heddle chat --model gpt-5.4-mini --max-steps 20
 ```
 
-Typical chat use cases:
-
-- ask Heddle to explain architecture, code paths, tests, or build setup
-- iterate on a fix over multiple prompts instead of fitting everything into one request
-- inspect files, search the repo, and edit code inside one persistent session
-- keep a long coding conversation usable through saved sessions, `/continue`, automatic history compaction, and manual `/compact`
-- let the agent create and update a short working plan for a multi-step implementation
-- search official docs or other current external references with provider-backed `web_search`
-- mention important repo files with `@path/to/file` so the agent treats them as first-pass context
-- reference a local screenshot path and have the agent inspect it with `view_image`
-- run direct shell commands from chat with `!<command>`
-- pause and later resume earlier sessions
-
-Useful chat commands:
-
-- `/help`: show local chat commands
-- `/continue`: resume the current session from its last interrupted or prior run
-- `/model`: show the active model
-- `/model list`: show the built-in shortlist
-- `/model set <query>`: open the interactive model picker
-- `/model <name>`: switch models directly
-- `/session list`: list recent saved sessions
-- `/session choose <query>`: choose a recent session interactively
-- `/session new [name]`: create a new session
-- `/session switch <id>`: switch to another session
-- `/session continue <id>`: switch and immediately continue that session
-- `/session rename <name>`: rename the current session
-- `/session close <id>`: remove a saved session
-- `/clear`: clear the current transcript
-- `/compact`: compact older session history immediately
-- `/drift`: show CyberLoop semantic drift detection status
-- `/drift on`: re-enable observe-only CyberLoop kinematics telemetry for chat runs
-- `/drift off`: disable CyberLoop semantic drift detection
-- `!<command>`: run a shell command directly in chat
-
-Direct shell in chat:
+From there, Heddle can inspect files, explain code, make edits, run shell commands with the right approval model, and carry a task through multiple turns.
 
-```bash
-!pwd
-!git status
-!yarn test
-```
-
-Read-oriented commands stay in inspect mode when possible. Workspace-changing or unclassified commands fall back to approval-gated execution.
-
-Chat state is stored under `.heddle/`, including saved sessions, traces, approvals, and memory notes. The footer context indicator is an estimate of total request input against the active model's context window, not only the raw chat history length.
-
-For local development against the sibling CyberLoop repo, run chat with the middleware module path:
-
-```bash
-HEDDLE_CYBERLOOP_ADVANCED_MODULE=/Users/roackb2/Studio/projects/CyberLoop/src/advanced/kinematics-middleware.ts yarn chat:dev:openai
-```
-
-Drift telemetry is enabled by default for new sessions. For installed usage, install the optional `cyberloop` peer dependency in the same environment as Heddle so it can dynamically import `cyberloop/advanced`.
-
-### CLI Commands
-
-Supported commands:
+This is the core feature. If you only use Heddle as a coding agent in the terminal, this is the part you care about.
 
-- `heddle` or `heddle chat`: start interactive chat mode
-- `heddle ask "<goal>"`: run a single prompt and exit
-- `heddle heartbeat start [--every 30m] [--task "<durable task>"]`: create or enable the default heartbeat task and run the foreground scheduler
-- `heddle heartbeat task add --id <id> --task "<durable task>" [--every 15m]`: create or update a scheduled heartbeat task
-- `heddle heartbeat task list`: list local heartbeat tasks
-- `heddle heartbeat task show <id>`: show a task's schedule, last decision, and last run summary
-- `heddle heartbeat task enable <id>` / `heddle heartbeat task disable <id>`: toggle a heartbeat task
-- `heddle heartbeat run --once`: run due heartbeat tasks once
-- `heddle heartbeat run [--poll 60s]`: run the foreground heartbeat scheduler until interrupted; heartbeat runs print scheduler, agent, tool, decision, and checkpoint progress events
-- `heddle heartbeat runs list [--task <id>] [--limit 10]`: list saved heartbeat run records
-- `heddle heartbeat runs show <run-id|latest> [--task <id>]`: show the final agent output for a saved heartbeat run
-- `heddle init`: create a `heddle.config.json` template in the current project
+More: [Chat and sessions guide](docs/guides/chat-and-sessions.md)
 
-Common flags:
+### Sessions and continuity
 
-- `--cwd <path>`: run against another workspace root
-- `--model <name>`: choose the active model
-- `--max-steps <n>`: limit the agent loop length
+Heddle keeps saved sessions under `.heddle/` so longer work does not have to reset every time. That means you can come back to an interrupted task, continue a previous debugging thread, or preserve project-specific context across runs.
 
-## Control Plane
+This matters if you are doing real multi-step work rather than one-shot prompts.
 
-Heddle includes a local browser control plane for workspace oversight when you want a native UI in addition to terminal chat.
+Typical session commands include:
 
-The current control plane is still early, but it has moved beyond a placeholder dashboard into a workstation-style local UI for inspecting sessions, review evidence, heartbeat tasks, and run history.
+- `/session list`
+- `/session switch <id>`
+- `/continue`
+- `/compact`
 
-Current stack:
+More: [Chat and sessions guide](docs/guides/chat-and-sessions.md)
 
-- `src/server`: Express-hosted tRPC server
-- `src/web`: React/Vite web client
-- `src/server/features/control-plane`: control-plane-specific server feature logic
-- pino logs written locally for debugging
+### Control plane
 
-Start the daemon from a workspace:
+The control plane is Heddle's local browser UI:
 
 ```bash
 heddle daemon
 ```
 
-By default, the daemon binds to `127.0.0.1:8765` and serves the built web app plus the tRPC API. The current browser UI surfaces:
+It gives you a browser-based view into sessions, run state, heartbeat tasks, and review-oriented details. The purpose is operator oversight: seeing what the agent is doing, reviewing history more comfortably, and managing local runs from a UI instead of only from the terminal.
 
-- workspace and `.heddle/` state location
-- saved chat sessions with sidebar navigation, resizable desktop panels, conversation view, and review-oriented detail inspection
-- browser-side session actions for new session, send, continue, cancel, and pending approval resolution
-- live per-session updates over SSE for run status, tool progress, assistant streaming text, and saved-session changes
-- a model selector backed by the server-side built-in model catalog, plus a drift toggle and latest trace-derived drift level
-- debounced `@file` mention suggestions in the composer, backed by a capped workspace file search endpoint
-- compact tool-result cards for saved tool outputs such as `list_files: {...}`
-- lightweight toast notifications for session/action success and failure
-- heartbeat task status, scheduling state, selected task detail, and run history
-- recent heartbeat run summaries and usage data
+If terminal chat is the execution surface, the control plane is the oversight surface.
 
-You can override host and port:
+This is useful if you want a more inspectable and operator-friendly workflow than a plain CLI transcript.
 
-```bash
-heddle daemon --host 127.0.0.1 --port 8765
-```
+More: [Control plane guide](docs/guides/control-plane.md)
 
-For local development, run the server and client separately:
+### Knowledge persistence
 
-```bash
-yarn server:dev
-yarn client:dev
-```
+Heddle can keep durable project knowledge in markdown notes under `.heddle/memory/`.
 
-`yarn server:dev` starts the backend API server only at `127.0.0.1:8765`. It does not serve the web app shell at `/`.
+The idea is simple: if the agent learns a stable fact about your repo — architecture notes, command quirks, recurring build issues, conventions — it can save that knowledge so future sessions do not have to rediscover it.
 
-`yarn client:dev` starts the Vite web client at `127.0.0.1:5173` and proxies `/trpc` and `/control-plane` requests to the backend server.
+This is not meant to be a hidden vector database or magical long-term memory. It is readable, local, workspace-scoped memory that both the agent and the human can inspect.
 
-In other words:
+This matters if you want the agent to become more useful over time in a specific project.
 
-- development mode uses two services:
-  - backend API on `8765`
-  - Vite frontend on `5173`
-- built daemon mode uses one service:
-  - `heddle daemon` serves both the built web client and the backend API on the same port
+More: [Knowledge persistence](docs/guides/knowledge-persistence.md)
 
-For built/local operator usage, run:
+### Heartbeat
 
-```bash
-yarn build
-heddle daemon
-```
-
-That path serves the built control-plane frontend from `dist/src/web` and mounts the backend API and session-event endpoints from the same daemon process. If you open the backend dev server port directly while only `yarn server:dev` is running, you may see `Cannot GET /`, because that dev path is API-only.
+Heartbeat is Heddle's model for bounded autonomous wake cycles.
 
-If you add or change control-plane tRPC routes, restart the daemon/server process. Vite hot reload updates the browser bundle only; a still-running daemon will not know about new procedures and may return `No procedure found on path ...`.
+Instead of only running when a human types a prompt, a heartbeat task lets Heddle wake up on a schedule, do a limited amount of work, checkpoint the result, and decide whether to continue, pause, complete, or escalate.
 
-The server writes pino logs to `.heddle/logs/server.log` by default. Override the path with:
+Example commands:
 
 ```bash
-HEDDLE_SERVER_LOG_FILE=/path/to/server.log yarn server:dev
+heddle heartbeat start --every 30m
+heddle heartbeat task add --id repo-gardener --task "Check for safe maintenance work" --every 1h
+heddle heartbeat task list
 ```
 
-The control plane is still early and not yet a full IDE-like browser-native operator surface. The next milestones are manual validation of the browser session flows against real `.heddle` state, heartbeat task mutations, and structured file-level review payloads for a richer diff viewer.
-
-## Knowledge Persistence
-
-Heddle can maintain durable workspace knowledge under `.heddle/memory/`.
-
-The goal is to help Heddle learn from real project work over time instead of rediscovering the same stable facts every session.
-
-Typical examples:
-
-- architecture notes that future sessions should reuse
-- recurring build, test, or environment quirks
-- important repo conventions and command patterns
-- durable findings from completed implementation work
+Why this exists: some agent work is not a single interactive chat. You may want periodic repo inspection, recurring maintenance checks, scheduled summaries, or a host that can resume work in bounded steps.
 
-The memory model is intentionally simple:
+If you do not need scheduled or semi-autonomous workflows, you can ignore heartbeat entirely and just use chat.
 
-- memory is stored as readable markdown files in the project state directory
-- Heddle can list, read, search, and edit those notes
-- shell tools are still available when flexible retrieval or editing is needed
-- memory is meant for stable, reusable knowledge, not scratch notes or speculative plans
+More: [Heartbeat guide](docs/guides/heartbeat.md)
 
-This is one of Heddle's more distinctive host-side capabilities: the aim is not just to answer the current prompt, but to let the runtime accumulate project understanding from your operations and become more useful across sessions.
+### Semantic drift
 
-## Semantic Drift
+Semantic drift is optional telemetry that helps you see whether the assistant's responses appear to be moving away from the recent semantic trajectory of the conversation.
 
-Heddle can show whether the agent's responses are drifting away from the recent semantic trajectory of the conversation.
+With optional [CyberLoop](https://www.npmjs.com/package/cyberloop) integration installed, Heddle can surface drift levels such as:
 
-The CyberLoop workflow is observe-only. Drift telemetry is enabled by default for new chat sessions when `cyberloop` is available. Heddle loads real [CyberLoop](https://www.npmjs.com/package/cyberloop) kinematics middleware, embeds agent output frames with OpenAI embeddings, compares the current response trajectory against the previous assistant response when available, shows `drift=unknown|low|medium|high` in the footer, highlights medium/high drift in the status bar, and writes `cyberloop.annotation` events into saved traces.
+- `drift=unknown`
+- `drift=low`
+- `drift=medium`
+- `drift=high`
 
-Tool outputs are excluded from chat drift scoring so the signal focuses on where the agent's own responses are heading. Chat drift uses a more sensitive default stability threshold than CyberLoop's library default; set `HEDDLE_DRIFT_STABILITY_THRESHOLD` if you want to tune it. The toggle is saved on the active chat session, and `/drift` reports the last unavailable reason if the middleware or embeddings fail.
+This is an observability feature, not a magic correctness guarantee. It is meant to help operators notice when a run may be getting less aligned with its recent direction.
 
-Heddle does not calculate semantic drift itself. For the underlying methodology, see the [CyberLoop repository](https://github.com/roackb2/cyberloop) and [paper](https://zenodo.org/records/18138161).
+If you are just looking for a coding agent, you do not need to care about this on day one. If you care about agent observability and runtime behavior, it is one of Heddle's more distinctive features.
 
-## Heartbeat
+More: [Semantic drift](docs/guides/semantic-drift.md)
 
-Heddle exposes `runAgentHeartbeat` for autonomous, scheduler-driven agent work.
+### Programmatic runtime APIs
 
-Heartbeat is not an interactive chat mode. It is a host/runtime primitive for systems that want to wake an agent periodically, let it work within budget and approval limits, checkpoint the result, and decide what should happen next.
+Heddle is not only a CLI. The npm package also exposes runtime primitives such as `runAgentLoop` and `runAgentHeartbeat` so other hosts can build on top of it.
 
-A heartbeat wake cycle:
+This is for people building their own agent hosts, schedulers, or control surfaces rather than only using the packaged CLI.
 
-- loads a durable task plus an optional checkpoint
-- resumes prior transcript state if available
-- lets the agent do bounded useful work without a human prompt
-- checkpoints the new state
-- returns a decision: `continue`, `pause`, `complete`, or `escalate`
+More: [Programmatic use](docs/guides/programmatic-use.md)
 
-This is intended for hosted workers, local schedulers, long-running agents, and systems like agent social platforms where agents need to keep working over time without staying in a live chat session.
+## Why Someone Might Choose Heddle
 
-Heartbeat uses a larger default step budget than ordinary short chat runs so a wake cycle has room to inspect, act, and checkpoint. Hosts can still pass `maxSteps` when they need stricter control.
+Heddle is a good fit if you want:
 
-The built-in CLI heartbeat runner is intentionally conservative: it has no live approval UI, so approval-gated file edits and mutation shell commands are denied with a clear blocker. It is useful today for recurring inspection, summaries, memory-note updates, and escalation reports. Hosts can provide their own `approveToolCall` policy when they want autonomous agents to perform broader actions.
+- a terminal-first coding agent that works in a real repository
+- local state and durable project memory
+- explicit traces, approvals, and reviewable workflow artifacts
+- a browser control plane for local oversight
+- a path from interactive use to programmatic and scheduled agent workflows
 
-For repeated wake cycles, Heddle also exposes a local-first scheduler core:
+Heddle is probably not the right fit if you only want a very simple one-shot chat wrapper and do not care about sessions, persistence, observability, or operator control.
 
-- `runDueHeartbeatTasks`: scan a task store once, run due tasks, save checkpoints, and update next-run state
-- `runHeartbeatScheduler`: run the same scan loop until an `AbortSignal` stops it
-- `createFileHeartbeatTaskStore`: store task definitions and checkpoints under `.heddle/heartbeat/`-style directories
-
-Cron, launchd, systemd, hosted queues, and Lucid-style services should be treated as hosts around this API, not as Heddle's internal scheduler model.
+## Install
 
-Try a small local heartbeat example:
+Global install:
 
 ```bash
-export OPENAI_API_KEY=your_key_here
-yarn example:heartbeat
+npm install -g @roackb2/heddle
 ```
 
-The example stores its checkpoint at `.heddle/examples/heartbeat-demo-checkpoint.json`, so running it again resumes from the previous wake cycle.
-
-Try the local scheduler API with a real LLM:
+Run without a global install:
 
 ```bash
-export OPENAI_API_KEY=your_key_here
-yarn example:heartbeat-scheduler
+npx @roackb2/heddle
 ```
 
-The scheduler example writes task, checkpoint, and run records under `.heddle/examples/heartbeat-scheduler/`.
+The installed CLI command is `heddle`.
 
-The installed CLI also exposes the local heartbeat scheduler:
+## Requirements
 
-```bash
-heddle heartbeat start --every 30m
-heddle heartbeat task add --id repo-gardener --task "Check for safe maintenance work" --every 1h
-heddle heartbeat task list
-heddle heartbeat task show repo-gardener
-heddle heartbeat run --once
-heddle heartbeat run --poll 60s
-heddle heartbeat runs list --task repo-gardener
-heddle heartbeat runs show latest --task repo-gardener
-```
+- Node.js 20+
+- an API key for at least one supported provider:
+  - `OPENAI_API_KEY`
+  - `ANTHROPIC_API_KEY`
 
-For an OpenClaw-like local experience, `heartbeat start` creates or enables a default periodic task and runs the foreground scheduler in one command. It prints the agent's final summary and decision after each run. Stop it with `Ctrl+C`.
+## Quick Start
 
-For programmatic hosts, heartbeat now also exposes compact task/run views and a thin host-adapter layer, so external apps can consume stable status/progress/response payloads without parsing raw CLI output or full trace history.
-
-Inside this repository, use the dev CLI entrypoint instead:
+1. Set a provider API key.
 
 ```bash
-yarn cli:dev heartbeat start --every 30m
+export OPENAI_API_KEY=your_key_here
+# or
+export ANTHROPIC_API_KEY=your_key_here
 ```
 
-Adding a task only saves scheduler state; it does not start a background process. Stop a foreground scheduler with `Ctrl+C`, or pause a task with:
+2. Move into the project you want Heddle to operate on.
 
 ```bash
-heddle heartbeat task disable repo-gardener
-```
-
-For hosts that want storage handled by Heddle, use `runStoredHeartbeat` with a checkpoint store:
-
-```ts
-import { createFileHeartbeatCheckpointStore, runStoredHeartbeat } from '@roackb2/heddle'
-
-const result = await runStoredHeartbeat({
-  task: 'Keep this project moving when safe autonomous progress is available',
-  store: createFileHeartbeatCheckpointStore({
-    path: '.heddle/heartbeat/project-maintenance.json',
-  }),
-})
-
-// result.nextDelayMs is a scheduling hint. The host still owns the timer,
-// cron job, queue, worker, or hosted scheduler that wakes the agent again.
-```
-
-For hosts that want task scheduling handled by Heddle, use the scheduler API:
-
-```ts
-import { createFileHeartbeatTaskStore, runHeartbeatScheduler } from '@roackb2/heddle'
-
-const controller = new AbortController()
-
-await runHeartbeatScheduler({
-  store: createFileHeartbeatTaskStore({ dir: '.heddle/heartbeat' }),
-  pollIntervalMs: 60_000,
-  signal: controller.signal,
-})
-```
-
-To read compact task/run state back out for dashboards or hosted controllers:
-
-```ts
-import {
-  createFileHeartbeatTaskStore,
-  listHeartbeatTaskViews,
-  listHeartbeatRunViews,
-} from '@roackb2/heddle'
-
-const store = createFileHeartbeatTaskStore({ dir: '.heddle/heartbeat' })
-
-const tasks = await listHeartbeatTaskViews(store)
-const runs = await listHeartbeatRunViews(store, { taskId: 'repo-gardener', limit: 5 })
-```
-
-Those views are intentionally smaller than full checkpoints or traces. They expose stable operator-facing fields such as task ID, status, progress, decision, outcome, resumability, usage, and latest summary.
-
-## Programmatic Use
-
-The npm package exports a programmatic execution loop for building other agent hosts on top of Heddle.
-
-Use `runAgentLoop` when you want Heddle to assemble the model adapter, default tool bundle, memory tools, and event stream:
-
-```ts
-import { runAgentLoop } from '@roackb2/heddle'
-
-const result = await runAgentLoop({
-  goal: 'Inspect this repo and summarize the main architecture',
-  model: 'gpt-5.1-codex',
-  workspaceRoot: process.cwd(),
-  onEvent(event) {
-    // Render progress, persist traces, feed middleware, or bridge into another app.
-    console.log(event.type)
-  },
-})
-```
-
-Persist `result.state` or wrap it with `createAgentLoopCheckpoint(result.state)` when another host needs to continue later:
-
-```ts
-import { createAgentLoopCheckpoint, runAgentLoop } from '@roackb2/heddle'
-
-const checkpoint = createAgentLoopCheckpoint(result.state)
-
-await runAgentLoop({
-  goal: 'Continue from the prior run and identify the next action',
-  resumeFrom: checkpoint,
-})
-```
-
-The loop emits structured events for:
-
-- loop start and finish
-- assistant streaming updates
-- trace events such as tool calls, tool results, approvals, and final outcome
-
-The returned result also includes a serializable `state` object with the model, provider, workspace root, outcome, transcript, trace, usage, and timestamps. This is the boundary future hosts can persist for background execution, dashboards, middleware, or heartbeat-style continuation.
-
-For host UIs or controllers that do not want to understand Heddle's full trace/event model, the package also exports compact heartbeat views plus a thin status/progress/response adapter layer:
-
-```ts
-import {
-  createFileHeartbeatTaskStore,
-  heartbeatSchedulerEventToLucidMessages,
-  heartbeatTaskViewToLucidMessages,
-  listHeartbeatTaskViews,
-} from '@roackb2/heddle'
-
-const store = createFileHeartbeatTaskStore({ dir: '.heddle/heartbeat' })
-const tasks = await listHeartbeatTaskViews(store)
-
-for (const task of tasks) {
-  const messages = heartbeatTaskViewToLucidMessages(task)
-  console.log(messages)
-}
-
-const schedulerMessages = heartbeatSchedulerEventToLucidMessages({
-  type: 'heartbeat.task.started',
-  taskId: 'repo-gardener',
-  loadedCheckpoint: true,
-  status: 'running',
-  progress: 'Resuming heartbeat wake from the last checkpoint.',
-  timestamp: new Date().toISOString(),
-})
-```
-
-The adapter names are Lucid-oriented because that is one target host, but the payload shape is generic: compact status, progress, and response messages that another app can publish over websockets, SSE, or logs.
-
-For passive semantic-drift experiments, `createCyberLoopObserver` can consume Heddle's event stream and run CyberLoop-compatible middleware over normalized runtime frames:
-
-```ts
-import {
-  createCyberLoopObserver,
-  createRuntimeFrameEmbedder,
-  runAgentLoop,
-} from '@roackb2/heddle'
-import { kinematicsMiddleware } from 'cyberloop/advanced'
-
-const frameEmbedder = createRuntimeFrameEmbedder({
-  async embedText(text) {
-    return embedWithYourProvider(text)
-  },
-})
-
-const observer = createCyberLoopObserver({
-  middleware: [
-    kinematicsMiddleware({
-      embedder: frameEmbedder,
-      goalEmbedding: await embedWithYourProvider('Investigate this repo'),
-    }),
-  ],
-  onAnnotation(annotation) {
-    console.log(annotation.driftLevel, annotation.frame.kind)
-  },
-})
-
-await runAgentLoop({
-  goal: 'Investigate this repo',
-  onEvent: observer.handleEvent,
-})
-await observer.flush()
-```
-
-This is intentionally observe-only. Heddle still owns execution, tools, approvals, and checkpoints; CyberLoop-style middleware can annotate the run without steering or halting it. Heddle does not calculate semantic drift itself; actual drift signals should come from CyberLoop metadata such as kinematics, manifold, or Grassmannian channels.
-
-For autonomous background work, `runAgentHeartbeat` runs one wake cycle from a durable task and optional checkpoint:
-
-```ts
-import { runAgentHeartbeat } from '@roackb2/heddle'
-
-const heartbeat = await runAgentHeartbeat({
-  task: 'Check whether there is safe maintenance work to do for this project',
-  checkpoint,
-  maxSteps: 8,
-})
-
-// Persist heartbeat.checkpoint, then schedule the next wake based on heartbeat.decision.
+cd /path/to/project
 ```
 
-Heartbeat is not chat by default. It is meant for scheduler-driven agents that wake up, reload state, do bounded autonomous work, checkpoint, and either continue, pause, complete, or escalate.
-
-For repeated local or hosted wake cycles, `runDueHeartbeatTasks`, `runHeartbeatScheduler`, and `createFileHeartbeatTaskStore` provide the scheduler layer above one-shot heartbeat runs.
-
-Lower-level pieces are still exported for custom hosts, including:
-
-- `runAgent`
-- `runAgentLoop`
-- `runAgentHeartbeat`
-- `runHeartbeatScheduler`
-- `createFileHeartbeatTaskStore`
-- `createDefaultAgentTools`
-- LLM adapter helpers
-- built-in tools
-- trace utilities
-
-Install as a dependency with:
+3. Start interactive chat.
 
 ```bash
-npm install @roackb2/heddle
+heddle
 ```
 
-If you want CyberLoop middleware examples or chat drift telemetry, install the optional peer dependency in the same project:
+4. Ask for something concrete, for example:
 
-```bash
-npm install cyberloop
+```text
+Summarize this repository and point out the main build and test commands.
 ```
 
-For a small real-LLM example of embedding the loop with a custom host tool:
+5. If you want the browser oversight UI, run:
 
 ```bash
-export OPENAI_API_KEY=your_key_here
-yarn example:programmatic
+heddle daemon
 ```
 
-To try the same example with Claude:
+By default, Heddle uses the current directory as the workspace root unless you pass `--cwd`.
 
-```bash
-export ANTHROPIC_API_KEY=your_key_here
-HEDDLE_EXAMPLE_MODEL=claude-3-5-haiku-latest yarn example:programmatic
-```
+## Optional CyberLoop Integration
 
-For a small no-network observer example:
+If you want semantic drift telemetry in chat, install `cyberloop` in the same environment as Heddle:
 
 ```bash
-yarn example:cyberloop-observer
+npm install -g cyberloop
+# or for project-local usage
+npm install cyberloop
 ```
 
-The public API lives in [src/index.ts](/Users/roackb2/Studio/projects/ProjectHeddle/heddle/src/index.ts).
-
-## Capability Details
-
-Heddle currently supports:
-
-- repository inspection with `list_files`, `read_file`, and `search_files`
-- code and doc changes with `edit_file`
-- provider-backed hosted web search through `web_search`
-- local screenshot and image inspection through `view_image`
-- native browser control plane through `heddle daemon`
-- inline `@file` mentions for file-priority context without pasting file contents into the prompt
-- browser composer `@file` suggestions in the control plane, backed by workspace file search
-- shell execution with inspect vs approval-gated mutate behavior
-- multi-turn chat sessions with saved history under `.heddle/`
-- session management with create, switch, continue, rename, and close flows
-- automatic conversation compaction so longer chats preserve context instead of growing unbounded
-- manual `/compact` to shrink the current session transcript on demand
-- persistent workspace memory notes under `.heddle/memory/`
-- serializable run checkpoints for programmatic hosts and later continuation
-- short working-plan support through `update_plan` for substantial multi-step tasks
-- remembered per-project approvals for repeated commands and edits
-- interrupt and resume support for longer-running coding workflows
-- request-size aware context tracking in chat so the footer reflects model input usage, not only raw history size
+For one-off usage without a global install:
 
-The image workflow is intentionally simple for now: users can reference a local image path in chat, and the agent can decide whether to inspect it with `view_image`. Heddle does not require a full multimodal attachment model for this first version.
-
-The file-mention workflow is also intentionally lightweight: `@path/to/file` tells Heddle that the file is important context and should be inspected before answering, but it does not automatically inline the file contents into the prompt.
-
-The planning workflow is also intentionally lightweight: Heddle does not force a heavyweight planner or a separate "plan mode," but it can automatically record and update a short plan when a task is substantial enough to benefit from visible progress tracking.
-
-The web-search workflow is provider-backed rather than crawler-backed: OpenAI models use OpenAI-hosted web search, and Anthropic models use Anthropic-hosted web search when available through the selected model/tool path.
-
-## What Heddle Does
-
-Heddle runs an agent loop against your workspace:
-
-```text
-goal
-  -> send transcript + tool definitions to the model
-  -> model answers or requests tool calls
-  -> execute tools in the workspace
-  -> append results to the transcript
-  -> continue until done / max steps / error
+```bash
+npx -p @roackb2/heddle -p cyberloop heddle
 ```
 
-Current focus:
+## Documentation
 
-- chat-first coding and repository workflows from the terminal
-- minimal runtime behavior instead of a large framework surface
-- traceability and operator control over hidden orchestration
+### Start here
 
-## Supported Providers And Models
+- [Documentation hub](docs/README.md)
+- [Chat and sessions guide](docs/guides/chat-and-sessions.md)
+- [CLI reference](docs/reference/cli.md)
 
-Heddle currently has working adapters for:
+### Feature guides
 
-- OpenAI
-- Anthropic
+- [Control plane](docs/guides/control-plane.md)
+- [Heartbeat](docs/guides/heartbeat.md)
+- [Knowledge persistence](docs/guides/knowledge-persistence.md)
+- [Semantic drift](docs/guides/semantic-drift.md)
+- [Programmatic use](docs/guides/programmatic-use.md)
 
-Environment variables:
+### Contributors
 
-- `OPENAI_API_KEY` for OpenAI models
-- `ANTHROPIC_API_KEY` for Anthropic models
-- dev fallback env vars are also accepted: `PERSONAL_OPENAI_API_KEY` and `PERSONAL_ANTHROPIC_API_KEY`
+- [Development and contributing](docs/guides/development.md)
+- [Framework Vision](docs/framework-vision.md)
+- [Coding Agent Roadmap](docs/coding-agent-roadmap.md)
 
-Default models:
+## Project Status
 
-- OpenAI: `gpt-5.1-codex`
-- Anthropic: `claude-sonnet-4-6`
+Heddle is already useful for real coding-agent workflows, but it is still evolving.
 
-Built-in model shortlist exposed by the CLI UI:
+Current strengths include:
 
-- OpenAI: `gpt-5.4`, `gpt-5.4-pro`, `gpt-5.4-mini`, `gpt-5.4-nano`
-- OpenAI: `gpt-5`, `gpt-5-pro`, `gpt-5-mini`, `gpt-5-nano`
-- OpenAI: `gpt-5.2`, `gpt-5.2-pro`, `gpt-5.1`
-- OpenAI: `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`
-- OpenAI: `o3-pro`, `o3`, `o3-mini`, `o4-mini`
-- OpenAI coding models: `gpt-5.1-codex`, `gpt-5.1-codex-max`, `gpt-5.1-codex-mini`
-- Anthropic: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`
-- Anthropic: `claude-opus-4-1`, `claude-opus-4-0`, `claude-sonnet-4-0`
-- Anthropic: `claude-3-7-sonnet-latest`
-- Anthropic: `claude-3-5-sonnet-latest`, `claude-3-5-haiku-latest`
+- terminal-first coding and repository workflows
+- explicit traces, approvals, and local workspace state
+- browser-based oversight through the control plane
+- local-first heartbeat primitives for scheduled agent work
+- practical programmatic hooks for custom hosts
 
-Notes:
+Current limitations include:
 
-- model selection is inferred from the model name prefix
-- Gemini model names are recognized by provider inference, but a Google adapter is not wired yet
-- you can pass another model name with `--model`, but it only works if the corresponding provider adapter supports it
+- the browser control plane is still early compared with a full IDE-like environment
+- some advanced workflows remain better documented in source and examples than in polished product UX
+- the project surface is still changing as the runtime matures
 
-## Project Config
+## Development
 
-You can store project defaults in `heddle.config.json`:
+If you want to work on Heddle itself:
 
-```json
-{
-  "model": "gpt-5.1-codex",
-  "maxSteps": 100,
-  "stateDir": ".heddle",
-  "directShellApproval": "never",
-  "searchIgnoreDirs": [".git", "dist", "node_modules", ".heddle"],
-  "agentContextPaths": ["AGENTS.md"]
-}
+```bash
+git clone https://github.com/roackb2/heddle.git
+cd heddle
+yarn install
+yarn build
+yarn test
 ```
 
-Precedence order:
-
-- CLI flags override `heddle.config.json`
-- `heddle.config.json` overrides environment-driven defaults
-
-Field notes:
-
-- `stateDir`: where traces, logs, approvals, and chat state are stored
-- `directShellApproval`: whether explicit `!command` input in chat still asks for approval
-- `searchIgnoreDirs`: directories excluded from `search_files`
-- `agentContextPaths`: project instruction files injected into the system prompt
-
-## Design Direction
-
-Heddle is currently optimized for coding and terminal workflows, but the long-term goal is broader: an open, provider-agnostic runtime for tool-using agents in real working environments.
-
-The current CLI is the proving ground, not the endpoint. The coding-agent workflow matters because it is a demanding, evidence-heavy environment with real files, shell tools, long-running context, and operator oversight. If the runtime holds up there, it can later support wider agentic workflows beyond software projects.
-
-The design direction stays intentionally behavior-first:
-
-- start from real agent loops, traces, approvals, and recovery behavior
-- keep the current surface small until abstractions are justified by actual usage
-- stay usable as a coding agent while growing toward a more general agent runtime
-- support richer workspace tasks, not just code editing, whenever the environment already provides the right tools
-
-More project context:
-
-- [Framework Vision](/Users/roackb2/Studio/projects/ProjectHeddle/heddle/docs/framework-vision.md)
-- [Project Purpose](/Users/roackb2/Studio/projects/ProjectHeddle/heddle/docs/project-purpose.md)
-- [Coding Agent Roadmap](/Users/roackb2/Studio/projects/ProjectHeddle/heddle/docs/coding-agent-roadmap.md)
+See [Development and contributing](docs/guides/development.md) for the fuller contributor workflow.
 
 ## License
 

package/dist/src/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE5D,YAAY,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oDAAoD,CAAC;AAE5F,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB1F;AAED,eAAO,MAAM,kBAAkB,2BAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE5D,YAAY,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oDAAoD,CAAC;AAE5F,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB1F;AAED,eAAO,MAAM,kBAAkB,2BAAqB,CAAC"}

package/dist/src/server/index.js

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHeddleServerApp } from './app.js';
@@ -38,6 +39,17 @@ function resolveDefaultAssetsDir() {
         return resolve(process.env.HEDDLE_WEB_DIST);
     }
     const moduleDir = dirname(fileURLToPath(import.meta.url));
-    return resolve(moduleDir, '../web');
+    const candidates = [
+        resolve(moduleDir, '../web'),
+        resolve(moduleDir, '../../web'),
+        resolve(moduleDir, '../../../src/web'),
+    ];
+    for (const candidate of candidates) {
+        const indexPath = resolve(candidate, 'index.html');
+        if (existsSync(indexPath)) {
+            return candidate;
+        }
+    }
+    return candidates[0];
 }
 //# sourceMappingURL=index.js.map

package/dist/src/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAInD,OAAO,EAAE,SAAS,EAAkB,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oDAAoD,CAAC;AAE5F,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAkC;IACzE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,uBAAuB,EAAE,CAAC;IACjE,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,kBAAkB,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IACtF,MAAM,GAAG,GAAG,qBAAqB,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IAErE,MAAM,IAAI,OAAO,CAAO,CAAC,aAAa,EAAE,YAAY,EAAE,EAAE;QACtD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE;YACzD,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,SAAS;aACV,EAAE,uBAAuB,CAAC,CAAC;YAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;YAC5F,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,OAAO,CAAC,aAAa,IAAI,CAAC,CAAC;YAC7D,aAAa,EAAE,CAAC;QAClB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC7B,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,sBAAsB,CAAC,CAAC;YAChD,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;AAErD,SAAS,uBAAuB;IAC9B,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,OAAO,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roackb2/heddle",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "An open-source terminal coding agent runtime and CLI with OpenAI and Anthropic support",
   "author": "Jay / Fienna Liang <roackb2@gmail.com>",
   "license": "MIT",