@roackb2/heddle 0.0.13 → 0.0.14

package/README.md

@@ -10,6 +10,19 @@ Heddle is designed to make live agent runs more observable, not just easier to l
 
 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
@@ -24,6 +37,7 @@ If you are interested in the underlying methodology, Heddle's drift telemetry is
 - 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
+- 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`
@@ -70,7 +84,9 @@ If you are developing inside the Heddle repo itself, `yarn install` also install
 
 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`.
 
-## Quick Start
+## Chat And CLI Usage
+
+### Quick Start
 
 1. Set an API key for a supported provider.
 
@@ -96,34 +112,165 @@ Heddle uses the current directory as the workspace root unless you pass `--cwd`.
 
 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.
 
-## Core Capabilities
+### Chat Workflow
 
-Heddle currently supports:
+Start chat in the current repo:
 
-- 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`
-- inline `@file` mentions for file-priority context without pasting file contents into the prompt
-- 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
+```bash
+heddle
+heddle chat
+heddle --cwd /path/to/project
+heddle chat --model gpt-5.4-mini --max-steps 20
+```
 
-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.
+Typical chat use cases:
 
-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.
+- 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
 
-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.
+Useful chat commands:
 
-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.
+- `/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:
+
+```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:
+
+- `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
+
+Common flags:
+
+- `--cwd <path>`: run against another workspace root
+- `--model <name>`: choose the active model
+- `--max-steps <n>`: limit the agent loop length
+
+## Control Plane
+
+Heddle includes an early local browser control plane for users who want a native UI instead of only terminal chat or third-party messaging apps.
+
+This is still WIP. The current version is useful for read-only oversight, but it is not yet a full replacement for the TUI.
+
+Current stack:
+
+- `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
+
+Start the daemon from a workspace:
+
+```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 first implementation surfaces:
+
+- workspace and `.heddle/` state location
+- saved chat session inventory
+- heartbeat task status
+- recent heartbeat run summaries and usage
+
+You can override host and port:
+
+```bash
+heddle daemon --host 127.0.0.1 --port 8765
+```
+
+For local development, run the server and client separately:
+
+```bash
+yarn server:dev
+yarn client:dev
+```
+
+`yarn server:dev` starts the tRPC server at `127.0.0.1:8765`. `yarn client:dev` starts the Vite client and proxies `/trpc` to the server.
+
+The server writes pino logs to `.heddle/logs/server.log` by default. Override the path with:
+
+```bash
+HEDDLE_SERVER_LOG_FILE=/path/to/server.log yarn server:dev
+```
+
+This control plane is intentionally read-only at first. The next milestones are session detail views, chat continuation from the browser, heartbeat task actions, and live run updates.
+
+## 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
+
+The memory model is intentionally simple:
+
+- 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
+
+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
 
