@sunshinelife83/hearth 1.0.0

package/docs/agent-profile-schema.md

@@ -0,0 +1,203 @@
+# Subagent profile schema
+
+Hearth agent profiles are user-owned markdown files with YAML
+frontmatter. They describe roles such as reviewer, explorer, or implementer.
+The internal on-demand `hearth-agentd` process owns provider invocation. The
+CLI and MCP server use it as clients when they need agent execution.
+
+When subagents are enabled, the internal `hearth-agentd` process owns the
+durable agent manager and live provider runtimes. `hearth agents run` is a
+thin local client that starts or reuses the daemon automatically; `hearth
+serve` is not required. A run returns an agent id immediately, while the daemon
+persists its status, latest response, and provider session id.
+
+Profiles are discovered from:
+
+- `~/.hearth/agents/*.md`
+- `.hearth/agents/*.md`
+
+Packaged files under `examples/agents/` are starter templates only.
+
+## Minimal shape
+
+```md
+---
+schema: hearth-agent/v1
+name: reviewer
+description: Read-only reviewer for bugs, security risks, and missing tests.
+provider: codex
+model: gpt-5.4
+effort: high
+disabled: false
+---
+
+You are a read-only reviewer. Do not edit files.
+Focus on correctness, security, test gaps, and maintainability.
+Cite files and return concise findings.
+```
+
+## Frontmatter fields
+
+### `schema`
+
+Optional schema identifier:
+
+```yaml
+schema: hearth-agent/v1
+```
+
+### `name`
+
+Stable profile identifier shown to the model and accepted by:
+
+```bash
+hearth agents run <name> "<prompt>"
+```
+
+Use lowercase kebab-case names. If omitted, Hearth uses the filename without
+`.md`.
+
+### `description`
+
+Required short purpose. This is exposed by `open_workspace` so the supervising
+model can choose the right profile.
+
+### `provider`
+
+Required built-in provider id:
+
+```yaml
+provider: codex
+provider: claude
+provider: opencode
+provider: pi
+provider: cursor
+provider: copilot
+provider: grok
+```
+
+Unsupported or custom providers are rejected. Hearth maps providers to their
+native integration:
+
+- `codex`: the host-installed `codex app-server` command
+- `claude`: Claude Code SDK
+- `opencode`: OpenCode SDK
+- `pi`: the installed Pi coding-agent SDK, one in-process session per Hearth agent
+- `cursor`: ACP
+- `copilot`: ACP
+- `grok`: Grok Build ACP (`grok agent stdio`)
+
+Codex is resolved from the user's environment rather than bundled with
+Hearth. Run `codex login` normally before using it; set `CODEX_COMMAND` when
+the executable is not on the normal PATH. OpenCode, Cursor, and Copilot
+runtimes are started and reused by the daemon internally, while Pi is embedded
+through its Node SDK.
+
+### `model`
+
+Optional provider model id or alias.
+
+```yaml
+model: gpt-5.4
+model: sonnet
+```
+
+### `effort`
+
+Optional provider reasoning effort, thinking level, or model variant. If omitted,
+Hearth lets the provider default apply. Values are provider-specific
+passthrough strings; Hearth does not translate names between harnesses.
+
+```yaml
+effort: low
+effort: high
+effort: xhigh
+```
+
+Hearth passes this through to providers that expose a matching control:
+
+- `claude`: SDK effort with adaptive thinking.
+- `codex`: app-server model reasoning effort.
+- `pi`: the AgentSession thinking-level control.
+- `opencode`: model variant.
+- `cursor` and `copilot`: ACP thought-level config when supported.
+- `grok`: `--reasoning-effort` on startup and xAI's ACP model metadata for resumed sessions.
+
+### `disabled`
+
+Optional boolean. Disabled profiles are not exposed.
+
+```yaml
+disabled: true
+```
+
+## Markdown body
+
+The body is the profile prompt prefix Hearth prepends when launching that
+profile. It is not included in `open_workspace` by default.
+
+Recommended body content:
+
+- When to use this profile.
+- Whether the worker should act read-only or may make changes.
+- Output format.
+- Review or testing expectations.
+
+## Model-facing workflow
+
+The Subagent skill teaches only:
+
+```bash
+hearth agents ls --json
+hearth agents targets --json
+hearth agents run <profile-or-provider> "<prompt>" --json
+hearth agents continue <id> "<prompt>" --json
+hearth agents show <id> --json
+```
+
+`open_workspace` exposes compact profile metadata:
+
+```json
+{
+  "name": "reviewer",
+  "description": "Read-only reviewer for bugs, security risks, and missing tests.",
+  "provider": "codex",
+  "model": "gpt-5.4",
+  "effort": "high"
+}
+```
+
+`hearth agents targets` lists usable providers and profile definitions for the
+current workspace. `hearth agents ls` lists existing subagent sessions; it does
+not list profile definitions.
+
+Use `hearth agents continue <id>` for a later turn. The logical agent ID is
+the `agt_...` value returned by `run` or `ls`; provider session IDs are not
+accepted as substitutes.
+
+The full profile body stays out of the model context until Hearth launches the
+profile.
+
+## Runtime lifecycle
+
+Hearth keeps provider sessions warm while they are active or recently used,
+but persists only the provider session id and durable agent metadata. Native
+sharing follows the provider boundary: Codex uses one app-server across agents,
+OpenCode uses one server across sessions, ACP providers use one process across
+sessions, while Claude and Pi keep one warm runtime per Hearth agent. There is
+one active turn per agent; different agents may run concurrently.
+
+If the daemon restarts during a turn, persisted `starting` and `running` agents
+become `error` with a restart message. The next `agents continue <id>` request can
+continue the provider session when that provider supports resumption. The MCP
+server can restart independently because it does not own this state.
+
+## Current non-goals
+
+- Custom or arbitrary CLI-backed agents.
+- Inferring changed files, tests, or diffs from worker output.
+- Exposing raw provider transcripts by default.
+- Teaching the model provider-specific CLIs.
+- First-class MCP agent tools. Future tools should call the same local agent
+  daemon used by `hearth agents` rather than executing providers in the MCP
+  server process.

