@hybridaione/hybridclaw 0.9.2 → 0.9.4

package/AGENTS.md

@@ -219,6 +219,7 @@ npm run tui                          # tsx src/cli.ts tui
 ### Git Discipline
 
 - Treat existing uncommitted changes as user work unless you created them.
+- Run `npm run format` before creating commits that will be pushed to GitHub.
 - Conventional Commits preferred: `feat:`, `fix:`, `test:`, `refactor:`,
   `chore:`, `docs:`.
 - Group related changes; avoid bundling unrelated refactors.
@@ -309,7 +310,15 @@ When the user says "bump release":
 5. Commit with `chore: release vX.Y.Z`.
 6. Create an annotated git tag `vX.Y.Z`.
 7. Push the commit and tag.
-8. Create or publish a GitHub Release entry for the tag.
+8. Create or publish a GitHub Release entry for the tag using the same curated
+   format as `v0.9.2`:
+   - title: `HybridClaw vX.Y.Z`
+   - `Release Date:` line with the calendar date
+   - short blockquote summary paragraph
+   - `Highlights`, `Changed`, and `Fixed` sections with polished bullets
+   - `Contributors` section (`Core` and `All Contributors`)
+   - trailing `Full Changelog` compare link
+   - do not paste the raw `CHANGELOG.md` version heading/body verbatim
 
 ---
 

package/CHANGELOG.md

@@ -1,6 +1,86 @@
 # Changelog
 
-## [Unreleased]
+## [Coming up]
+
+## [0.9.4](https://github.com/HybridAIOne/hybridclaw/tree/v0.9.4)
+
+### Added
+
+- **Packaged agent GitHub install sources and activation**:
+  `hybridclaw agent install` now accepts
+  `official:<agent-dir>` and `github:owner/repo[/<ref>]/<agent-dir>` sources,
+  and `hybridclaw agent activate <agent-id>` can set the default agent for new
+  requests.
+- **Agent presentation profiles with image assets**: Agent configs and `.claw`
+  manifests can now declare `displayName` and workspace-relative `imageAsset`
+  metadata so web chat can show the active agent name and profile image.
+- **Startup opening automation for fresh sessions**: Gateway/web startup can
+  proactively run `BOOTSTRAP.md` for one-time onboarding and `OPENING.md` for a
+  fresh-session opening message before the user types the first turn.
+
+### Changed
+
+- **Bootstrap templates and workspace completion detection**: Refreshed the
+  shipped onboarding template around a lighter first-hatch flow, added the
+  optional `OPENING.md` template, and tightened workspace completion checks so
+  onboarding stays active until there is real post-bootstrap evidence.
+- **Web chat default-agent routing and history context**: New web sessions now
+  follow the configured default agent, preserve agent presentation across
+  history reloads, and keep bootstrap placeholder state visible while startup
+  autostart is still running.
+
+### Fixed
+
+- **HybridAI chatbot fallback resolution**: Gateway chat, scheduler runs, and
+  bootstrap autostart can fall back to `HybridAI /api/v1/bot-management/me`
+  when a session needs a chatbot id but none was configured explicitly.
+- **Packaged agent source validation**: Official/package GitHub installs now
+  require exact directory matches, reject `.claw` shorthand guesses, and keep
+  external install skipping explicit.
+- **Web chat composer focus styling**: Restored an accessible focus ring while
+  removing the extra focus border regression in the built-in chat surface.
+
+## [0.9.3](https://github.com/HybridAIOne/hybridclaw/tree/v0.9.3)
+
+### Added
+
+- **Hugging Face provider support**: Added `hybridclaw auth login|status|logout`
+  support for Hugging Face Inference providers, provider probing in `doctor`,
+  model-catalog discovery, and recommended-model handling for
+  `huggingface/...` model ids.
+- **Admin jobs board and scheduler follow-ups**: Added a dedicated `Jobs`
+  page in the embedded admin console with richer scheduler metadata, kanban
+  views, and job movement/edit flows for proactive agent work.
+- **Built-in tool toggles**: Added `hybridclaw tool list|enable|disable` so
+  operators can trim unused built-in prompt surfaces directly from runtime
+  config when `doctor` flags them.
+
+### Changed
+
+- **Container bootstrap and publish verification**: Installed packages now
+  prefer published runtime images while source checkouts build locally, and
+  the publish workflow verifies pushed GHCR tags before the job completes.
+- **Skill metadata parsing cleanup**: Consolidated frontmatter traversal and
+  metadata grouping in the skill loader so HybridClaw prefers native
+  HybridClaw metadata while still handling OpenClaw-compatible skill manifests
+  more predictably.
+
+### Fixed
+
+- **Scheduled delivery and backlog retry reliability**: Tightened scheduler
+  follow-up handling, admin/API job state updates, backlog retries, and
+  channel/email delivery flows so queued jobs recover more predictably after
+  failures.
+- **Router-provider credential normalization**: Shared API-key lookup and base
+  URL normalization across OpenRouter and Hugging Face so auth setup, runtime
+  credential resolution, and provider diagnostics behave more consistently.
+- **Skill install/sync path stability**: Stabilized installed and synced skill
+  paths, prevented path collisions during sync, and deduplicated install specs
+  independent of key order so repeated skill installs are safer and more
+  consistent.
+- **Malformed `requires` handling for skills**: HybridClaw now warns when a
+  skill declares malformed `requires` metadata instead of silently accepting
+  broken dependency declarations.
 
 ## [0.9.2](https://github.com/HybridAIOne/hybridclaw/tree/v0.9.2)
 

