better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md

@@ -1,446 +0,0 @@
----
-title: "Honcho — Configure and troubleshoot Honcho memory for Hermes"
-sidebar_label: "Honcho"
-description: "Configure and troubleshoot Honcho memory for Hermes"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Honcho
-
-Configure and troubleshoot Honcho memory for Hermes.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/honcho` |
-| Path | `optional-skills/autonomous-ai-agents\honcho` |
-| Version | `2.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Honcho`, `Memory`, `Profiles`, `Observation`, `Dialectic`, `User-Modeling`, `Session-Summary` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Honcho Memory for Hermes
-
-Honcho provides AI-native cross-session user modeling. It learns who the user is across conversations and gives every Hermes profile its own peer identity while sharing a unified view of the user.
-
-## When to Use
-
-- Setting up Honcho (cloud or self-hosted)
-- Troubleshooting memory not working / peers not syncing
-- Creating multi-profile setups where each agent has its own Honcho peer
-- Tuning observation, recall, dialectic depth, or write frequency settings
-- Understanding what the 5 Honcho tools do and when to use them
-- Configuring context budgets and session summary injection
-
-## Setup
-
-### Cloud (app.honcho.dev)
-
-```bash
-hermes memory setup honcho
-# select "cloud", paste API key from https://app.honcho.dev
-```
-
-### Self-hosted
-
-```bash
-hermes memory setup honcho
-# select "local", enter base URL (e.g. http://localhost:8000)
-```
-
-See: https://docs.honcho.dev/v3/guides/integrations/hermes#running-honcho-locally-with-hermes
-
-### Verify
-
-```bash
-hermes honcho status    # shows resolved config, connection test, peer info
-```
-
-## Architecture
-
-### Base Context Injection
-
-When Honcho injects context into the system prompt (in `hybrid` or `context` recall modes), it assembles the base context block in this order:
-
-1. **Session summary** -- a short digest of the current session so far (placed first so the model has immediate conversational continuity)
-2. **User representation** -- Honcho's accumulated model of the user (preferences, facts, patterns)
-3. **AI peer card** -- the identity card for this Hermes profile's AI peer
-
-The session summary is generated automatically by Honcho at the start of each turn (when a prior session exists). It gives the model a warm start without replaying full history.
-
-### Cold / Warm Prompt Selection
-
-Honcho automatically selects between two prompt strategies:
-
-| Condition | Strategy | What happens |
-|-----------|----------|--------------|
-| No prior session or empty representation | **Cold start** | Lightweight intro prompt; skips summary injection; encourages the model to learn about the user |
-| Existing representation and/or session history | **Warm start** | Full base context injection (summary → representation → card); richer system prompt |
-
-You do not need to configure this -- it is automatic based on session state.
-
-### Peers
-
-Honcho models conversations as interactions between **peers**. Hermes creates two peers per session:
-
-- **User peer** (`peerName`): represents the human. Honcho builds a user representation from observed messages.
-- **AI peer** (`aiPeer`): represents this Hermes instance. Each profile gets its own AI peer so agents develop independent views.
-
-### Observation
-
-Each peer has two observation toggles that control what Honcho learns from:
-
-| Toggle | What it does |
-|--------|-------------|
-| `observeMe` | Peer's own messages are observed (builds self-representation) |
-| `observeOthers` | Other peers' messages are observed (builds cross-peer understanding) |
-
-Default: all four toggles **on** (full bidirectional observation).
-
-Configure per-peer in `honcho.json`:
-
-```json
-{
-  "observation": {
-    "user": { "observeMe": true, "observeOthers": true },
-    "ai":   { "observeMe": true, "observeOthers": true }
-  }
-}
-```
-
-Or use the shorthand presets:
-
-| Preset | User | AI | Use case |
-|--------|------|----|----------|
-| `"directional"` (default) | me:on, others:on | me:on, others:on | Multi-agent, full memory |
-| `"unified"` | me:on, others:off | me:off, others:on | Single agent, user-only modeling |
-
-Settings changed in the [Honcho dashboard](https://app.honcho.dev) are synced back on session init -- server-side config wins over local defaults.
-
-### Sessions
-
-Honcho sessions scope where messages and observations land. Strategy options:
-
-| Strategy | Behavior |
-|----------|----------|
-| `per-directory` (default) | One session per working directory |
-| `per-repo` | One session per git repository root |
-| `per-session` | New Honcho session each Hermes run |
-| `global` | Single session across all directories |
-
-Manual override: `hermes honcho map my-project-name`
-
-### Recall Modes
-
-How the agent accesses Honcho memory:
-
-| Mode | Auto-inject context? | Tools available? | Use case |
-|------|---------------------|-----------------|----------|
-| `hybrid` (default) | Yes | Yes | Agent decides when to use tools vs auto context |
-| `context` | Yes | No (hidden) | Minimal token cost, no tool calls |
-| `tools` | No | Yes | Agent controls all memory access explicitly |
-
-## Three Orthogonal Knobs
-
-Honcho's dialectic behavior is controlled by three independent dimensions. Each can be tuned without affecting the others:
-
-### Cadence (when)
-
-Controls **how often** dialectic and context calls happen.
-
-| Key | Default | Description |
-|-----|---------|-------------|
-| `contextCadence` | `1` | Min turns between context API calls |
-| `dialecticCadence` | `2` | Min turns between dialectic API calls. Recommended 1–5 |
-| `injectionFrequency` | `every-turn` | `every-turn` or `first-turn` for base context injection |
-
-Higher cadence values fire the dialectic LLM less often. `dialecticCadence: 2` means the engine fires every other turn. Setting it to `1` fires every turn.
-
-### Depth (how many)
-
-Controls **how many rounds** of dialectic reasoning Honcho performs per query.
-
-| Key | Default | Range | Description |
-|-----|---------|-------|-------------|
-| `dialecticDepth` | `1` | 1-3 | Number of dialectic reasoning rounds per query |
-| `dialecticDepthLevels` | -- | array | Optional per-depth-round level overrides (see below) |
-
-`dialecticDepth: 2` means Honcho runs two rounds of dialectic synthesis. The first round produces an initial answer; the second refines it.
-
-`dialecticDepthLevels` lets you set the reasoning level for each round independently:
-
-```json
-{
-  "dialecticDepth": 3,
-  "dialecticDepthLevels": ["low", "medium", "high"]
-}
-```
-
-If `dialecticDepthLevels` is omitted, rounds use **proportional levels** derived from `dialecticReasoningLevel` (the base):
-
-| Depth | Pass levels |
-|-------|-------------|
-| 1 | [base] |
-| 2 | [minimal, base] |
-| 3 | [minimal, base, low] |
-
-This keeps earlier passes cheap while using full depth on the final synthesis.
-
-**Depth at session start.** The session-start prewarm runs the full configured `dialecticDepth` in the background before turn 1. A single-pass prewarm on a cold peer often returns thin output — multi-pass depth runs the audit/reconcile cycle before the user ever speaks. Turn 1 consumes the prewarm result directly; if prewarm hasn't landed in time, turn 1 falls back to a synchronous call with a bounded timeout.
-
-### Level (how hard)
-
-Controls the **intensity** of each dialectic reasoning round.
-
-| Key | Default | Description |
-|-----|---------|-------------|
-| `dialecticReasoningLevel` | `low` | `minimal`, `low`, `medium`, `high`, `max` |
-| `dialecticDynamic` | `true` | When `true`, the model can pass `reasoning_level` to `honcho_reasoning` to override the default per-call. `false` = always use `dialecticReasoningLevel`, model overrides ignored |
-
-Higher levels produce richer synthesis but cost more tokens on Honcho's backend.
-
-## Multi-Profile Setup
-
-Each Hermes profile gets its own Honcho AI peer while sharing the same workspace (user context). This means:
-
-- All profiles see the same user representation
-- Each profile builds its own AI identity and observations
-- Conclusions written by one profile are visible to others via the shared workspace
-
-### Create a profile with Honcho peer
-
-```bash
-hermes profile create coder --clone
-# creates host block hermes.coder, AI peer "coder", inherits config from default
-```
-
-What `--clone` does for Honcho:
-1. Creates a `hermes.coder` host block in `honcho.json`
-2. Sets `aiPeer: "coder"` (the profile name)
-3. Inherits `workspace`, `peerName`, `writeFrequency`, `recallMode`, etc. from default
-4. Eagerly creates the peer in Honcho so it exists before first message
-
-### Backfill existing profiles
-
-```bash
-hermes honcho sync    # creates host blocks for all profiles that don't have one yet
-```
-
-### Per-profile config
-
-Override any setting in the host block:
-
-```json
-{
-  "hosts": {
-    "hermes.coder": {
-      "aiPeer": "coder",
-      "recallMode": "tools",
-      "dialecticDepth": 2,
-      "observation": {
-        "user": { "observeMe": true, "observeOthers": false },
-        "ai": { "observeMe": true, "observeOthers": true }
-      }
-    }
-  }
-}
-```
-
-## Tools
-
-The agent has 5 bidirectional Honcho tools (hidden in `context` recall mode):
-
-| Tool | LLM call? | Cost | Use when |
-|------|-----------|------|----------|
-| `honcho_profile` | No | minimal | Quick factual snapshot at conversation start or for fast name/role/pref lookups |
-| `honcho_search` | No | low | Fetch specific past facts to reason over yourself — raw excerpts, no synthesis |
-| `honcho_context` | No | low | Full session context snapshot: summary, representation, card, recent messages |
-| `honcho_reasoning` | Yes | medium–high | Natural language question synthesized by Honcho's dialectic engine |
-| `honcho_conclude` | No | minimal | Write or delete a persistent fact; pass `peer: "ai"` for AI self-knowledge |
-
-### `honcho_profile`
-Read or update a peer card — curated key facts (name, role, preferences, communication style). Pass `card: [...]` to update; omit to read. No LLM call.
-
-### `honcho_search`
-Semantic search over stored context for a specific peer. Returns raw excerpts ranked by relevance, no synthesis. Default 800 tokens, max 2000. Good when you need specific past facts to reason over yourself rather than a synthesized answer.
-
-### `honcho_context`
-Full session context snapshot from Honcho — session summary, peer representation, peer card, and recent messages. No LLM call. Use when you want to see everything Honcho knows about the current session and peer in one shot.
-
-### `honcho_reasoning`
-Natural language question answered by Honcho's dialectic reasoning engine (LLM call on Honcho's backend). Higher cost, higher quality. Pass `reasoning_level` to control depth: `minimal` (fast/cheap) → `low` → `medium` → `high` → `max` (thorough). Omit to use the configured default (`low`). Use for synthesized understanding of the user's patterns, goals, or current state.
-
-### `honcho_conclude`
-Write or delete a persistent conclusion about a peer. Pass `conclusion: "..."` to create. Pass `delete_id: "..."` to remove a conclusion (for PII removal — Honcho self-heals incorrect conclusions over time, so deletion is only needed for PII). You MUST pass exactly one of the two.
-
-### Bidirectional peer targeting
-
-All 5 tools accept an optional `peer` parameter:
-- `peer: "user"` (default) — operates on the user peer
-- `peer: "ai"` — operates on this profile's AI peer
-- `peer: "<explicit-id>"` — any peer ID in the workspace
-
-Examples:
-```
-honcho_profile                        # read user's card
-honcho_profile peer="ai"              # read AI peer's card
-honcho_reasoning query="What does this user care about most?"
-honcho_reasoning query="What are my interaction patterns?" peer="ai" reasoning_level="medium"
-honcho_conclude conclusion="Prefers terse answers"
-honcho_conclude conclusion="I tend to over-explain code" peer="ai"
-honcho_conclude delete_id="abc123"    # PII removal
-```
-
-## Agent Usage Patterns
-
-Guidelines for Hermes when Honcho memory is active.
-
-### On conversation start
-
-```
-1. honcho_profile                  → fast warmup, no LLM cost
-2. If context looks thin → honcho_context  (full snapshot, still no LLM)
-3. If deep synthesis needed → honcho_reasoning  (LLM call, use sparingly)
-```
-
-Do NOT call `honcho_reasoning` on every turn. Auto-injection already handles ongoing context refresh. Use the reasoning tool only when you genuinely need synthesized insight the base context doesn't provide.
-
-### When the user shares something to remember
-
-```
-honcho_conclude conclusion="<specific, actionable fact>"
-```
-
-Good conclusions: "Prefers code examples over prose explanations", "Working on a Rust async project through April 2026"
-Bad conclusions: "User said something about Rust" (too vague), "User seems technical" (already in representation)
-
-### When the user asks about past context / you need to recall specifics
-
-```
-honcho_search query="<topic>"       → fast, no LLM, good for specific facts
-honcho_context                       → full snapshot with summary + messages
-honcho_reasoning query="<question>"  → synthesized answer, use when search isn't enough
-```
-
-### When to use `peer: "ai"`
-
-Use AI peer targeting to build and query the agent's own self-knowledge:
-- `honcho_conclude conclusion="I tend to be verbose when explaining architecture" peer="ai"` — self-correction
-- `honcho_reasoning query="How do I typically handle ambiguous requests?" peer="ai"` — self-audit
-- `honcho_profile peer="ai"` — review own identity card
-
-### When NOT to call tools
-
-In `hybrid` and `context` modes, base context (user representation + card + session summary) is auto-injected before every turn. Do not re-fetch what was already injected. Call tools only when:
-- You need something the injected context doesn't have
-- The user explicitly asks you to recall or check memory
-- You're writing a conclusion about something new
-
-### Cadence awareness
-
-`honcho_reasoning` on the tool side shares the same cost as auto-injection dialectic. After an explicit tool call, the auto-injection cadence resets — avoiding double-charging the same turn.
-
-## Config Reference
-
-Config file: `$HERMES_HOME/honcho.json` (profile-local) or `~/.honcho/config.json` (global).
-
-### Key settings
-
-| Key | Default | Description |
-|-----|---------|-------------|
-| `apiKey` | -- | API key ([get one](https://app.honcho.dev)) |
-| `baseUrl` | -- | Base URL for self-hosted Honcho |
-| `peerName` | -- | User peer identity |
-| `aiPeer` | host key | AI peer identity |
-| `workspace` | host key | Shared workspace ID |
-| `recallMode` | `hybrid` | `hybrid`, `context`, or `tools` |
-| `observation` | all on | Per-peer `observeMe`/`observeOthers` booleans |
-| `writeFrequency` | `async` | `async`, `turn`, `session`, or integer N |
-| `sessionStrategy` | `per-directory` | `per-directory`, `per-repo`, `per-session`, `global` |
-| `messageMaxChars` | `25000` | Max chars per message (chunked if exceeded) |
-
-### Dialectic settings
-
-| Key | Default | Description |
-|-----|---------|-------------|
-| `dialecticReasoningLevel` | `low` | `minimal`, `low`, `medium`, `high`, `max` |
-| `dialecticDynamic` | `true` | Auto-bump reasoning by query complexity. `false` = fixed level |
-| `dialecticDepth` | `1` | Number of dialectic rounds per query (1-3) |
-| `dialecticDepthLevels` | -- | Optional array of per-round levels, e.g. `["low", "high"]` |
-| `dialecticMaxInputChars` | `10000` | Max chars for dialectic query input |
-
-### Context budget and injection
-
-| Key | Default | Description |
-|-----|---------|-------------|
-| `contextTokens` | uncapped | Max tokens for the combined base context injection (summary + representation + card). Opt-in cap — omit to leave uncapped, set to an integer to bound injection size. |
-| `injectionFrequency` | `every-turn` | `every-turn` or `first-turn` |
-| `contextCadence` | `1` | Min turns between context API calls |
-| `dialecticCadence` | `2` | Min turns between dialectic LLM calls (recommended 1–5) |
-
-The `contextTokens` budget is enforced at injection time. If the session summary + representation + card exceed the budget, Honcho trims the summary first, then the representation, preserving the card. This prevents context blowup in long sessions.
-
-### Memory-context sanitization
-
-Honcho sanitizes the `memory-context` block before injection to prevent prompt injection and malformed content:
-
-- Strips XML/HTML tags from user-authored conclusions
-- Normalizes whitespace and control characters
-- Truncates individual conclusions that exceed `messageMaxChars`
-- Escapes delimiter sequences that could break the system prompt structure
-
-This fix addresses edge cases where raw user conclusions containing markup or special characters could corrupt the injected context block.
-
-## Troubleshooting
-
-### "Honcho not configured"
-Run `hermes honcho setup`. Ensure `memory.provider: honcho` is in `~/.hermes/config.yaml`.
-
-### Memory not persisting across sessions
-Check `hermes honcho status` -- verify `saveMessages: true` and `writeFrequency` isn't `session` (which only writes on exit).
-
-### Profile not getting its own peer
-Use `--clone` when creating: `hermes profile create <name> --clone`. For existing profiles: `hermes honcho sync`.
-
-### Observation changes in dashboard not reflected
-Observation config is synced from the server on each session init. Start a new session after changing settings in the Honcho UI.
-
-### Messages truncated
-Messages over `messageMaxChars` (default 25k) are automatically chunked with `[continued]` markers. If you're hitting this often, check if tool results or skill content is inflating message size.
-
-### Context injection too large
-If you see warnings about context budget exceeded, lower `contextTokens` or reduce `dialecticDepth`. The session summary is trimmed first when the budget is tight.
-
-### Session summary missing
-Session summary requires at least one prior turn in the current Honcho session. On cold start (new session, no history), the summary is omitted and Honcho uses the cold-start prompt strategy instead.
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `hermes honcho setup` | Interactive setup wizard (cloud/local, identity, observation, recall, sessions) |
-| `hermes honcho status` | Show resolved config, connection test, peer info for active profile |
-| `hermes honcho enable` | Enable Honcho for the active profile (creates host block if needed) |
-| `hermes honcho disable` | Disable Honcho for the active profile |
-| `hermes honcho peer` | Show or update peer names (`--user <name>`, `--ai <name>`, `--reasoning <level>`) |
-| `hermes honcho peers` | Show peer identities across all profiles |
-| `hermes honcho mode` | Show or set recall mode (`hybrid`, `context`, `tools`) |
-| `hermes honcho tokens` | Show or set token budgets (`--context <N>`, `--dialectic <N>`) |
-| `hermes honcho sessions` | List known directory-to-session-name mappings |
-| `hermes honcho map <name>` | Map current working directory to a Honcho session name |
-| `hermes honcho identity` | Seed AI peer identity or show both peer representations |
-| `hermes honcho sync` | Create host blocks for all Hermes profiles that don't have one yet |
-| `hermes honcho migrate` | Step-by-step migration guide from OpenClaw native memory to Hermes + Honcho |
-| `hermes memory setup` | Generic memory provider picker (selecting "honcho" runs the same wizard) |
-| `hermes memory status` | Show active memory provider and config |
-| `hermes memory off` | Disable external memory provider |

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md

@@ -1,167 +0,0 @@
----
-title: "Openhands — Delegate coding to OpenHands CLI (model-agnostic, LiteLLM)"
-sidebar_label: "Openhands"
-description: "Delegate coding to OpenHands CLI (model-agnostic, LiteLLM)"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Openhands
-
-Delegate coding to OpenHands CLI (model-agnostic, LiteLLM).
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/openhands` |
-| Path | `optional-skills/autonomous-ai-agents\openhands` |
-| Version | `0.1.0` |
-| Author | Tim Koepsel (xzessmedia), Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos |
-| Tags | `Coding-Agent`, `OpenHands`, `Model-Agnostic`, `LiteLLM` |
-| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# OpenHands CLI
-
-Delegate coding tasks to the [OpenHands CLI](https://github.com/All-Hands-AI/OpenHands) via the `terminal` tool. OpenHands is model-agnostic: any LiteLLM-supported provider (OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, vLLM, etc.).
-
-This skill is the headless-mode wrapper for batch / one-shot delegation. The interactive textual UI is not used from Hermes.
-
-## When to Use
-
-- User wants a coding task delegated to OpenHands specifically.
-- User wants a coding agent that can run on a non-Anthropic / non-OpenAI provider (DeepSeek, Qwen, Ollama, vLLM, Nous, etc.) — sibling skills `claude-code` and `codex` are tied to one vendor.
-- Multi-step file edits + shell commands inside a workspace.
-
-For Claude-native, prefer `claude-code`. For OpenAI-native, prefer `codex`. For Hermes-native subagents, use `delegate_task`.
-
-## Prerequisites
-
-1. Install upstream (requires Python 3.12+ and `uv`):
-
-   ```
-   terminal(command="uv tool install openhands --python 3.12")
-   ```
-
-   Verify: `openhands --version` (currently `OpenHands CLI 1.16.0` / `SDK v1.21.0` at time of writing).
-
-2. Pick a model and set env vars for `--override-with-envs`:
-
-   ```
-   export LLM_MODEL=openrouter/openai/gpt-4o-mini       # or any LiteLLM slug
-   export LLM_API_KEY=$OPENROUTER_API_KEY
-   export LLM_BASE_URL=https://openrouter.ai/api/v1     # omit for native OpenAI
-   ```
-
-   `LLM_MODEL` uses LiteLLM's full slug. When the provider is OpenRouter the slug is doubly-prefixed: `openrouter/<vendor>/<model>` (e.g. `openrouter/anthropic/claude-sonnet-4.5`). For native Anthropic: `anthropic/claude-sonnet-4-5`. For native OpenAI: `openai/gpt-4o-mini`.
-
-3. Suppress the startup banner so JSON output isn't preceded by ASCII art:
-
-   ```
-   export OPENHANDS_SUPPRESS_BANNER=1
-   ```
-
-## How to Run
-
-Always invoke through the `terminal` tool. Always pass `--headless --json --override-with-envs --exit-without-confirmation` for automation.
-
-### One-shot task
-
-```
-terminal(
-  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=$OPENROUTER_API_KEY LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Add error handling to all API calls in src/'",
-  workdir="/path/to/project",
-  timeout=600
-)
-```
-
-### Background for long tasks
-
-```
-terminal(command="<same as above>", workdir="/path/to/project", background=true, notify_on_complete=true)
-process(action="poll", session_id="<id>")
-process(action="log", session_id="<id>")
-```
-
-### Resume a previous conversation
-
-OpenHands prints `Conversation ID: <32-hex>` and a `Hint: openhands --resume <dashed-uuid>` line at the end of each run. Use the dashed form to resume:
-
-```
-terminal(
-  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=... openhands --headless --json --override-with-envs --exit-without-confirmation --resume <dashed-uuid> -t 'Now fix the bug you found'",
-  workdir="/path/to/project"
-)
-```
-
-## Real Flag List
-
-Verified against `openhands --help` (CLI 1.16.0). Anything not in this table is not a flag — pass it via env var or settings file.
-
-| Flag | Effect |
-|------|--------|
-| `--headless` | No UI, requires `-t` or `-f`. Auto-approves all actions (no `--llm-approve` in this mode). |
-| `--json` | JSONL event stream (requires `--headless`). |
-| `-t TEXT` | Task prompt. |
-| `-f PATH` | Read task from file. |
-| `--resume [ID]` | Resume conversation. No ID → list recent. |
-| `--last` | Resume most recent (with `--resume`). |
-| `--override-with-envs` | Apply `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` env vars. Without this, OpenHands uses `~/.openhands/settings.json` and ignores the env. |
-| `--exit-without-confirmation` | Don't show the "are you sure" exit dialog. |
-| `--always-approve` / `--yolo` | Auto-approve every action (default in `--headless`). |
-| `--llm-approve` | LLM-based security gate (interactive only — does NOT work in headless). |
-| `--version` / `-v` | Print version and exit. |
-
-**There is no `--model`, `--max-iterations`, `--workspace`, `--sandbox`, `--sandbox-type` flag.** Model is `LLM_MODEL`. Workspace is the `workdir` you pass to the `terminal` tool. Sandbox / runtime is the `RUNTIME` and `SANDBOX_VOLUMES` env vars.
-
-## JSON Event Schema
-
-With `--json --headless`, OpenHands emits JSONL — one JSON object per line, plus a handful of non-JSON status lines (`Initializing agent...`, `Agent is working`, `Agent finished`, the final summary box, `Goodbye!`, `Conversation ID:`, `Hint:`). Filter for lines starting with `{`.
-
-Top-level `kind` field discriminates events:
-
-- `MessageEvent` — user / agent text turn. `source` is `user` or `agent`.
-- `ActionEvent` — agent picked a tool. Read `tool_name` (`file_editor`, `terminal`, `finish`) and `action.kind` (`FileEditorAction`, `TerminalAction`, `FinishAction`).
-- `ObservationEvent` — tool result. `observation.is_error` is the success flag. `source` is `environment`.
-- `FinishAction` inside an `ActionEvent` carries the agent's final message in `action.message`.
-
-The cli prints all stderr from LiteLLM/Authlib first — see Pitfalls. Parse only stdout, line by line, ignoring lines that don't start with `{`.
-
-## Pitfalls
-
-- **LiteLLM warnings on every invocation.** The CLI prints `bedrock-runtime` and `sagemaker-runtime` warnings to stderr because `botocore` isn't installed. Plus an Authlib deprecation. These are noise, not failures. Pipe stderr to `/dev/null` or filter it out before showing the user.
-- **Banner spam.** Without `OPENHANDS_SUPPRESS_BANNER=1`, every run starts with a multi-line `+--+` ASCII box advertising the SDK. Always export it.
-- **`--override-with-envs` is mandatory for automation.** Without it, OpenHands ignores `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` and falls back to `~/.openhands/settings.json`. On a fresh install this file doesn't exist and the CLI hangs waiting for first-run setup.
-- **Model slug is LiteLLM's, not the provider's.** `openrouter/openai/gpt-4o-mini` works; `openai/gpt-4o-mini` while pointed at OpenRouter does not. `anthropic/claude-sonnet-4-5` (hyphen) is native Anthropic; `openrouter/anthropic/claude-sonnet-4.5` (dot) is via OpenRouter. Get it wrong → cryptic LiteLLM 400.
-- **`pip install openhands-ai` is the wrong package.** That's the legacy V0 SDK. The new CLI is `uv tool install openhands --python 3.12`. There is no maintained conda package.
-- **Resume ID format is fiddly.** The CLI ends with `Conversation ID: f46573d9cfdb45e492ca189bde40019b` (no dashes) and then a `Hint: openhands --resume f46573d9-cfdb-45e4-92ca-189bde40019b` (with dashes). Use the dashed form.
-- **Headless ignores `--llm-approve`.** If you pass it, you get an argparse error. Headless mode hardcodes always-approve.
-- **No Windows support upstream.** The OpenHands docs require WSL on Windows. This skill is gated `[linux, macos]` accordingly.
-- **`~/.openhands/conversations/<id>/` accumulates.** Each run persists a trajectory. Clean it up if running batches.
-- **Heavy install (~200 packages).** Use `uv tool install` (isolated venv) to avoid dependency conflicts with the active project.
-
-## Verification
-
-```
-terminal(
-  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=$OPENROUTER_API_KEY LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Print the string OPENHANDS_OK to stdout via the terminal tool.'",
-  workdir="/tmp",
-  timeout=120
-)
-```
-
-If the JSONL stream ends with a `FinishAction` whose `action.message` mentions `OPENHANDS_OK`, the install is working.
-
-## Related
-
-- [OpenHands GitHub](https://github.com/All-Hands-AI/OpenHands)
-- [OpenHands CLI command reference](https://docs.openhands.dev/openhands/usage/cli/command-reference)
-- Sibling skills: `claude-code` (Anthropic-only), `codex` (OpenAI-only), `opencode` (multi-provider via OpenCode), `hermes-agent` (Hermes subagents via `delegate_task`).