package/docs/artifact-exchange.md

@@ -0,0 +1,44 @@
+# Download a native file
+
+Hearth can save a file attached or generated by an MCP host, such as ChatGPT,
+directly into an open workspace. Enable the tool with
+`artifacts.enabled` in `~/.hearth/config.jsonc`.
+
+## Workflow
+
+```text
+open_workspace
+  -> download_artifact({ file, workspaceId, path })
+  -> { path }
+```
+
+1. Open the project with `open_workspace`.
+2. Pass the host-provided native `file`, the returned `workspaceId`, and an
+   unused workspace-relative `path` to `download_artifact`.
+3. Use the returned path with the ordinary Hearth filesystem tools.
+
+```text
+download_artifact({
+  file: <native file value supplied by the MCP host>,
+  workspaceId: "ws_123",
+  path: "public/images/generated-image.png"
+})
+```
+
+Hearth creates missing parent directories and refuses to overwrite an existing
+file. After the download, normal tools can inspect, move, rename, replace, or
+delete it.
+
+## Safety and limits
+
+The `file` input must be the native value supplied by the MCP host. Hearth does
+not accept pasted download URLs or local source paths. It validates the complete
+file-object shape, trusted OpenAI download hosts, and redirects before streaming.
+Malformed references, unknown fields, absolute paths, traversal, and symlinked
+parents are rejected.
+
+Downloads are streamed under `artifacts.maxFileBytes` and published as
+owner-only files without overwriting an existing destination. The tool is
+currently available on Linux. It is not registered on macOS, Windows, or BSD
+because Node.js does not expose the required descriptor-relative filesystem
+operations there.

package/docs/chatgpt-coding-workflow.md

