@hybridaione/hybridclaw 0.2.8 → 0.2.12

package/CHANGELOG.md

@@ -2,7 +2,84 @@
 
 ## [Unreleased]
 
-No unreleased changes.
+### Added
+
+### Changed
+
+### Fixed
+
+## [0.2.12](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.12)
+
+### Added
+
+- **Automatic container publishing**: Added release-tag GitHub Actions publishing to Docker Hub (`hybridaione/hybridclaw-agent`) plus GHCR mirror (`ghcr.io/<org>/hybridclaw-agent`) with versioned tags (`vX.Y.Z`) and stable `latest` updates.
+- **Container build context guardrails**: Added `container/.dockerignore` and included it in npm package files so local secrets/artifacts are excluded from image build context.
+
+### Changed
+
+- **Runtime data default location**: Runtime config and data now default to `~/.hybridclaw` (`config.json`, `data/hybridclaw.db`, audit/session artifacts) to match home-directory workspace best practices.
+- **Container bootstrap pull order**: Container readiness now pulls prebuilt images from Docker Hub first (`v<app-version>`, then `latest`) with GHCR fallback before local build.
+- **README scope cleanup**: Reduced README to user-facing install/runtime guidance and moved maintainer/developer internals to `CONTRIBUTING.md`.
+- **Container build script behavior**: `npm run build:container` now runs `docker build` directly without requiring host TypeScript tooling.
+
+### Fixed
+
+- **First-run migration completeness**: Startup now migrates legacy `./config.json` and `./data` into `~/.hybridclaw`, archives legacy files, and stores migration backups under `~/.hybridclaw/migration-backups/` on conflicts.
+- **Install-root write issues**: Container image fingerprint state now persists under `~/.hybridclaw/container-image-state` (with legacy state fallback) instead of package install directories.
+- **Duplicate Discord `/status` slash entries**: Slash command registration now keeps `status`/`approve` global-only and removes stale guild-scoped duplicates to avoid duplicate command entries in guild channels.
+
+## [0.2.11](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.11)
+
+### Added
+
+- **Model default controls across TUI/Discord**: Added `model default [name]` command support in gateway/TUI plus a Discord `/model` slash command (`info`, `default`) with configured model choices.
+- **Local proactive reminder delivery path**: Added queued proactive pull API (`GET /api/proactive/pull`) and TUI polling so scheduler/heartbeat reminders reliably surface in `tui` channels.
+- **Scheduler timestamp regression test**: Added coverage for legacy SQLite second-precision timestamps and interval due-time regression handling.
+
+### Changed
+
+- **Cron tool reminder contract**: Cron `add` now accepts prompt aliases (`prompt`/`message`/`text`), supports relative one-shot scheduling via `at_seconds`, and documents prompt-as-instruction semantics for future model runs.
+- **Scheduler prompt framing**: Scheduled model turns now explicitly instruct execution of the provided instruction without follow-up questions.
+
+### Fixed
+
+- **SQLite timestamp interpretation drift**: Scheduler now normalizes legacy `YYYY-MM-DD HH:MM:SS` task timestamps as UTC, preventing immediate re-fire bugs on interval tasks after timezone conversion.
+- **Silent reply normalization edge case**: API/stream silent-token replacement now emits `Message sent.` only for real `message` send actions and otherwise falls back to the latest successful tool result.
+
+## [0.2.10](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.10)
+
+### Added
+
+- **Model retry policy helpers + tests**: Added shared model stream-fallback/retry predicates with dedicated unit coverage for retryable/non-retryable HybridAI error classes.
+- **Message tool schema regression test**: Added explicit schema test coverage to enforce valid `components` parameter structure for the `message` tool definition.
+
+### Changed
+
+- **Stream failure fallback behavior**: Container model-call flow now applies stream-to-non-stream fallback policy through centralized retry helpers for consistent error classification.
+
+### Fixed
+
+- **HybridAI function schema rejection**: Fixed `message` tool `components` schema by defining `items` for the array variant, resolving `invalid_function_parameters` 400 failures.
+- **HybridAI 500 handling robustness**: Streamed 5xx API failures now trigger the non-stream fallback path before hard-failing the turn.
+
+## [0.2.9](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.9)
+
+### Added
+
+- **Release bundle guard scripts**: Added root and container `release:check` scripts that validate `npm pack --dry-run` contents and fail on forbidden files (tests, source, CI/config artifacts).
+- **Dry-run publish helpers**: Added `publish:dry` scripts for root and container package smoke checks before publish.
+
+### Changed
+
+- **NPM package allowlists**: Added explicit `files` allowlists for root and container packages so publish output is limited to runtime assets and docs/templates/skills that HybridClaw loads at runtime.
+- **Prepack gating**: Root and container packages now run clean build + release bundle validation during `prepack`.
+- **CI packaging checks**: CI now runs root/container release bundle checks to catch publish-regression changes on PRs and pushes.
+- **Silent reply token handling**: Centralized `__MESSAGE_SEND_HANDLED__` parsing/cleanup, added streaming prefix buffering for Discord/API output paths, and aligned prompt token constants with shared silent-reply utilities.
+- **CLI build output mode**: Root `build` script now enforces executable mode on `dist/cli.js` after TypeScript compilation.
+
+### Fixed
+
+- **Silent token leakage in streams/history**: Streaming token fragments are now suppressed until divergence/confirmation, trailing silent tokens are stripped from mixed replies, and silent assistant placeholders are filtered from conversation history before model calls.
 
 ## [0.2.8](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.8)
 

