@hybridaione/hybridclaw 0.12.4 → 0.12.6

package/AGENTS.md

@@ -21,7 +21,7 @@ HybridClaw is a personal AI assistant bot for Discord, powered by HybridAI.
 Enterprise-grade Node.js 22 application with gateway service, TUI client, and
 Docker-sandboxed container runtime.
 
-**Version:** 0.9.7  |  **Package:** `@hybridaione/hybridclaw`
+**Version:** 0.12.6  |  **Package:** `@hybridaione/hybridclaw`
  |  **License:** see `LICENSE`
 
 Architecture: gateway (core runtime, SQLite persistence, REST API, Discord
@@ -45,8 +45,9 @@ src/
   agent/                Agent execution: conversation loop, tool executor, prompt hooks, delegation
   audit/                Append-only audit trail, approval tracking, hash-chain integrity
   auth/                 HybridAI and OpenAI Codex authentication flows
-  channels/discord/     Discord integration and delivery logic
+  channels/             Channel transports (discord, slack, telegram, email, whatsapp, msteams, voice, imessage)
   config/               CLI flag parsing, runtime config management
+  doctor/               Doctor checks and resource hygiene maintenance
   gateway/              Core gateway service: HTTP APIs, health, session mgmt, approvals
   infra/                Container setup, IPC (file-based), worker signatures, runners
   memory/               SQLite database, semantic memory, compaction, consolidation, chunking
@@ -363,7 +364,7 @@ When the user says "bump release":
 - Do not include personal identity, real phone numbers, or live config values
   in tests, examples, docs, or commits.
 - Do not edit `.dockerignore` without verifying the resulting Docker image
-  still contains all runtime-required files (especially `docs/development/`).
+  still contains all runtime-required files (especially `docs/content/`).
   Build the image and confirm the affected paths exist inside it before
   marking the change complete.
 - Do not edit `node_modules/` or vendored files.
@@ -406,7 +407,7 @@ When multiple agents may be working on this repo concurrently:
 | `CONTRIBUTING.md`           | Human contributors  | Quickstart, PR workflow         |
 | `SECURITY.md`               | Security reviewers  | Runtime security controls       |
 | `TRUST_MODEL.md`            | Operators           | Trust acceptance policy         |
-| `docs/development/`         | Maintainers         | Architecture, runtime, testing  |
+| `docs/content/`             | Maintainers         | User docs, developer guide, reference |
 | `templates/*.md`            | Product runtime     | Agent workspace bootstrap       |
 
 ---

package/CHANGELOG.md

@@ -1,6 +1,122 @@
 # Changelog
 
-## [Coming up]
+## [0.12.6](https://github.com/HybridAIOne/hybridclaw/tree/v0.12.6)
+
+### Added
+
+- **Twilio voice channel**: Added a built-in Twilio ConversationRelay phone
+  channel with inbound webhook handling, outbound `hybridclaw gateway voice
+  call <number>` support, admin-console setup, and a dedicated setup and
+  troubleshooting guide.
+- **Salesforce skill**: New bundled skill for enterprise CRM integration with
+  OAuth token binding, a dedicated `secret` CLI surface for credential
+  management, and hardened field-level configuration.
+- **Local skill import**: `skill import` now accepts local filesystem
+  directories and `.zip` archives as sources, with persistent import-source
+  markers so locally-imported skills retain personal trust across restarts.
+- **Admin approvals policy console**: New `/admin/approvals` interface for
+  viewing and managing approval policies from the browser.
+- **Console chat UI**: Migrated the legacy standalone chat UI into the console
+  React app with unified channels selection and improved upstream error
+  handling.
+- **Doctor resource hygiene**: `hybridclaw doctor` now includes a resource
+  hygiene maintenance pass that detects and cleans stale gateway artifacts,
+  with cached DB snapshots and disk-state diffing for efficient checks.
+- **Fetch Email-Config button**: The admin email channel editor includes a
+  one-click button to fetch and validate HybridAI mailbox credentials.
+- **XLSX skill creation script**: Bundled creation script prevents silent
+  generation failures when the xlsx skill produces spreadsheet output.
+- **ToggleGroup component**: New `ToggleGroup` / `ToggleGroupItem` UI
+  primitive used across the admin console for binary-toggle controls.
+- **Provider health panel**: Inline login action and inactive-provider
+  collapse in the admin console for quicker provider triage.
+
+### Changed
+
+- **Per-channel instructions in `/admin/channels`**: The admin console now
+  lets operators edit transport-specific prompt guidance, and runtime config
+  exposes the same values under `channelInstructions.*` so channels such as
+  voice can enforce spoken-output rules without editing prompt files directly.
+- **OAuth token domain binding**: Bearer tokens are now bound to their OAuth
+  issuer domain to prevent cross-domain exfiltration, and the gateway proxy
+  auto-captures tokens using config constants instead of raw environment
+  variables.
+- **Secret CLI simplification**: Removed the `[--raw]` option from
+  `secret show` and `secret set`, streamlining the operator-facing surface.
+- **CI pipeline split**: Unit tests now run as parallel lint and test jobs
+  with a shared `setup-node-workspace` composite action and PR-level
+  concurrency groups that cancel stale runs.
+- **Security scanner hints**: Block messages now include actionable override
+  hints so operators understand how to respond to policy violations.
+- **DRY provider utilities**: Refactored model-matching and `agentId`
+  normalization into shared provider utilities with prefix-aware matching.
+
+### Fixed
+
+- **Voice approval and relay handling**: Spoken approval replies normalize more
+  reliably, voice turns skip the usual yellow implicit wait, and the Twilio
+  relay path handles disconnect, interrupt, and runtime-unavailable cases more
+  cleanly instead of dropping into noisier failure states.
+- **Memory-flush pool slot leak**: Host processes spawned during memory-flush
+  no longer leak worker pool slots, and empty sessions are cleaned up
+  automatically.
+- **Stream terminated retry**: Terminated stream errors are now retried
+  correctly, preserving PDF creation workflows across transport retries.
+- **Skill scanning and promotion**: Runtime-created skills in agent workspace
+  directories now appear in `/skill list` and are promoted to the managed
+  directory on save.
+- **Teams webhook resilience**: Missing Teams credentials on incoming webhook
+  requests are handled gracefully instead of crashing the handler.
+- **AuthProvider callback stability**: Stabilized React `AuthProvider`
+  callbacks with memoized context values to prevent unnecessary re-renders.
+- **Upstream error mapping**: Nested HybridAI error payloads are unwrapped
+  and mapped to `502` responses to avoid gateway auth confusion, with
+  `no-store` cache headers on error responses.
+- **Skip-skill-scan persistence**: The `--skip-skill-scan` CLI decision is
+  now persisted so the runtime guard honors it across restarts.
+
+## [0.12.5](https://github.com/HybridAIOne/hybridclaw/tree/v0.12.5)
+
+### Added
+
+- **Admin agent file editor**: The admin console now includes `/admin/agents`
+  for editing each registered agent's allowlisted workspace bootstrap markdown
+  files, with saved revision history and restore controls.
+
+### Changed
+
+- **Local TUI approval workflow**: Pending approvals in `hybridclaw tui` open a
+  keyboard-driven picker with `Up`/`Down` navigation, `Enter` confirmation,
+  number-key quick select, `Esc` to skip, and a text fallback for
+  non-interactive terminals.
+- **Admin destructive-action confirmations**: Browser-based operator flows now
+  use explicit confirmation dialogs for destructive actions so restarts,
+  deletes, and similar changes require a deliberate confirm step.
+
+### Fixed
+
+- **TUI approval replay handling**: Replayed or restated approval prompts reuse
+  cached approval details more reliably, and web `/approve` flows preserve
+  pending-approval metadata so follow-up approvals reopen the same picker
+  instead of dropping back to raw text.
+- **TUI exit summaries**: Exit output either shows the remote usage/tool/file
+  totals for the session or an explicit unavailable summary, and gateway
+  history breakdowns resolve canonical TUI session ids consistently for
+  tool/file counts.
+- **Invalid runtime-config recovery**: Interactive onboarding can restore the
+  last known-good saved config snapshot, or roll back to the newest saved
+  revision, when `config.json` becomes invalid JSON instead of leaving setup
+  stuck on in-memory defaults.
+- **Transport retry backoff**: Retry-aware channel transports honor
+  service-provided `Retry-After` delays and reject invalid retry values early
+  instead of silently retrying with bad timing.
+- **Email first-sync cursor handling**: The built-in email transport seeds a
+  missing mailbox cursor from the current mailbox head so old inbox mail is not
+  replayed as new traffic on first startup, while later restarts still deliver
+  mail that arrived while the gateway was offline.
+- **WhatsApp startup reliability**: The built-in WhatsApp transport disables
+  Baileys init queries that can trigger intermittent `400`/`bad-request`
+  failures during startup and pairing.
 
 ## [0.12.4](https://github.com/HybridAIOne/hybridclaw/tree/v0.12.4)
 
@@ -19,24 +135,12 @@
 - **Admin console dialog and toast UX**: Replaced inline banners with
   accessible dialog/toast primitives, tightened scheduler and jobs feedback
   flows, and refined the mobile topbar/sidebar interaction.
-- **Per-agent skill filtering**: Agent `skills` settings now narrow the
+- **Per-agent skill filtering**: Agent `skills` settings narrow the
   globally enabled skill set, while omitting `skills` keeps the existing
   global scope for backward compatibility.
 - **Approval presentation across channels**: Gateway approval copy and channel
-  actions now render more consistently, preserve approval ids correctly, and
-  align Discord and Slack approval flows more closely.
-
-### Fixed
-
-- **Slack slash-command ergonomics**: Slack slash commands use shorter
-  `/hc-*` names, keep runtime command coverage aligned with the shipped
-  manifest, and avoid review regressions in channel setup/documentation flows.
-- **Scheduler delivery state reporting**: One-shot deliveries now report retry
-  and review outcomes more clearly instead of leaving ambiguous scheduler state
-  after gateway or console handoff.
-- **Console accessibility edge cases**: Toast and dialog flows now keep
-  backdrops interactive, ignore closed dialogs in Escape-key handling, and
-  harden focus/visibility coordination during layered UI interactions.
+  actions render more consistently across Discord, Slack, and
+  gateway-managed approval surfaces.
 
 ## [0.12.3](https://github.com/HybridAIOne/hybridclaw/tree/v0.12.3)
 

package/README.md

@@ -19,9 +19,28 @@ security, and operational visibility. It combines sandboxed execution, secure
 credentials, approvals, persistent memory, and admin surfaces behind a single
 gateway.
 
-Connect it to Discord, Slack, WhatsApp, Telegram, Microsoft Teams, email, or the web. Run it
-locally, deploy it for business workflows, and keep your agents, secrets, and
-data under your control.
+Connect it to Discord, Slack, WhatsApp, Telegram, Microsoft Teams, email,
+Twilio voice, or the web. Run it locally, deploy it for business workflows,
+and keep your agents, secrets, and data under your control.
+
+[Quick Start](https://www.hybridclaw.io/docs/getting-started/quickstart) ·
+[Installation](https://www.hybridclaw.io/docs/getting-started/installation) ·
+[Configuration](https://www.hybridclaw.io/docs/reference/configuration) ·
+[Migration](https://www.hybridclaw.io/docs/reference/commands#migration) ·
+[Contributing](./CONTRIBUTING.md) ·
+[Support](./SUPPORT.md)
+
+## Pick your path
+
+- Want the shortest path to a running assistant? Start with
+  [Quick Start](https://www.hybridclaw.io/docs/getting-started/quickstart).
+- Want the full setup flow with providers, channels, and admin surfaces? Start
+  with [Installation](https://www.hybridclaw.io/docs/getting-started/installation)
+  and [Authentication](https://www.hybridclaw.io/docs/getting-started/authentication).
+- Want to migrate from OpenClaw or Hermes? Start with the
+  [migration commands](https://www.hybridclaw.io/docs/reference/commands#migration).
+- Want to contribute from source? Start with [CONTRIBUTING.md](./CONTRIBUTING.md)
+  and the maintainer docs under [docs/content/README.md](./docs/content/README.md).
 
 ## Coming from OpenClaw or Hermes?
 
@@ -58,7 +77,8 @@ hybridclaw tui
 Open locally:
 
 - Chat UI: `http://127.0.0.1:9090/chat`
-- Admin UI: `http://127.0.0.1:9090/admin` for channels, scheduler, audit, and config
+- Admin UI: `http://127.0.0.1:9090/admin` for channels, versioned agent files,
+  scheduler, audit, config, and channel-specific instructions
 - Agents UI: `http://127.0.0.1:9090/agents`
 - OpenAI-compatible API: `http://127.0.0.1:9090/v1/models` and `http://127.0.0.1:9090/v1/chat/completions`
 
@@ -73,10 +93,34 @@ operator and maintainer manual lives at
 Once the gateway is running, open HybridClaw locally:
 
 - Web Chat: `http://127.0.0.1:9090/chat`
-- Admin Console: `http://127.0.0.1:9090/admin` for channels, scheduler, audit, and config
+- Admin Console: `http://127.0.0.1:9090/admin` for channels, versioned agent files,
+  scheduler, audit, config, and channel-specific instructions
 - Agent Dashboard: `http://127.0.0.1:9090/agents`
 - or connect Slack, WhatsApp, Telegram, Discord, Microsoft Teams, Email
 
+## Operator workflows
+
+- `/admin/agents` edits allowlisted bootstrap markdown files such as
+  `AGENTS.md`, keeps saved revisions, and restores earlier versions from the
+  browser.
+- `/admin/channels` edits transport config, encrypted channel credentials,
+  Twilio voice settings, and per-channel instructions that are injected into
+  prompts at runtime.
+- `/admin/approvals` manages approval policies from the browser.
+- `hybridclaw tui` includes a keyboard-driven approval picker and prints a
+  ready-to-run `hybridclaw tui --resume <sessionId>` command on exit.
+- `hybridclaw doctor` checks runtime health including resource hygiene
+  maintenance for stale gateway artifacts.
+- `hybridclaw onboarding` and related local setup flows can restore the last
+  known-good saved config snapshot or roll back to a tracked revision when
+  `config.json` becomes invalid.
+- `hybridclaw skill import` supports community sources, local directories,
+  and `.zip` archives.
+- Channel delivery stays predictable: email seeds its first mailbox cursor from
+  the current head instead of replaying old inbox mail, retry-aware transports
+  honor server `Retry-After` backoff, and WhatsApp startup avoids intermittent
+  init-query bad-request failures.
+
 ## How HybridClaw compares
 
 | Capability | HybridClaw | OpenClaw | Hermes Agent |
@@ -111,6 +155,7 @@ Once the gateway is running, open HybridClaw locally:
 ## Built for real workflows
 
 - channels
+- versioned agent workspace prompt files with saved revisions and restore
 - browser sessions
 - office docs
 - skills / plugins / MCP
@@ -124,10 +169,11 @@ Once the gateway is running, open HybridClaw locally:
 
 ## Architecture
 
-- **Gateway service** (Node.js) — shared message/command handlers, SQLite persistence (KV + semantic + knowledge graph + canonical sessions + usage events), scheduler, heartbeat, web/API, loopback OpenAI-compatible API, and channel integrations for Discord, Slack, Microsoft Teams, Telegram, iMessage, WhatsApp, and email
+- **Gateway service** (Node.js) — shared message/command handlers, SQLite persistence (KV + semantic + knowledge graph + canonical sessions + usage events), scheduler, heartbeat, web/API, loopback OpenAI-compatible API, and channel integrations for Discord, Slack, Microsoft Teams, Telegram, iMessage, WhatsApp, Twilio voice, and email
 - **TUI client** — thin client over HTTP (`/api/chat`, `/api/command`) with
   a structured startup banner that surfaces model, sandbox, gateway, and
-  chatbot context before the first prompt
+  chatbot context before the first prompt, an interactive approval picker for
+  pending approvals, and an exit summary with a ready-to-run resume command
 - **Container** (Docker, ephemeral) — HybridAI API client, sandboxed tool executor, and preinstalled browser automation runtime with cursor-aware snapshots for JS-heavy custom UI
 - Communication via file-based IPC (input.json / output.json)
 
@@ -141,8 +187,8 @@ Browse the full manual at
   [Authentication](https://www.hybridclaw.io/docs/getting-started/authentication), and
   [Quick Start](https://www.hybridclaw.io/docs/getting-started/quickstart)
 - Enterprise deployment:
-  [Runtime Internals](https://www.hybridclaw.io/docs/internals/runtime) and
-  [Architecture](https://www.hybridclaw.io/docs/internals/architecture)
+  [Runtime Internals](https://www.hybridclaw.io/docs/developer-guide/runtime) and
+  [Architecture](https://www.hybridclaw.io/docs/developer-guide/architecture)
 - Operations:
   [Remote Access](https://www.hybridclaw.io/docs/guides/remote-access)
 - Security:
@@ -151,10 +197,16 @@ Browse the full manual at
   [Commands: Migration](https://www.hybridclaw.io/docs/reference/commands#migration) and
   [FAQ](https://www.hybridclaw.io/docs/reference/faq#can-i-migrate-an-existing-openclaw-or-hermes-agent-home)
 - Channels:
-  [Channel Setup](https://www.hybridclaw.io/docs/getting-started/channels),
-  [Slack](https://www.hybridclaw.io/docs/slack),
-  [iMessage](https://www.hybridclaw.io/docs/imessage), and
-  [MS Teams](https://www.hybridclaw.io/docs/msteams)
+  [Connect Your First Channel](https://www.hybridclaw.io/docs/getting-started/first-channel),
+  [Overview](https://www.hybridclaw.io/docs/channels/overview),
+  [Twilio Voice](https://www.hybridclaw.io/docs/guides/twilio-voice),
+  [Discord](https://www.hybridclaw.io/docs/channels/discord),
+  [Slack](https://www.hybridclaw.io/docs/channels/slack),
+  [Telegram](https://www.hybridclaw.io/docs/channels/telegram),
+  [Email](https://www.hybridclaw.io/docs/channels/email),
+  [WhatsApp](https://www.hybridclaw.io/docs/channels/whatsapp),
+  [iMessage](https://www.hybridclaw.io/docs/channels/imessage), and
+  [Microsoft Teams](https://www.hybridclaw.io/docs/channels/msteams)
 - Skills and plugins:
   [Extensibility](https://www.hybridclaw.io/docs/extensibility),
   [Bundled Skills](https://www.hybridclaw.io/docs/guides/bundled-skills),
@@ -171,20 +223,27 @@ Browse the full manual at
 
 ## Contributing
 
-Mini quick start:
+Contributor quick start:
 
 ```bash
 npm install
 npm run setup
 npm run build
+npm run typecheck
+npm run test:unit
 ```
 
 Use `npm run typecheck`, `npm run lint`, and targeted tests for code changes.
-For docs-only changes, verify links, commands, and examples. See
-[CONTRIBUTING.md](./CONTRIBUTING.md) for the full workflow and check matrix.
+For docs-only changes, verify links, commands, and examples. GitHub issue forms
+cover bug reports, setup help, feature requests, and docs fixes, and the PR
+template asks for validation and scope boundaries up front. See
+[CONTRIBUTING.md](./CONTRIBUTING.md) for the full workflow, check matrix, and
+community guidance.
 
 ## Community
 
 - Discord: [discord.gg/jsVW4vJw27](https://discord.gg/jsVW4vJw27)
 - Issues: [github.com/HybridAIOne/hybridclaw/issues](https://github.com/HybridAIOne/hybridclaw/issues)
 - Discussions: [github.com/HybridAIOne/hybridclaw/discussions](https://github.com/HybridAIOne/hybridclaw/discussions)
+- Support guide: [SUPPORT.md](./SUPPORT.md)
+- Community standards: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)

package/SECURITY.md

@@ -20,7 +20,7 @@ System prompts include safety constraints for every conversation turn:
 - Do not exfiltrate credentials, tokens, or private keys.
 - Prefer least-privilege actions and avoid destructive operations without explicit intent.
 
-Implementation: [src/prompt-hooks.ts](./src/prompt-hooks.ts)
+Implementation: [src/agent/prompt-hooks.ts](./src/agent/prompt-hooks.ts)
 
 ### 1.1) Browser Authentication Flows
 
@@ -67,7 +67,8 @@ Tool execution runs inside Docker with sandbox constraints:
 - controlled workspace/IPC mounts
 - additional mount allowlist validation
 
-Implementation: [src/container-runner.ts](./src/container-runner.ts), [src/mount-security.ts](./src/mount-security.ts)
+Implementation: [src/infra/container-runner.ts](./src/infra/container-runner.ts),
+[src/security/mount-security.ts](./src/security/mount-security.ts)
 
 ### 4) Session Isolation
 
@@ -123,3 +124,20 @@ If compromise is suspected:
 3. Review mount allowlist, workspace files, and `sessionRouting.identityLinks`.
 4. Inspect denied/authorization events with `hybridclaw audit approvals --denied`.
 5. Validate audit integrity with `hybridclaw audit verify`.
+
+## Reporting A Vulnerability
+
+Do not report security vulnerabilities in public GitHub issues or Discussions.
+
+Report vulnerabilities privately to
+[support@hybridai.one](mailto:support@hybridai.one?subject=HybridClaw%20security%20report)
+with:
+
+- affected HybridClaw version
+- deployment details and operating system
+- reproduction steps or proof-of-concept
+- impact assessment
+- suggested mitigation if you have one
+
+Please redact secrets, tokens, and personal data from any attached logs or
+screenshots.

package/config.example.json

@@ -14,6 +14,7 @@
       "msteams": [],
       "slack": [],
       "telegram": [],
+      "voice": [],
       "whatsapp": [],
       "email": []
     }
@@ -21,6 +22,16 @@
   "tools": {
     "disabled": []
   },
+  "channelInstructions": {
+    "discord": "",
+    "msteams": "",
+    "slack": "",
+    "telegram": "",
+    "voice": "This is a live phone call. Produce plain spoken text only.\nKeep each reply short and conversational, usually one or two short sentences.\nAbsolutely no markdown, bullets, numbered lists, headings, code fences, tables, JSON, or decorative formatting.\nDo not narrate internal reasoning, planning, tool usage, or stage directions. Say only what the caller should hear.\nDo not spell punctuation, formatting marks, or raw URLs unless the caller explicitly asks for exact characters.",
+    "whatsapp": "",
+    "email": "",
+    "imessage": ""
+  },
   "adaptiveSkills": {
     "enabled": false,
     "observationEnabled": true,
@@ -157,6 +168,25 @@
     "ackReaction": "👀",
     "mediaMaxMb": 20
   },
+  "voice": {
+    "enabled": false,
+    "provider": "twilio",
+    "twilio": {
+      "accountSid": "",
+      "authToken": "",
+      "fromNumber": ""
+    },
+    "relay": {
+      "ttsProvider": "default",
+      "voice": "",
+      "transcriptionProvider": "default",
+      "language": "en-US",
+      "interruptible": true,
+      "welcomeGreeting": "Hello! How can I help you today?"
+    },
+    "webhookPath": "/voice",
+    "maxConcurrentCalls": 8
+  },
   "imessage": {
     "enabled": false,
     "backend": "local",
@@ -459,6 +489,29 @@
   },
   "scheduler": {
     "jobs": [
+      {
+        "id": "resource-hygiene",
+        "name": "Resource Hygiene",
+        "description": "Runs conservative doctor-based resource hygiene twice daily and auto-applies only safe cleanup.",
+        "schedule": {
+          "kind": "every",
+          "at": null,
+          "everyMs": 43200000,
+          "expr": null,
+          "tz": "UTC"
+        },
+        "action": {
+          "kind": "system_event",
+          "message": "resource_hygiene_maintenance"
+        },
+        "delivery": {
+          "kind": "last-channel",
+          "channel": "",
+          "to": "",
+          "webhookUrl": ""
+        },
+        "enabled": true
+      },
       {
         "id": "morning-standup",
         "name": "Daily Standup Report",