@@ -0,0 +1,215 @@
+# ChatGPT Coding Workflow
+
+Hearth brings a Codex-style coding-agent loop to ChatGPT and other MCP hosts:
+inspect the repo, follow local instructions, make scoped edits, run
+verification, and show the user what changed.
+
+## Open One Workspace
+
+ChatGPT should call `open_workspace` once for a project folder:
+
+```json
+{
+  "path": "~/work/my-project"
+}
+```
+
+The result includes a `workspaceId`. All later file, search, edit, show-changes,
+and shell calls should reuse that same `workspaceId`.
+
+ChatGPT may support automatic checkout recovery through optional host
+conversation metadata. This is an OpenAI-host adapter detail, not a standard MCP
+conversation field. When that optional context is available, opening the same
+checkout project again in the same conversation can continue in the existing
+workspace, and the context already provided for that reused checkout is not
+repeated. The portable workflow remains the same: keep using the `workspaceId`
+returned by `open_workspace` for later operations. Hosts without supported
+conversation context receive a normal new workspace and continue with that
+explicit `workspaceId` workflow.
+The model receives actionable workspace instructions; automatic-reuse
+bookkeeping is not a model-facing choice.
+
+Worktree mode is deliberately different: every call creates a new managed
+worktree and a new workspace session with complete context, even for the same
+path and base ref.
+
+The first successful open of a checkout provides complete instructions and
+coding context. A repeated open that reuses the same checkout workspace does
+not repeat the model-visible context, but the workspace UI continues to show the
+complete details. Every new worktree establishes and returns its own complete
+context, even when the same project was already opened in checkout or another
+worktree. Opening checkout after a worktree therefore provides the checkout's
+own context.
+
+Do not call `open_workspace` again for the same checkout folder unless:
+
+- the `workspaceId` is rejected as unknown
+- work moves to a different project folder
+- work switches between checkout and worktree mode
+- the user asks for a new isolated worktree
+
+## Checkout Mode
+
+Checkout mode is the default. Hearth opens the actual directory:
+
+```json
+{
+  "path": "~/work/my-project"
+}
+```
+
+Use this when the user wants ChatGPT to work in the current checkout.
+
+## Worktree Mode
+
+Use worktree mode for isolated parallel work:
+
+```json
+{
+  "path": "~/work/my-project",
+  "mode": "worktree"
+}
+```
+
+Managed worktrees are created under:
+
+```text
+~/.hearth/worktrees
+```
+
+Worktree mode requires a Git repository with at least one commit. It starts from
+`HEAD` unless `baseRef` is provided.
+
+Each worktree-mode call creates a new managed worktree and returns a new
+`workspaceId`. Reuse that ID for work inside that worktree; call
+`open_workspace` in worktree mode again only when another isolated worktree is
+actually required.
+
+Uncommitted source checkout changes are not copied into the managed worktree.
+Hearth reports when the source checkout was dirty so the model can decide how
+to proceed with the user.
+
+## Project Instructions
+
+When a workspace opens, Hearth loads root-level instruction files:
+
+- `AGENTS.md`
+- `AGENTS.MD`
+- `CLAUDE.md`
+- `CLAUDE.MD`
+
+Nested instruction files are returned as `availableAgentsFiles`. The model
+should read the relevant nested file before working under that directory.
+
+This keeps instructions explicit and inspectable instead of silently injecting
+new context during later tool calls.
+
+## Skills
+
+Skills are enabled by default for coding-agent workflows.
+
+Hearth discovers standard Agent Skills from:
+
+- `~/.agents/skills`
+- project `.agents/skills`
+- `~/.hearth/skills`
+
+It also keeps compatibility with:
+
+- the bundled `subagents` skill when Subagents are enabled, unless `~/.hearth/skills/subagents/SKILL.md` exists
+- `skills.agentDir/skills`, defaulting to `~/.codex/skills`
+- additional paths from `skills.paths`
+
+When Subagents are enabled, Hearth discovers agent profiles
+from `~/.hearth/agents/*.md` and project `.hearth/agents/*.md`.
+`open_workspace` exposes a compact catalog with profile names, descriptions,
+providers, and optional models/effort levels so the model can choose a configured agent
+without seeing provider-specific launch details.
+
+Example profiles are packaged under `examples/agents/` for users who want
+starter templates. Copy or adapt them into one of the active profile directories
+before use.
+
+Legacy project paths such as `.pi/skills` can be added to `skills.paths` when needed.
+
+When `open_workspace` returns matching skills, the model should read the
+advertised `SKILL.md` before following that skill.
+
+Skill paths may be outside the workspace. Hearth only permits reading:
+
+- files within advertised skill directories
+
+Set `skills.enabled` to `false` to hide skills from workspace output. Enable
+Subagents and choose providers through `hearth init` or the persisted provider
+configuration. The bundled `subagents` skill teaches the minimal
+`hearth agents targets`, `hearth agents ls`, `hearth agents run`,
+`hearth agents continue`, and `hearth agents show` workflow. The catalog
+comes from `open_workspace`; `hearth agents ls` lists existing subagent
+sessions for that workspace.
+
+## Tool Names
+
+The Claude surface exposes these tool names:
+
+- `open_workspace`
+- `read`
+- `write`
+- `edit`
+- `bash`
+- `show_changes`
+
+Hearth uses the Codex-style surface by default. It exposes:
+
+- `open_workspace`
+- `read`
+- `apply_patch`
+- `exec_command`
+- `write_stdin`
+- `show_changes`
+
+In this mode, `write`, `edit`, and `bash` are not registered. `exec_command`
+returns a process session ID when a command is still
+running after its yield window. Use `write_stdin` to poll it, send input, resize
+a PTY, or send Ctrl-C. Set `tty: true` only for commands that need a terminal.
+
+Set `tools.mode` to `claude` in `~/.hearth/config.jsonc` to expose `write`,
+`edit`, and `bash` instead of the Codex mutation and command tools. Dedicated
+MCP tools for `grep`, `glob`, and `ls` are not registered in either mode; use
+the configured shell tool with command-line tools such as `rg`, `find`, and
+`ls`.
+
+## Show Changes
+
+Hearth exposes `show_changes` in both tool modes and attaches widget UI only
+to `open_workspace` and `show_changes`. Reads, edits, and commands return normal
+MCP results without creating an iframe for each call. Set `ui.enabled` to
+`false` in `~/.hearth/config.jsonc` to disable UI metadata while keeping the
+aggregate review tool available.
+
+Call `show_changes` exactly once after the final file modification in any turn
+that changes files. It shows the combined changes for that turn and advances
+the review point automatically. Reusing a workspace does not change this
+workflow.
+
+The model-facing result stays compact: Hearth returns the workspace ID, a
+Git-backed `reviewRef`, and the summary text. MCP Apps hosts receive the full
+file list and patch in result metadata for immediate rendering. If a host later
+restores only the structured result, the review card can reopen that exact
+`reviewRef` from Hearth's Git review history without advancing the current
+review point.
+
+For local inspection, run `hearth show-changes <review-ref>`. Add `--json` to
+include the parsed summary, file list, and patch.
+
+## Shell Use
+
+The shell tool is for commands that belong in a terminal:
+
+- tests
+- builds
+- git inspection
+- package scripts
+- environment checks
+
+File writes should go through the edit/write tools rather than shell
+redirection, heredocs, `tee`, `sed -i`, or generated scripts.