package/README.md

@@ -11,16 +11,13 @@ npm install -g @hybridaione/hybridclaw
 hybridclaw onboarding
 ```
 
-Latest release: [v0.2.8](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.2.8)
+Latest release: [v0.2.12](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.2.12)
 
-## Release highlights (v0.2.8)
+## Release highlights (v0.2.12)
 
-- Discord `message` tool now supports richer actions (`send`, `read`, `member-info`, `channel-info`, `react`, `quote-reply`, `edit`, `delete`, `pin`, `unpin`, `thread-create`, `thread-reply`).
-- Send intent handling is more natural: aliases like `dm`, `post`, `reply`, `respond`, `history`, `fetch`, `lookup`, and `whois` normalize automatically.
-- Single-call DM routing is now supported for user targets (`user`/`username`, `@mentions`, IDs), including inline resolution when no explicit `channelId` is provided.
-- Message-tool descriptions now include intent phrases and enumerate configured channels so isolated/cron runs can discover available Discord targets.
-- Discord send governance gained runtime allowlist controls via `discord.sendPolicy` plus channel/guild/user/role checks.
-- Lookup failures now return structured errors with disambiguation candidates and optional `resolveAmbiguous=best` auto-pick behavior.
+- Runtime config/data now default to `~/.hybridclaw`, with automatic migration from legacy `./config.json` and `./data`.
+- HybridClaw now auto-pulls prebuilt runtime images (Docker Hub first, GHCR fallback) before trying a local build.
+- Discord slash command registration now removes duplicate guild `/status` entries and keeps global-only commands clean.
 
 ## HybridAI Advantage
 
@@ -54,7 +51,7 @@ hybridclaw onboarding
 # 3) open /register in browser (optional) and confirm in terminal
 # 4) open /login?next=/admin_api_keys in browser and get an API key
 # 5) paste API key (or URL containing it) back into the CLI
-# 6) choose the default bot (saved to config.json) and save secrets to `.env`
+# 6) choose the default bot (saved to ~/.hybridclaw/config.json) and save secrets to `.env`
 
 # Start gateway backend (default)
 hybridclaw gateway
@@ -77,341 +74,20 @@ Runtime model:
 - If `DISCORD_TOKEN` is set, Discord runs inside gateway automatically.
 - `hybridclaw tui` is a thin client that connects to the gateway.
 - `hybridclaw gateway` and `hybridclaw tui` validate the container image at startup.
-- If the image is missing, it is built automatically.
-- Default rebuild policy is `if-stale`: when tracked container sources changed since last build, the image is rebuilt automatically.
-- Policy override (optional): env `HYBRIDCLAW_CONTAINER_REBUILD=if-stale|always|never`.
-
-HybridClaw best-in-class capabilities:
-
-- explicit trust-model acceptance during onboarding (recorded in `config.json`)
-- typed `config.json` runtime settings with defaults, validation, and hot reload
-- formal prompt hook orchestration (`bootstrap`, `memory`, `safety`, `proactivity`)
-- layered memory substrate: structured KV, semantic memory, typed knowledge graph entities/relations, canonical cross-channel sessions, and usage event persistence
-- lightweight DB evolution and concurrency hardening via `PRAGMA user_version` migrations, `journal_mode=WAL`, and `busy_timeout=5000`
-- Discord conversational UX: edit-in-place streaming responses, fence-safe chunking beyond Discord's 2000-char limit, phase-aware typing/reactions, adaptive debounce batching, per-user rate limits, health-driven self-presence, reply-chain-aware context, concise attachment-first screenshot replies, and humanized pacing (time-of-day slowdown, cooldown scaling, selective silence, read-without-reply, startup staggering)
-- token-efficient context assembly: per-message history truncation, hard history budgets with head/tail preservation, and head/tail truncation for oversized bootstrap files
-- runtime self-awareness in prompts: exact HybridClaw version/date, model, and runtime host metadata injected each turn for reliable "what version/model are you?" answers
-- proactive runtime layer with active-hours gating, push delegation (`single`/`parallel`/`chain`), depth-aware tool policy, and retry controls
-- trusted-coworker approval model for tool execution: Green (`just run`), Yellow (`narrate + 5s interrupt window`), Red (`explicit approval`) with `yes` (once), `yes for session`, `yes for agent`, and explicit deny (`no`, also `4`) plus pinned-red protections
-- structured audit trail: append-only hash-chained wire logs (`data/audit/<session>/wire.jsonl`) with tamper-evident immutability, normalized SQLite audit tables, and verification/search CLI commands
-- observability export: incremental `events:batch` forwarding with durable cursor tracking and bot-scoped ingest token lifecycle via `ingest-token:ensure`
-- model token telemetry in audit/observability events (`model.usage`) with API usage + deterministic fallback estimates
-- built-in usage aggregation (`usage summary|daily|monthly|model`) plus JSONL session exports (`export session [sessionId]`) for cost/debug visibility
-- gateway lifecycle controls: managed + unmanaged restart/stop flows with graceful shutdown fallback paths
-- instruction-integrity approval flow: core instruction docs (`AGENTS.md`, `SECURITY.md`, `TRUST_MODEL.md`) are hash-verified against a local approved baseline before TUI start
+- 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.
 
 ## Configuration
 
-HybridClaw uses typed runtime config in `config.json` (auto-created on first run).
-
-- Start from `config.example.json` (reference)
-- Runtime watches `config.json` and hot-reloads most settings (model defaults, heartbeat, prompt hooks, limits, etc.)
-- `discord.guildMembersIntent` enables richer guild member context and better `@name` mention resolution in replies (requires enabling **Server Members Intent** in Discord Developer Portal)
-- `discord.presenceIntent` enables Discord presence events (requires enabling **Presence Intent** in Discord Developer Portal)
-- `discord.respondToAllMessages` is a global fallback for open-policy guild channels without explicit mode config (`false` mention-gated, `true` free-response)
-- `discord.commandMode` controls command access: `public` (any user can run slash/`!claw` commands) or `restricted` (only allowlisted users can run slash/`!claw` commands)
-- `discord.commandAllowedUserIds` is the allowlist used when `discord.commandMode` is `restricted`
-- `discord.commandUserId` is a legacy single-user allowlist alias; when set without `commandMode`, runtime treats command access as `restricted` for backward compatibility
-- `discord.commandsOnly` optional hard mode: if `true`, the bot ignores non-`!claw` messages and only accepts prefixed commands (still subject to `discord.commandMode`)
-- `discord.groupPolicy` controls guild channel scope: `open` (default, mention-first unless a channel is set to `free`), `allowlist`, or `disabled`
-- `discord.freeResponseChannels` is a Hermes-style channel ID list that gets free-response behavior while other channels remain mention-gated
-- `discord.textChunkLimit` controls Discord message chunk size (default `2000`)
-- `discord.maxLinesPerMessage` controls max lines per Discord chunk (default `17`)
-- `discord.humanDelay` controls natural delays between multi-part messages (`off|natural|custom`)
-- `discord.typingMode` controls typing indicator lifecycle (`instant|thinking|streaming|never`)
-- `discord.presence.*` enables dynamic self-presence health states (healthy/degraded/exhausted mapped to `online|idle|dnd`, plus maintenance `invisible` during shutdown)
-- `discord.lifecycleReactions.*` enables phase emoji transitions (`queued|thinking|toolUse|streaming|done|error`)
-- approval policy layer is configured via `.hybridclaw/policy.yaml` (`approval.pinned_red`, `workspace_fence`, pending/timeout controls, audit toggles)
-- `discord.ackReaction`, `discord.ackReactionScope`, and `discord.removeAckAfterReply` control acknowledgment reaction behavior
-- `discord.debounceMs` controls default inbound debounce; channel overrides can tune noisy channels
-- `discord.rateLimitPerUser` and `discord.rateLimitExemptRoles` enforce per-user sliding-window limits
-- `discord.suppressPatterns` blocks auto-reply triggers for suppression terms (case-insensitive)
-- `discord.maxConcurrentPerChannel` limits concurrent in-flight runs per channel
-- `discord.guilds.<guildId>.defaultMode` sets that guild's fallback mode in `open` policy (`mention` recommended)
-- `discord.guilds.<guildId>.channels.<channelId>.*` supports per-channel mode and behavior overrides (`mode`, `typingMode`, `debounceMs`, `ackReaction*`, `humanDelay`, `rateLimitPerUser`, `suppressPatterns`, `maxConcurrentPerChannel`)
-- `scheduler.jobs[]` defines config-backed proactive jobs with `schedule.kind` (`cron|every|at`), `action.kind` (`agent_turn|system_event`), and delivery targets (`channel|last-channel|webhook`)
-- `scheduler.jobs[].name` / `scheduler.jobs[].description` add optional human-readable labels for status/log output; runtime status persists `nextRunAt`
-- Config scheduler job metadata (last status, consecutive errors, one-shot completion) persists atomically in `data/scheduler-jobs-state.json`
-- Config scheduler jobs auto-disable after repeated failures (5 consecutive errors) and one-shot jobs retry on a bounded interval until successful
-- `memory.decayRate` and `memory.consolidationIntervalHours` control semantic-memory consolidation intensity/cadence
-- `sessionCompaction.tokenBudget` and `sessionCompaction.budgetRatio` tune compaction token budgeting behavior
-- Built-in Discord humanization behaviors include night/weekend pacing, post-exchange cooldown scaling (after 5+ exchanges, reset after 20 minutes idle), selective silence in active free-mode channels, short-ack read reactions, and reconnect staggered dequeue
-- Per-guild/per-channel mode takes precedence over `discord.respondToAllMessages`
-- Discord slash commands: `/status`, `/approve [view|yes|session|agent|no] [approval_id]`, `/channel-mode <off|mention|free>`, and `/channel-policy <open|allowlist|disabled>` (ephemeral replies)
-- `skills.extraDirs` adds additional enterprise/shared skill roots (lowest precedence tier)
-- `proactive.*` controls autonomous behavior (`activeHours`, `delegation`, `autoRetry`, `ralph`)
-- `proactive.ralph.maxIterations` enables Ralph loop (`0` off, `-1` unlimited, `>0` extra autonomous iterations before forcing completion)
-- TUI/Gateway command: `ralph on|off|set <n>|info` (`0` off, `-1` unlimited, `1-64` extra iterations)
-- `observability.*` controls push ingest into HybridAI (`events:batch` endpoint, batching, identity metadata)
-- Some settings require restart to fully apply (for example HTTP bind host/port)
-- Default bot is configured via `hybridai.defaultChatbotId` in `config.json`
-- `hybridai.maxTokens` sets the default completion budget per model call (default `4096`)
-
-Secrets remain in `.env`:
-
-- `HYBRIDAI_API_KEY` (required)
-- `DISCORD_TOKEN` (optional)
-- `WEB_API_TOKEN` and `GATEWAY_API_TOKEN` (optional API auth hardening)
-- observability ingest token is auto-managed via `POST /api/v1/agent-observability/ingest-token:ensure` and cached locally
-
-Trust-model acceptance is stored in `config.json` under `security.*` and is required before runtime starts.
-
-See [TRUST_MODEL.md](./TRUST_MODEL.md) for onboarding acceptance policy and [SECURITY.md](./SECURITY.md) for technical security guidelines.
-
-## Audit Trail
-
-HybridClaw records a forensic audit trail by default:
-
-- append-only per-session wire logs in `data/audit/<session>/wire.jsonl`
-- SHA-256 hash chaining (`_prevHash` -> `_hash`) for tamper-evident immutability
-- normalized query tables in SQLite (`audit_events`, `approvals`)
-- policy denials captured as approval/authorization events (for example blocked commands)
-
-Useful commands:
-
-- `hybridclaw audit recent 50`
-- `hybridclaw audit search "tool.call" 50`
-- `hybridclaw audit approvals 50 --denied`
-- `hybridclaw audit verify <sessionId>`
-- `hybridclaw audit instructions`
-- `hybridclaw audit instructions --approve`
-
-Instruction approval notes:
-
-- local baseline file: `data/audit/instruction-hashes.json`
-- `hybridclaw audit instructions` fails when instruction files differ from the approved baseline
-- `hybridclaw audit instructions --approve` updates the local approved baseline
-- `hybridclaw tui` performs this check before startup and prompts for approval when files changed
-- instruction approval actions are audit logged (`approval.request` / `approval.response`, action `instruction:approve`)
-
-## Observability Push
-
-HybridClaw can forward structured audit records to HybridAI's ingest API:
-
-- endpoint: `POST /api/v1/agent-observability/events:batch`
-- source: local `audit_events` table (ordered by `id`)
-- transport: bearer ingest token auto-fetched via `POST /api/v1/agent-observability/ingest-token:ensure` using `HYBRIDAI_API_KEY`
-- delivery: incremental batches with persisted cursor (`observability_offsets` table), max 1000 events and max 2,000,000-byte payload per request
-- token handling: token cache is stored locally in SQLite (`observability_ingest_tokens`) and automatically refreshed on ingest auth failures
-- token visibility: `model.usage` payloads include `promptTokens`, `completionTokens`, `totalTokens`, plus estimated and API-native counters for accuracy/coverage
-
-Config keys (in `config.json`):
-
-- `observability.enabled` (`true` by default)
-- `observability.baseUrl` (for example `https://hybridai.one`)
-- `observability.ingestPath` (`/api/v1/agent-observability/events:batch`)
-- `observability.botId` (defaults to `hybridai.defaultChatbotId` when empty)
-- `observability.agentId`, `observability.label`, `observability.environment`
-- `observability.flushIntervalMs`, `observability.batchMaxEvents`
-
-Runtime diagnostics:
-
-- local status endpoint `GET /api/status` includes an `observability` block (enabled/running/paused, cursor, last success/failure timestamps)
-
-## Agent workspace
-
-Each agent gets a persistent workspace with markdown files that shape its personality and memory:
-
-| File | Purpose |
-|------|---------|
-| `SOUL.md` | Personality, tone, identity |
-| `IDENTITY.md` | Name, avatar, emoji |
-| `USER.md` | Info about the human |
-| `MEMORY.md` | Persistent memory across sessions |
-| `AGENTS.md` | Workspace conventions and rules |
-| `TOOLS.md` | Environment-specific notes |
-| `HEARTBEAT.md` | Periodic tasks |
-| `BOOT.md` | Startup instructions |
-
-Templates in `templates/` are copied to new agent workspaces on first run.
-Historical turn logs are mirrored into `<workspace>/.session-transcripts/*.jsonl` for `session_search`.
-
-## Skills
-
-HybridClaw supports `SKILL.md`-based skills (`<skill-name>/SKILL.md`).
-
-### Where to put skills
-
-You can place skills in:
-
-- any directory listed in `config.skills.extraDirs[]` (enterprise/shared)
-- bundled package skills (`<hybridclaw install>/skills/<skill-name>/SKILL.md`)
-- `$CODEX_HOME/skills/<skill-name>/SKILL.md` or `~/.codex/skills/<skill-name>/SKILL.md`
-- `~/.claude/skills/<skill-name>/SKILL.md`
-- `~/.agents/skills/<skill-name>/SKILL.md`
-- `./.agents/skills/<skill-name>/SKILL.md` (project)
-- `./skills/<skill-name>/SKILL.md` (workspace)
-
-Load precedence is:
-
-- `extra < bundled < codex < claude < agents-personal < agents-project < workspace`
-- skills are merged by `name`; higher-precedence sources override lower-precedence ones
-
-Security scanning is trust-aware:
-
-- `bundled` sources are treated as `builtin` and not scanned
-- `workspace` sources (`./skills/`, `./.agents/skills/`) are scanned; `caution` is allowed, `dangerous` is blocked
-- `personal` sources (`~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`) are scanned and blocked on `caution`/`dangerous`
-- scanner includes Hermes-derived regex checks, structural limits (50 files, 1MB total, 256KB/file, binary/symlink checks), invisible-unicode detection, and mtime+content-hash cache reuse
-
-### Required format
-
-Each skill must be a folder with a `SKILL.md` file and frontmatter:
-
-```markdown
----
-name: repo-orientation
-description: Quickly map an unfamiliar repository and identify where a requested feature should be implemented.
-user-invocable: true
-disable-model-invocation: false
-always: false
-requires:
-  bins: [docker, git]
-  env: [GITHUB_TOKEN]
-metadata:
-  hybridclaw:
-    tags: [devops, docker]
-    related_skills: [kubernetes]
----
-
-# Repo Orientation
-...instructions...
-```
-
-Supported frontmatter keys:
-
-- `name` (required)
-- `description` (required)
-- `user-invocable` (optional, default `true`)
-- `disable-model-invocation` (optional, default `false`)
-- `always` (optional, default `false`; embeds full skill body in the system prompt up to `maxAlwaysChars=10000`, then demotes to summary)
-- `requires.bins` / `requires.env` (optional; skill is excluded unless requirements are met)
-- `metadata.hybridclaw.tags` / `metadata.hybridclaw.related_skills` (optional metadata namespace)
+HybridClaw creates `~/.hybridclaw/config.json` on first run and hot-reloads most runtime settings.
 