@@ -257,200 +404,6 @@ const runs = await listHeartbeatRunViews(store, { taskId: 'repo-gardener', limit
 
 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.
 
-## 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
-
-The memory model is intentionally simple:
-
-- 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
-
-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.
-
-## 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
-```
-
-Current focus:
-
-- 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
-
-## Chat Workflow
-
-Start chat in the current repo:
-
-```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:
-
-```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 Usage
-
-Supported commands:
-
-- `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
-
-Common flags:
-
-- `--cwd <path>`: run against another workspace root
-- `--model <name>`: choose the active model
-- `--max-steps <n>`: limit the agent loop length
-
-## Supported Providers And Models
-
-Heddle currently has working adapters for:
-
-- OpenAI
-- Anthropic
-
-Environment variables:
-
-- `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`
-
-Default models:
-
-- OpenAI: `gpt-5.1-codex`
-- Anthropic: `claude-sonnet-4-6`
-
-Built-in model shortlist exposed by the CLI UI:
-
-- 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`
-
-Notes:
-
-- 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
-
-## Project Config
-
-You can store project defaults in `heddle.config.json`:
-
-```json
-{
-  "model": "gpt-5.1-codex",
-  "maxSteps": 40,
-  "stateDir": ".heddle",
-  "directShellApproval": "never",
-  "searchIgnoreDirs": [".git", "dist", "node_modules", ".heddle"],
-  "agentContextPaths": ["AGENTS.md"]
-}
-```
-
-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
-
 ## Programmatic Use
 
 The npm package exports a programmatic execution loop for building other agent hosts on top of Heddle.
@@ -623,6 +576,119 @@ yarn example:cyberloop-observer
 
 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
+- 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
+
+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
+```
+
+Current focus:
+
+- 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
+
+## Supported Providers And Models
+
+Heddle currently has working adapters for:
+
+- OpenAI
+- Anthropic
+
+Environment variables:
+
+- `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`
+
+Default models:
+
+- OpenAI: `gpt-5.1-codex`
+- Anthropic: `claude-sonnet-4-6`
+
+Built-in model shortlist exposed by the CLI UI:
+
+- 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`
+
+Notes:
+
+- 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
+
+## Project Config
+
+You can store project defaults in `heddle.config.json`:
+
+```json
+{
+  "model": "gpt-5.1-codex",
+  "maxSteps": 40,
+  "stateDir": ".heddle",
+  "directShellApproval": "never",
+  "searchIgnoreDirs": [".git", "dist", "node_modules", ".heddle"],
+  "agentContextPaths": ["AGENTS.md"]
+}
+```
+
+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.

package/dist/src/cli/daemon.d.ts

@@ -0,0 +1,14 @@
+import { projectChatSessionView } from '../server/index.js';
+export type DaemonCliOptions = {
+    workspaceRoot?: string;
+    stateDir?: string;
+};
+export type DaemonArgs = {
+    host: string;
+    port: number;
+    assetsDir?: string;
+};
+export { projectChatSessionView };
+export declare function runDaemonCli(args: string[], options?: DaemonCliOptions): Promise<void>;
+export declare function parseDaemonArgs(args: string[]): DaemonArgs;
+//# sourceMappingURL=daemon.d.ts.map

package/dist/src/cli/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../../src/cli/daemon.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAG5B,MAAM,MAAM,gBAAgB,GAAG;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAKF,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,gBAAqB,iBAahF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAO1D"}

package/dist/src/cli/daemon.js

@@ -0,0 +1,61 @@
+import { resolve } from 'node:path';
+import { listenHeddleServer, projectChatSessionView, } from '../server/index.js';
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 8765;
+export { projectChatSessionView };
+export async function runDaemonCli(args, options = {}) {
+    const parsed = parseDaemonArgs(args);
+    const workspaceRoot = options.workspaceRoot ?? process.cwd();
+    const stateDir = options.stateDir ?? '.heddle';
+    const listenOptions = {
+        workspaceRoot,
+        stateRoot: resolve(workspaceRoot, stateDir),
+        host: parsed.host,
+        port: parsed.port,
+        assetsDir: parsed.assetsDir,
+    };
+    await listenHeddleServer(listenOptions);
+}
+export function parseDaemonArgs(args) {
+    const flags = parseFlags(args);
+    return {
+        host: stringFlag(flags, 'host') ?? DEFAULT_HOST,
+        port: parsePort(stringFlag(flags, 'port')) ?? DEFAULT_PORT,
+        assetsDir: stringFlag(flags, 'assets-dir'),
+    };
+}
+function parseFlags(args) {
+    const flags = {};
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index] ?? '';
+        if (!arg.startsWith('--')) {
+            continue;
+        }
+        const eqIndex = arg.indexOf('=');
+        if (eqIndex > 0) {
+            flags[arg.slice(2, eqIndex)] = arg.slice(eqIndex + 1);
+            continue;
+        }
+        const name = arg.slice(2);
+        const next = args[index + 1];
+        if (!next || next.startsWith('--')) {
+            flags[name] = true;
+            continue;
+        }
+        flags[name] = next;
+        index++;
+    }
+    return flags;
+}
+function stringFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === 'string' ? value : undefined;
+}
+function parsePort(raw) {
+    if (!raw) {
+        return undefined;
+    }
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value > 0 && value <= 65_535 ? value : undefined;
+}
+//# sourceMappingURL=daemon.js.map

package/dist/src/cli/daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.js","sourceRoot":"","sources":["../../../src/cli/daemon.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/main.js

@@ -5,6 +5,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { startChatCli } from './chat/index.js';
 import { runAskCli } from './ask.js';
 import { runHeartbeatCli } from './heartbeat.js';
+import { runDaemonCli } from './daemon.js';
 async function main() {
     const parsed = parseCli(process.argv.slice(2));
     const workspaceRoot = resolve(parsed.flags.cwd ?? process.cwd());
@@ -35,6 +36,10 @@ async function main() {
         await runHeartbeatCli(parsed.rest, resolved);
         return;
     }
+    if (parsed.command === 'daemon') {
+        await runDaemonCli(parsed.rest, resolved);
+        return;
+    }
     if (parsed.command === '--help' || parsed.command === '-h' || parsed.command === 'help') {
         printHelp();
         return;
@@ -132,6 +137,7 @@ function printHelp() {
         '  heddle heartbeat run [--poll 60s]',
         '  heddle heartbeat runs list [--task <id>] [--limit 10]',
         '  heddle heartbeat runs show <run-id|latest> [--task <id>]',
+        '  heddle daemon [--host 127.0.0.1] [--port 8765]',
         '  heddle init [--cwd <path>]',
         '',
         'Project config:',