package/docs/configuration.md

@@ -0,0 +1,217 @@
+# Configuration Reference
+
+Hearth stores durable settings in `~/.hearth/config.jsonc`. The file accepts
+comments and trailing commas and is validated before the server starts. Editor
+completion is provided by the versioned [JSON Schema](../schema/v1/hearth.schema.json),
+also hosted at the URL in the file's `$schema` property.
+
+Authentication stays separate because it contains a secret:
+
+```text
+~/.hearth/config.jsonc
+~/.hearth/auth.json
+```
+
+Run `hearth init` to create both files. `hearth config set publicBaseUrl
+<url|null>` updates the JSONC document without discarding its comments.
+
+## Complete example
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/Waishnav/hearth/main/schema/v1/hearth.schema.json",
+  "configVersion": 1,
+
+  "server": {
+    "host": "127.0.0.1",
+    "port": 7176,
+    // Use the public origin only; do not append /mcp.
+    "publicBaseUrl": "https://hearth.example.com",
+    "allowedHosts": [],
+    "trustProxy": false,
+  },
+  "workspaces": {
+    "allowedRoots": ["~/personal", "~/work"],
+    "worktreeRoot": "~/.hearth/worktrees",
+  },
+  "storage": {
+    "stateDir": "~/.local/share/hearth",
+  },
+  "tools": {
+    "mode": "codex",
+  },
+  "ui": {
+    "enabled": true,
+  },
+  "artifacts": {
+    "enabled": false,
+    "maxFileBytes": 104857600,
+  },
+  "skills": {
+    "enabled": true,
+    "paths": [],
+    "agentDir": "~/.codex",
+  },
+  "subagents": {
+    "enabled": false,
+    "providers": [],
+  },
+  "logging": {
+    "level": "info",
+    "format": "json",
+    "requests": true,
+    "assets": false,
+    "toolCalls": true,
+    "shellCommands": false,
+  },
+  "oauth": {
+    "accessTokenTtlSeconds": 3600,
+    "refreshTokenTtlSeconds": 2592000,
+    "scopes": ["hearth"],
+    "allowedRedirectHosts": ["chatgpt.com", "claude.ai", "anthropic.com", "localhost", "127.0.0.1"],
+  },
+}
+```
+
+Omitted sections and keys use the defaults shown above. An empty
+`workspaces.allowedRoots` uses the current working directory. Unknown keys are
+rejected so spelling mistakes cannot silently alter behavior.
+
+## Tool modes and UI
+
+`tools.mode` accepts two values:
+
+| Value | Tool surface |
+| --- | --- |
+| `codex` | Default. `open_workspace`, `read`, `apply_patch`, `exec_command`, `write_stdin`, and `show_changes`. |
+| `claude` | `open_workspace`, `read`, `write`, `edit`, `bash`, and `show_changes`. |
+
+The dedicated MCP tools `grep`, `glob`, and `ls` are not exposed. Each mode uses
+its shell tool with programs such as `rg`, `find`, and `ls` when it needs those
+operations.
+
+Hearth attaches Apps UI metadata only to `open_workspace` and `show_changes`.
+This avoids rendering an iframe for every read, edit, search, or command call.
+Setting `ui.enabled` to `false` removes the metadata but does not remove the
+`show_changes` tool.
+
+## Skills and subagents
+
+Hearth discovers standard Agent Skills from `~/.agents/skills`, project
+`.agents/skills`, and `~/.hearth/skills`. It also checks
+`skills.agentDir/skills` and each path in `skills.paths`. Relative custom paths
+are resolved from the active workspace.
+
+Subagent providers are explicit. Omitted providers are disabled:
+
+```jsonc
+{
+  "configVersion": 1,
+  "subagents": {
+    "enabled": true,
+    "providers": [
+      {
+        "id": "codex",
+        "enabled": true,
+        "model": "gpt-5.4",
+        "effort": "high",
+      },
+      {
+        "id": "claude",
+        "enabled": true,
+        "model": "sonnet",
+      },
+    ],
+  },
+}
+```
+
+Profiles are loaded from `~/.hearth/agents/*.md` and project
+`.hearth/agents/*.md`. `hearth agents targets` prints the configured targets
+available in the current workspace.
+
+Provider executable discovery remains process-scoped. The supported overrides
+are `CODEX_COMMAND`, `CODEX_HOME`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`,
+`COPILOT_COMMAND`, `GROK_COMMAND`, and `GROK_AGENT_PROFILE`. Hearth does not
+persist provider credentials.
+
+## Native artifact download
+
+Set `artifacts.enabled` to `true` when a host needs to save a native attached or
+generated file into an open workspace. `artifacts.maxFileBytes` limits one
+streamed file. The secure publication path is currently available only on
+Linux; the tool is not registered on macOS, Windows, or BSD.
+
+## Environment boundary
+
+User-facing Hearth environment variables (the only ones read from the environment; provider-specific overrides such as `CODEX_COMMAND`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`, `COPILOT_COMMAND`, `GROK_COMMAND`, `GROK_AGENT_PROFILE`, `CODEX_HOME` are read by the subagent layer):
+
+| Variable | Purpose |
+| --- | --- |
+| `HEARTH_CONFIG_DIR` | Bootstrap location for `config.jsonc`, `auth.json`, skills, and profiles. |
+| `HEARTH_OAUTH_OWNER_TOKEN` | Optional secret override for the owner token stored in `auth.json`. |
+
+Durable environment settings were removed in v1.1. Move existing deployment
+values to these JSONC keys:
+
+| Removed setting | JSONC key |
+| --- | --- |
+| `HOST`, `PORT` | `server.host`, `server.port` |
+| `HEARTH_PUBLIC_BASE_URL` | `server.publicBaseUrl` |
+| `HEARTH_ALLOWED_HOSTS` | `server.allowedHosts` |
+| `HEARTH_TRUST_PROXY` | `server.trustProxy` |
+| `HEARTH_ALLOWED_ROOTS` | `workspaces.allowedRoots` |
+| `HEARTH_WORKTREE_ROOT` | `workspaces.worktreeRoot` |
+| `HEARTH_STATE_DIR` | `storage.stateDir` |
+| `HEARTH_TOOL_MODE`, `HEARTH_MINIMAL_TOOLS` | `tools.mode` |
+| `HEARTH_WIDGETS` | `ui.enabled` |
+| `HEARTH_ARTIFACTS` | `artifacts.enabled` |
+| `HEARTH_ARTIFACT_MAX_FILE_BYTES` | `artifacts.maxFileBytes` |
+| `HEARTH_SKILLS` | `skills.enabled` |
+| `HEARTH_SKILL_PATHS` | `skills.paths` |
+| `HEARTH_AGENT_DIR` | `skills.agentDir` |
+| `HEARTH_SUBAGENTS` | `subagents.enabled` |
+| `HEARTH_LOG_LEVEL` | `logging.level` |
+| `HEARTH_LOG_FORMAT` | `logging.format` |
+| `HEARTH_LOG_REQUESTS` | `logging.requests` |
+| `HEARTH_LOG_ASSETS` | `logging.assets` |
+| `HEARTH_LOG_TOOL_CALLS` | `logging.toolCalls` |
+| `HEARTH_LOG_SHELL_COMMANDS` | `logging.shellCommands` |
+| `HEARTH_OAUTH_ACCESS_TOKEN_TTL_SECONDS` | `oauth.accessTokenTtlSeconds` |
+| `HEARTH_OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `oauth.refreshTokenTtlSeconds` |
+| `HEARTH_OAUTH_SCOPES` | `oauth.scopes` |
+| `HEARTH_OAUTH_ALLOWED_REDIRECT_HOSTS` | `oauth.allowedRedirectHosts` |
+
+These environment values are not read or auto-imported in v1.1. Environment is
+process state, so there is no reliable file Hearth can migrate on the user's
+behalf.
+
+## v1.0 file migration
+
+The first v1.1 load performs one migration when `config.jsonc` is missing and
+`config.json` exists:
+
+1. Validate the old JSON document.
+2. Translate its known fields into the versioned JSONC structure.
+3. Write and validate a temporary `config.jsonc`.
+4. Atomically publish it.
+5. Rename the old file to `config.json.v1.0.bak`.
+
+If `config.jsonc` exists, Hearth never reads `config.json`. Invalid JSONC also
+never falls back to the old file. Unsupported legacy keys stop migration with an
+actionable error instead of being silently discarded.
+
+The persisted fields map as follows:
+
+| v1.0 JSON field | v1.1 JSONC key |
+| --- | --- |
+| `host`, `port` | `server.host`, `server.port` |
+| `publicBaseUrl`, `allowedHosts` | `server.publicBaseUrl`, `server.allowedHosts` |
+| `allowedRoots`, `worktreeRoot` | `workspaces.allowedRoots`, `workspaces.worktreeRoot` |
+| `stateDir` | `storage.stateDir` |
+| `artifactsEnabled`, `artifactMaxFileBytes` | `artifacts.enabled`, `artifacts.maxFileBytes` |
+| `agentDir` | `skills.agentDir` |
+| `subagents` | `subagents` |
+| `tools.mode`, `ui.enabled` | unchanged nested keys |
+
+`auth.json` is unchanged.