-### Using skills
-
-Skills are listed to the model as metadata (`name`, `description`, `location`), and the model reads `SKILL.md` on demand with the `read` tool. Skills with `always: true` are embedded directly in the system prompt.
-
-Prompt embedding modes:
-
-- `Always`: `always: true` embeds full body in `<skill_always ...>` (budgeted by `maxAlwaysChars=10000`)
-- `Summary`: default mode, emits only XML metadata under `<available_skills>`
-- `Hidden`: `disable-model-invocation: true` excludes the skill from model prompt metadata (still invocable by slash command when `user-invocable: true`)
-
-Explicit invocation is supported via:
-
-- `/skill <name> [input]`
-- `/skill:<name> [input]`
-- `/<name> [input]` (when `user-invocable: true`; command names are sanitized to lowercase `a-z0-9-`, max 32 chars, with `-2`/`-3` dedup and built-in command-name blocking)
-
-Example skill in this repo:
-
-- `skills/repo-orientation/SKILL.md`
-- `skills/current-time/SKILL.md`
-- `skills/personality/SKILL.md`
-- `skills/skill-creator/SKILL.md`
-
-### Personality switching skill
-
-HybridClaw includes a command-only personality skill that updates the active persona contract in `SOUL.md`.
-
-- List current/available persona: `/personality` (or `/personality list`)
-- Activate persona: `/personality <name>`
-- Reset to default persona: `/personality reset`
-
-The skill writes/updates a managed block in `SOUL.md`:
-
-- `## Active personality`
-- `Name: ...`
-- `Definition: ...` (copied from the selected profile in `skills/personality/SKILL.md`)
-- `Rules: ...` (runtime style/behavior constraints)
-
-Notes:
-
-- The personality skill is intentionally command-only (`always: false`, `disable-model-invocation: true`) to avoid adding per-turn prompt overhead.
-- Profiles are defined in `skills/personality/SKILL.md` and currently include 25 switchable personas (expert, style, and role personas).
-
-## Agent tools
-
-The agent has access to these sandboxed tools inside the container:
-
-- `read` / `write` / `edit` / `delete` — file operations
-- `glob` / `grep` — file search
-- `bash` — shell command execution
-- `memory` — durable memory files (`MEMORY.md`, `USER.md`, `memory/YYYY-MM-DD.md`)
-- `session_search` — search/summarize historical sessions from transcript archives
-- `delegate` — push-based background subagent tasks (`single`, `parallel`, `chain`) with auto-announced completion (no polling)
-- `web_fetch` — plain HTTP fetch + extraction for static/read-only content (docs, articles, READMEs, JSON/text APIs, direct files)
-- `browser_*` (optional) — full browser automation for JS-rendered or interactive pages (`navigate`, `snapshot`, `click`, `type`, `upload`, `press`, `scroll`, `back`, `screenshot`, `pdf`, `close`)
-
-`delegate` mode examples:
-
-- single: `{ "prompt": "Audit auth middleware and list risks", "label": "auth-audit" }`
-- parallel: `{ "mode": "parallel", "label": "module-audit", "tasks": [{ "prompt": "Scan api/" }, { "prompt": "Scan ui/" }] }`
-- chain: `{ "mode": "chain", "label": "implement-flow", "chain": [{ "prompt": "Scout the payment module" }, { "prompt": "Plan changes from: {previous}" }, { "prompt": "Implement based on: {previous}" }] }`
-
-Browser tooling notes:
-
-- Routing default: prefer `web_fetch` first for read-only retrieval.
-- Use browser tools for SPAs/web apps/auth flows/interaction tasks, or when `web_fetch` returns escalation hints (`javascript_required`, `spa_shell_only`, `empty_extraction`, `boilerplate_only`, `bot_blocked`).
-- Cost profile: browser calls are typically ~10-100x slower/more expensive than `web_fetch`.
-- Browser read flow: after `browser_navigate`, use `browser_snapshot` with `mode="full"` to extract content, then `browser_scroll` + `browser_snapshot` for additional lazy-loaded sections.
-- `browser_pdf` is for export artifacts, not text extraction.
-
-- The shipped container image preinstalls `agent-browser` and Chromium (Playwright).
-- You can override the binary via `AGENT_BROWSER_BIN` if needed.
-- User-directed authenticated browser-flow testing is supported (including filling/submitting login forms on the requested site).
-- Browser auth/session state now persists per HybridClaw session by default via a dedicated profile directory under `/workspace/.hybridclaw-runtime/browser-profiles`.
-- Session cookies/localStorage are also auto-saved/restored via `agent-browser` session-state files.
-- Optional overrides: `BROWSER_PERSIST_PROFILE=false` (disable profile persistence), `BROWSER_PERSIST_SESSION_STATE=false` (disable state file persistence), `BROWSER_PROFILE_ROOT=/path` (custom profile root), `BROWSER_CDP_URL=ws://...` (force CDP attachment to an existing browser).
-- Structured audit logs redact sensitive browser/tool arguments (password/token/secret fields and typed form text).
-- Navigation to private/loopback hosts is blocked by default (set `BROWSER_ALLOW_PRIVATE_NETWORK=true` to override).
-- Screenshot/PDF outputs are constrained to `/workspace/.browser-artifacts`.
-
-HybridClaw also supports automatic session compaction with pre-compaction memory flush:
-
-- when a session gets long, old turns are summarized into `session_summary`
-- before compaction, the agent gets a `memory`-only flush turn to persist durable notes
-- each `(agent_id, user_id)` pair also maintains a canonical cross-channel session for continuity across channels
-- canonical context injection includes compacted summary + recent cross-channel messages (excluding the current live session)
-- compaction writes JSONL exports to `<workspace>/.session-exports/` for human-readable debugging
-
-System prompt assembly is handled by a formal hook pipeline:
-
-- `bootstrap` hook (workspace bootstrap + skills metadata)
-- `memory` hook (session summary)
-- `safety` hook (runtime guardrails / trust-model constraints)
-- `proactivity` hook (memory capture, session recall, delegation behavior)
-
-Hook toggles live in `config.json` under `promptHooks`.
-
-## Testing
-
-Run checks locally:
-
-```bash
-# Typecheck only (no emit)
-npm run typecheck
-
-# Strict TS lint gate (unused locals/params)
-npm run lint
-
-# Unit tests (default `npm test`)
-npm run test:unit
-
-# Scoped suites (ready for dedicated tests)
-npm run test:integration
-npm run test:e2e
-npm run test:live
-```
-
-Test layout and scopes:
-
-- tests live under `tests/` (not `src/`)
-- unit tests: `tests/**/*.test.ts` (excluding `*.integration|*.e2e|*.live`)
-- integration tests: `tests/**/*.integration.test.ts`
-- e2e tests: `tests/**/*.e2e.test.ts`
-- live tests: `tests/**/*.live.test.ts`
+- Start from `config.example.json` (reference).
+- Runtime data is stored in `~/.hybridclaw/` by default (`config.json`, `data/hybridclaw.db`, audit/session files).
+- On upgrade, legacy `./config.json` and `./data` are migrated to `~/.hybridclaw` automatically; backups are kept in `~/.hybridclaw/migration-backups/` when needed.
+- Keep secrets in `.env` (`HYBRIDAI_API_KEY` required, `DISCORD_TOKEN` optional).
+- Trust-model acceptance is stored in `~/.hybridclaw/config.json` under `security.*` and is required before runtime starts.
+- See [TRUST_MODEL.md](./TRUST_MODEL.md) for onboarding acceptance policy and [SECURITY.md](./SECURITY.md) for technical security guidelines.
+- For advanced configuration, audit/observability details, skills internals, agent tools, and developer docs, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## Commands
 