package/README.md

@@ -104,7 +104,7 @@ hybridclaw tui
 
 # Embedded admin console
 # open http://127.0.0.1:9090/admin
-# Includes Dashboard, Gateway, Sessions, Bindings, Models, Scheduler, MCP, Audit, Skills, Plugins, Tools, and Config
+# Includes Dashboard, Gateway, Sessions, Jobs, Bindings, Models, Scheduler, MCP, Audit, Skills, Plugins, Tools, and Config
 # If WEB_API_TOKEN is unset, localhost access opens without a login prompt
 # If WEB_API_TOKEN is set, /chat, /agents, and /admin all prompt for the same token
 ```
@@ -118,16 +118,19 @@ hybridclaw auth login hybridai --browser
 hybridclaw auth login hybridai --base-url http://localhost:5000
 hybridclaw auth login codex --import
 hybridclaw auth login openrouter anthropic/claude-sonnet-4 --api-key sk-or-...
+hybridclaw auth login huggingface meta-llama/Llama-3.1-8B-Instruct --api-key hf_...
 hybridclaw auth login local ollama llama3.2
 hybridclaw auth login msteams --app-id 00000000-0000-0000-0000-000000000000 --tenant-id 11111111-1111-1111-1111-111111111111 --app-password secret
 hybridclaw auth status hybridai
 hybridclaw auth status codex
 hybridclaw auth status openrouter
+hybridclaw auth status huggingface
 hybridclaw auth status local
 hybridclaw auth status msteams
 hybridclaw auth logout hybridai
 hybridclaw auth logout codex
 hybridclaw auth logout openrouter
+hybridclaw auth logout huggingface
 hybridclaw auth logout local
 hybridclaw auth logout msteams
 hybridclaw auth whatsapp reset
@@ -145,14 +148,15 @@ hybridclaw local configure ollama llama3.2
 - `hybridclaw auth login hybridai` auto-selects browser login on local GUI machines and a manual/headless API-key flow on SSH, CI, and container shells. `--import` copies the current `HYBRIDAI_API_KEY` from your shell into `~/.hybridclaw/credentials.json`, and `--base-url` updates `hybridai.baseUrl` before login.
 - `hybridclaw auth login codex` auto-selects browser PKCE on local GUI machines and device code on headless or remote shells.
 - `hybridclaw auth login openrouter` accepts `--api-key`, falls back to `OPENROUTER_API_KEY`, or prompts you to paste the key, then enables the provider and can set the global default model.
+- `hybridclaw auth login huggingface` accepts `--api-key`, falls back to `HF_TOKEN`, or prompts you to paste the token, then enables the provider and can set the global default model.
 - `hybridclaw auth login local` configures Ollama, LM Studio, or vLLM in `~/.hybridclaw/config.json`.
 - `hybridclaw auth login msteams` enables Microsoft Teams, stores `MSTEAMS_APP_PASSWORD` in `~/.hybridclaw/credentials.json`, and can prompt for the app id, app password, and optional tenant id.
 - `hybridclaw auth logout local` disables configured local backends and clears any saved vLLM API key.
 - `hybridclaw auth logout msteams` clears the stored Teams app password and disables the Teams integration in config.
 - `hybridclaw auth whatsapp reset` clears linked WhatsApp Web auth without starting a new pairing session.
-- HybridAI, OpenRouter, Discord, email, and Teams secrets are stored in `~/.hybridclaw/credentials.json`. Codex OAuth credentials are stored separately in `~/.hybridclaw/codex-auth.json`.
+- HybridAI, OpenRouter, Hugging Face, Discord, email, and Teams secrets are stored in `~/.hybridclaw/credentials.json`. Codex OAuth credentials are stored separately in `~/.hybridclaw/codex-auth.json`.
 - Only one running HybridClaw process should own `~/.hybridclaw/credentials/whatsapp` at a time. If WhatsApp Web shows duplicate Chrome/Ubuntu linked devices or reconnect/auth drift starts, stop the extra process, run `hybridclaw auth whatsapp reset`, then pair again with `hybridclaw channels whatsapp setup`.
-- Use `hybridclaw help`, `hybridclaw help auth`, `hybridclaw help openrouter`, or `hybridclaw help local` for CLI-specific reference output.
+- Use `hybridclaw help`, `hybridclaw help auth`, `hybridclaw help openrouter`, `hybridclaw help huggingface`, or `hybridclaw help local` for CLI-specific reference output.
 
 ## Setting Up MS Teams
 
@@ -166,7 +170,7 @@ See [docs/msteams.md](./docs/msteams.md) for the full setup flow, including:
 
 ## Model Selection
 
-Codex models use the `openai-codex/` prefix. OpenRouter models use the `openrouter/` prefix. The default shipped Codex model is `openai-codex/gpt-5-codex`.
+Codex models use the `openai-codex/` prefix. OpenRouter models use the `openrouter/` prefix. Hugging Face router models use the `huggingface/` prefix. The default shipped Codex model is `openai-codex/gpt-5-codex`.
 
 Examples:
 
@@ -176,18 +180,22 @@ Examples:
 /model default openai-codex/gpt-5-codex
 /model list openrouter
 /model set openrouter/anthropic/claude-sonnet-4
+/model list huggingface
+/model set huggingface/meta-llama/Llama-3.1-8B-Instruct
 /model clear
 /agent model openrouter/anthropic/claude-sonnet-4
 /model info
 /model default openrouter/anthropic/claude-sonnet-4
 ```
 
-- `hybridai.defaultModel` in `~/.hybridclaw/config.json` can point at a HybridAI model, an `openai-codex/...` model, an `openrouter/...` model, or a local backend model such as `ollama/...`.
+- `hybridai.defaultModel` in `~/.hybridclaw/config.json` can point at a HybridAI model, an `openai-codex/...` model, an `openrouter/...` model, a `huggingface/...` model, or a local backend model such as `ollama/...`.
 - `codex.models` in runtime config controls the allowed Codex model list shown in selectors and status output.
 - `openrouter.models` in runtime config controls the allowed OpenRouter model list shown in selectors and status output.
+- `huggingface.models` in runtime config controls the allowed Hugging Face model list shown in selectors and status output.
 - HybridAI model lists are refreshed from the configured HybridAI base URL (`/models`, then `/v1/models` as a compatibility fallback), and discovered `context_length` values feed status and model-info output when the API exposes them.
 - When the selected model starts with `openai-codex/`, HybridClaw resolves OAuth credentials through the Codex provider instead of `HYBRIDAI_API_KEY`.
 - When the selected model starts with `openrouter/`, HybridClaw resolves credentials through `OPENROUTER_API_KEY`.
+- When the selected model starts with `huggingface/`, HybridClaw resolves credentials through `HF_TOKEN`.
 - `/model set <name>` is a session-only override.
 - `/model clear` removes the session override and falls back to the current agent model or the global default.
 - `/agent model <name>` sets the persistent model for the current session agent.