@@ -444,18 +120,3 @@ In Discord, use `!claw help` to see all commands. Key ones:
 - `!claw schedule add "<cron>" <prompt>` — Add cron scheduled task
 - `!claw schedule add at "<ISO time>" <prompt>` — Add one-shot task
 - `!claw schedule add every <ms> <prompt>` — Add interval task
-
-## Project structure
-
-```
-src/gateway.ts                    Core runtime entrypoint (DB, scheduler, heartbeat, HTTP API)
-src/tui.ts                        Terminal adapter (thin client to gateway)
-src/channels/discord/runtime.ts   Discord runtime integration and message transport
-src/channels/discord/*.ts         Discord responsibility modules (inbound, delivery, mentions, attachments, tools, stream)
-src/gateway-service.ts            Core shared agent/session logic used by gateway API
-src/gateway-client.ts             HTTP client used by thin clients (e.g. TUI)
-tests/                            Vitest suites (unit/integration/e2e/live scopes)
-container/src/                    Agent code (tools, HybridAI client, IPC)
-templates/                        Workspace bootstrap files
-data/                             Runtime data (gitignored): SQLite DB, sessions, agent workspaces
-```

package/config.example.json

@@ -92,7 +92,7 @@
     "webApiToken": "",
     "gatewayBaseUrl": "http://127.0.0.1:9090",
     "gatewayApiToken": "",