@@ -208,8 +216,8 @@ Runtime model:
 - `hybridclaw gateway` and `hybridclaw tui` validate the container image at startup.
 - `container.sandboxMode` defaults to `container`, but if HybridClaw is already running inside a container and the setting is not explicitly pinned, the gateway auto-switches to `host` to avoid Docker-in-Docker.
 - Use `hybridclaw gateway start --sandbox=host` or `hybridclaw gateway restart --sandbox=host` to force host execution for a given launch.
-- On first run, HybridClaw automatically prepares that image (pulls a prebuilt image first, then falls back to local build if needed).
-- If container setup fails, run `npm run build:container` in the project root and retry.
+- On first run from an installed package, HybridClaw pulls a published container image automatically. In a source checkout, it builds the local container image instead.
+- If Docker is unavailable, install Docker or switch to `container.sandboxMode=host`.
 
 ## Configuration
 
@@ -223,6 +231,7 @@ HybridClaw creates `~/.hybridclaw/config.json` on first run and hot-reloads most
 - `mcpServers.*` declares Model Context Protocol servers that HybridClaw connects to per session and exposes as namespaced tools (`server__tool`).
 - `sessionReset.*` controls automatic daily and idle session expiry. The default policy resets both daily and after 24 hours idle at `04:00` in the gateway host's local timezone; set `sessionReset.defaultPolicy.mode` to `none` to disable automatic resets.
 - `sessionRouting.*` controls DM continuity scope. The default `per-channel-peer` mode keeps direct messages isolated by transport and peer identity; `per-linked-identity` plus `sessionRouting.identityLinks` can collapse verified aliases onto one shared main session.
+- `agents.defaultAgentId` selects the default agent for new requests and fresh web sessions when the user does not pin an agent explicitly.
 - `skills.disabled` and `skills.channelDisabled.{discord,msteams,whatsapp,email}` control global and per-channel skill availability. Use `hybridclaw skill enable|disable <name> [--channel <kind>]` or the TUI `/skill config` checklist to manage them.
 - `plugins.list[]` controls plugin overrides such as `enabled`, custom `path`, and top-level `config` values. Use `hybridclaw plugin config <plugin-id> [key] [value|--unset]` for focused edits without rewriting the full config file.
 - `adaptiveSkills.*` controls observation, inspection, amendment staging, and rollback for the self-improving skill loop. See [docs/development/extensibility/adaptive-skills.md](./docs/development/extensibility/adaptive-skills.md) for the operator workflow.
@@ -232,7 +241,7 @@ HybridClaw creates `~/.hybridclaw/config.json` on first run and hot-reloads most
 - `media.audio` controls shared inbound audio transcription. By default it auto-detects local CLIs first (`sherpa-onnx-offline`, `whisper-cli`, `whisper`), then `gemini`, then provider keys (`openai`, `groq`, `deepgram`, `google`).
 - `whisper-cli` auto-detect also needs a whisper.cpp model file. If the binary exists but HybridClaw still skips local transcription, set `WHISPER_CPP_MODEL` to a local `ggml-*.bin` model path.
 - If no transcript backend is available, the container tries native model audio input before tool-use fallback for supported local providers. Today that fallback is enabled for `vllm` sessions and uses the original current-turn audio attachment.
-- Keep runtime secrets in `~/.hybridclaw/credentials.json` (`HYBRIDAI_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `GROQ_API_KEY`, `DEEPGRAM_API_KEY`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `DISCORD_TOKEN`, `EMAIL_PASSWORD`, `MSTEAMS_APP_PASSWORD`). Codex OAuth sessions are stored separately in `~/.hybridclaw/codex-auth.json`.
+- Keep runtime secrets in `~/.hybridclaw/credentials.json` (`HYBRIDAI_API_KEY`, `OPENROUTER_API_KEY`, `HF_TOKEN`, `OPENAI_API_KEY`, `GROQ_API_KEY`, `DEEPGRAM_API_KEY`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `DISCORD_TOKEN`, `EMAIL_PASSWORD`, `MSTEAMS_APP_PASSWORD`). Codex OAuth sessions are stored separately in `~/.hybridclaw/codex-auth.json`.
 - Trust-model acceptance is stored in `~/.hybridclaw/config.json` under `security.*` and is required before runtime starts. In headless environments, set `HYBRIDCLAW_ACCEPT_TRUST=true` to persist acceptance automatically before credential checks run.
 - See [TRUST_MODEL.md](./TRUST_MODEL.md) for onboarding acceptance policy and [SECURITY.md](./SECURITY.md) for technical security guidelines.
 - For contributor workflow, see [CONTRIBUTING.md](./CONTRIBUTING.md). For deeper runtime, skills, release, voice/TTS, and maintainer reference docs, see [docs/development/README.md](./docs/development/README.md).
@@ -304,6 +313,8 @@ hybridclaw agent list
 hybridclaw agent export main -o /tmp/main.claw
 hybridclaw agent inspect /tmp/main.claw
 hybridclaw agent install /tmp/main.claw --id demo-agent --yes
+hybridclaw agent install official:charly-neumann-executive-briefing-chief-of-staff --yes
+hybridclaw agent activate demo-agent
 ```
 
 - `agent export` exports the workspace plus optional bundled workspace skills
@@ -311,7 +322,13 @@ hybridclaw agent install /tmp/main.claw --id demo-agent --yes
 - `agent inspect` validates the manifest and prints archive metadata without
   extracting it.
 - `agent install` restores the agent, fills missing bootstrap files, and
-  re-registers bundled content with the runtime.
+  re-registers bundled content with the runtime from a local `.claw` file or a
+  packaged GitHub source such as `official:<agent-dir>` or
+  `github:owner/repo[/<ref>]/<agent-dir>`.
+- `.claw` manifests can include agent presentation metadata such as a
+  `displayName` and workspace-relative profile image asset for web chat.
+- `agent activate <agent-id>` sets the default agent for new requests that do
+  not specify one explicitly.
 - Legacy aliases still work: `agent pack` maps to `export`, and `agent unpack`
   maps to `install`.
 - See [docs/development/extensibility/agent-packages.md](./docs/development/extensibility/agent-packages.md)

package/config.example.json

@@ -16,6 +16,9 @@
       "email": []
     }
   },
+  "tools": {
+    "disabled": []
+  },
   "adaptiveSkills": {
     "enabled": false,
     "observationEnabled": true,
@@ -170,6 +173,11 @@
     "baseUrl": "https://openrouter.ai/api/v1",
     "models": ["openrouter/anthropic/claude-sonnet-4"]
   },
+  "huggingface": {
+    "enabled": false,
+    "baseUrl": "https://router.huggingface.co/v1",
+    "models": ["huggingface/meta-llama/Llama-3.1-8B-Instruct"]
+  },
   "local": {
     "backends": {
       "ollama": {