-    "dbPath": "data/hybridclaw.db",
+    "dbPath": "~/.hybridclaw/data/hybridclaw.db",
     "logLevel": "info"
   },
   "observability": {

package/container/.dockerignore

@@ -0,0 +1,16 @@
+node_modules
+dist
+.env
+.env.*
+.npmrc
+npm-debug.log*
+yarn-error.log*
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+*.kubeconfig
+*.sqlite
+*.db
+*.log

package/container/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hybridclaw-agent",
-  "version": "0.2.8",
+  "version": "0.2.12",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hybridclaw-agent",
-      "version": "0.2.8",
+      "version": "0.2.12",
       "dependencies": {
         "@mozilla/readability": "^0.6.0",
         "agent-browser": "^0.15.1",

package/container/package.json

@@ -1,10 +1,19 @@
 {
   "name": "hybridclaw-agent",
-  "version": "0.2.8",
+  "version": "0.2.12",
   "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist/",
+    "Dockerfile"
+  ],
   "scripts": {
+    "clean": "node -e \"const fs=require('node:fs');fs.rmSync('dist',{recursive:true,force:true});\"",
     "build": "tsc",
-    "lint": "tsc --noEmit --noUnusedLocals --noUnusedParameters"
+    "lint": "tsc --noEmit --noUnusedLocals --noUnusedParameters",
+    "prepack": "npm run clean && npm run build && npm run release:check",
+    "release:check": "node ./scripts/release-check.mjs",
+    "publish:dry": "npm publish --dry-run"
   },
   "dependencies": {
     "@mozilla/readability": "^0.6.0",

package/container/src/index.ts

@@ -8,12 +8,12 @@ import {
   runAfterToolHooks,
   runBeforeToolHooks,
 } from './extensions.js';
-import {
-  callHybridAI,
-  callHybridAIStream,
-  HybridAIRequestError,
-} from './hybridai-client.js';
+import { callHybridAI, callHybridAIStream } from './hybridai-client.js';
 import { waitForInput, writeOutput } from './ipc.js';
+import {
+  isRetryableModelError,
+  shouldFallbackFromStreamError,
+} from './model-retry.js';
 import {
   accumulateApiUsage,
   createTokenUsageStats,
@@ -305,16 +305,6 @@ function emitStreamDelta(delta: string): void {
   console.error(`[stream] ${payload}`);
 }
 
-function isRetryableError(err: unknown): boolean {
-  if (err instanceof HybridAIRequestError) {
-    return err.status === 429 || (err.status >= 500 && err.status <= 504);
-  }
-  const message = err instanceof Error ? err.message : String(err);
-  return /fetch failed|network|socket|timeout|timed out|ECONNRESET|ECONNREFUSED|EAI_AGAIN/i.test(
-    message,
-  );
-}
-
 function inferToolError(result: string, blockedReason: string | null): boolean {
   if (blockedReason) return true;
   return /\b(error|failed|denied|forbidden|timed out|timeout|exception|invalid)\b/i.test(
@@ -538,11 +528,7 @@ async function callHybridAIWithRetry(params: {
             maxTokens,
           );
         } catch (streamErr) {
-          const fallbackEligible =
-            streamErr instanceof HybridAIRequestError &&
-            streamErr.status >= 400 &&
-            streamErr.status < 500 &&
-            streamErr.status !== 429;
+          const fallbackEligible = shouldFallbackFromStreamError(streamErr);
           if (!fallbackEligible) throw streamErr;
           response = await callHybridAI(
             baseUrl,
@@ -575,7 +561,9 @@ async function callHybridAIWithRetry(params: {
       return response;
     } catch (err) {
       const retryable =
-        RETRY_ENABLED && isRetryableError(err) && attempt < RETRY_MAX_ATTEMPTS;
+        RETRY_ENABLED &&
+        isRetryableModelError(err) &&
+        attempt < RETRY_MAX_ATTEMPTS;
       await emitRuntimeEvent({
         event: retryable ? 'model_retry' : 'model_error',
         attempt,

package/container/src/model-retry.ts

@@ -0,0 +1,19 @@
+import { HybridAIRequestError } from './hybridai-client.js';
+
+const TRANSIENT_NETWORK_ERROR_RE =
+  /fetch failed|network|socket|timeout|timed out|ECONNRESET|ECONNREFUSED|EAI_AGAIN/i;
+
+export function shouldFallbackFromStreamError(error: unknown): boolean {
+  if (!(error instanceof HybridAIRequestError)) return false;
+  // Keep 429 on retry/backoff path; fallback does not help throttling.
+  if (error.status === 429) return false;
+  return error.status >= 400 && error.status <= 599;
+}
+
+export function isRetryableModelError(error: unknown): boolean {
+  if (error instanceof HybridAIRequestError) {
+    return error.status === 429 || (error.status >= 500 && error.status <= 504);
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return TRANSIENT_NETWORK_ERROR_RE.test(message);
+}