@hybridaione/hybridclaw 0.2.3 → 0.2.7

package/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Install container dependencies
+        run: npm run setup
+
+      - name: Biome check (changed files)
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            BASE_SHA="${{ github.event.pull_request.base.sha }}"
+          else
+            BASE_SHA="${{ github.event.before }}"
+          fi
+          HEAD_SHA="${{ github.sha }}"
+
+          FILES=()
+          if [[ -z "${BASE_SHA}" || "${BASE_SHA}" == "0000000000000000000000000000000000000000" ]]; then
+            while IFS= read -r file; do
+              [[ -n "${file}" ]] && FILES+=("${file}")
+            done < <(git ls-files src | grep -E '^src/.*\.(ts|tsx|js|jsx)$' || true)
+          else
+            while IFS= read -r file; do
+              [[ -n "${file}" ]] && FILES+=("${file}")
+            done < <(
+              git diff --name-only --diff-filter=ACMRT "${BASE_SHA}" "${HEAD_SHA}" \
+                | grep -E '^src/.*\.(ts|tsx|js|jsx)$' || true
+            )
+          fi
+
+          if [[ "${#FILES[@]}" -eq 0 ]]; then
+            echo "No changed source files for Biome check."
+            exit 0
+          fi
+
+          echo "Running Biome on changed files:"
+          printf ' - %s\n' "${FILES[@]}"
+          npx biome check "${FILES[@]}"
+
+      - name: TypeScript lint (root)
+        run: npm run lint
+
+      - name: TypeScript lint (container)
+        run: npm --prefix container run lint
+
+      - name: Unit tests with coverage
+        run: npx vitest run --coverage --config vitest.unit.config.ts

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx biome check --write --staged

package/CHANGELOG.md

@@ -2,12 +2,107 @@
 
 ## [Unreleased]
 
+No unreleased changes.
+
+## [0.2.7](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.7)
+
 ### Added
 
+- **Private approval slash command**: Added `/approve` with private (ephemeral) responses for `view`, `yes`, `session`, `agent`, and `no`, including optional `approval_id`.
+- **Static model context-window catalog**: Added curated context-window mappings (Claude/Gemini/GPT-5 families) plus family-aware model-id fallback matching for session status metrics without runtime model-list fetches.
+- **Discord command access + output controls**: Added runtime config support for `discord.commandMode`, `discord.commandAllowedUserIds`, `discord.textChunkLimit`, and `discord.maxLinesPerMessage`.
+- **HybridAI completion budget control**: Added `hybridai.maxTokens` runtime setting and request wiring (`max_tokens`) for container model calls.
+
 ### Changed
 
+- **Approval prompt visibility in Discord**: Channel responses now post a minimal “approval required” notice and move full approval details/decisions into private slash-command responses (`/approve`), matching the visibility pattern of `/status`.
+- **Discord command handler context**: Command execution now receives invoking `userId` and `username` so approval actions can be scoped to the requesting user.
+- **Discord slash command discoverability**: `/status` and `/approve` are now upserted globally for DM visibility while guild-only authorization checks remain enforced in servers.
+- **Discord free-mode message relevance gating**: Free-mode replies now skip low-signal acknowledgements/URL-only chatter and avoid jumping in when other users are explicitly mentioned.
+- **Status context usage reporting**: Session status now derives context usage from usage telemetry and static model context-window resolution instead of char-budget estimation only.
+- **Approval parsing and trust scoping**: Approval response parsing now handles mention-prefixed/batched messages, and network trust scopes now normalize hosts to broader domain scopes.
+- **Prompt dump diagnostics**: `data/last_prompt.jsonl` now includes media context plus allowed/blocked tool lists for richer debugging context.
+
 ### Fixed
 
+- **Google Images/Lens upload compatibility**: `browser_upload` now supports CSS-selector targets and automatically falls back from wrapper refs to detected `input[type="file"]` selectors when upload fails with non-input elements.
+- **Install-root container bootstrap**: CLI container readiness checks now resolve the package install root, preventing false build failures when invoked from non-package working directories.
+- **DM slash command registration regression**: Restored reliable discovery/usage of HybridClaw slash commands in Discord DMs.
+
+## [0.2.6](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.6)
+
+### Added
+
+- **Memory consolidation runtime controls**: Added `memory.decayRate` and `memory.consolidationIntervalHours` config support, plus gateway-managed periodic consolidation scheduling.
+- **Scheduler job runtime metadata**: Added optional `scheduler.jobs[].name` / `description`, persisted `nextRunAt`, and scheduler status surfaces for runtime visibility.
+- **Scheduler status API typing**: Added gateway status typing for scheduler jobs (`id`, `name`, `description`, `enabled`, `lastRun`, `lastStatus`, `nextRunAt`, `disabled`, `consecutiveErrors`).
+- **CLI version flag**: Added top-level `hybridclaw --version` / `-v`.
+- **Memory substrate architecture**: Added full SQLite-backed memory layers for structured KV (`kv_store`), semantic memory (`semantic_memories` with optional embeddings), knowledge graph (`entities` + `relations`), canonical cross-channel sessions, and usage events.
+- **Knowledge graph model + APIs**: Added typed entity/relation enums (with custom value support), relation traversal query APIs, and normalized serialization/parsing for graph properties.
+- **Canonical cross-channel sessions**: Added `canonical_sessions` persistence keyed by `(agent_id, user_id)` with rolling window retention, compaction summaries, and current-session exclusion support at recall time.
+- **Usage aggregation layer**: Added `usage_events` persistence plus aggregation queries (daily/monthly totals, by-agent, by-model, and daily breakdown) and gateway `usage` command surface.
+- **JSONL session export tools**: Added manual `export session [sessionId]` command and automatic compaction exports to `.session-exports/` for debugging and human review.
+- **Memory service abstraction**: Added `MemoryService` + pluggable backend interface for session/memory access, semantic recall, knowledge graph APIs, canonical recall, and compaction helpers.
+- **Memory consolidation engine**: Added consolidation engine + report model for periodic semantic decay operations.
+- **Discord command namespace expansion**: Added `usage` and `export` command parsing support.
+- **Coverage expansion**: Added comprehensive memory/DB unit tests (`tests/memory-service.test.ts`) and Discord parsing coverage for `usage`.
+
+### Changed
+
+- **Session compaction controls**: Added token-budget compaction knobs (`sessionCompaction.tokenBudget`, `sessionCompaction.budgetRatio`) and exposed them in config normalization + example config.
+- **Gateway runtime scheduling**: Gateway now starts/restarts memory consolidation when runtime config changes and stops it cleanly on shutdown.
+- **Heartbeat memory path**: Heartbeat turns now use `MemoryService` for session retrieval, prompt-memory context, and turn persistence.
+- **Scheduler observability depth**: Scheduler now tracks and persists `nextRunAt`, includes job labels in logs, and keeps runtime state synchronized for status consumers.
+- **Approval UX wording**: Red-tier approval prompt now instructs users to deny with `no` (alias `4`) instead of `skip`.
+- **Prompt wording clarity**: Session summary hook text now explicitly frames memory as compressed/recalled durable context.
+- **Runtime hygiene sweep**: Applied project-wide lint/import-order/format cleanup across gateway/runtime modules (audit, Discord channels, container runtime, onboarding, observability, skills/security, and Vitest configs) without behavior changes.
+- **Schema migrations**: Replaced ad-hoc bootstrapping with versioned `user_version` migrations (including forward-version guard) and migration records.
+- **Memory context injection**: Gateway prompt assembly now includes canonical cross-channel recall (summary + recent messages) while excluding the current session to avoid duplicate context.
+- **SQLite migration baseline**: Introduced schema version `4` with explicit `user_version` migrations for canonical and usage tables.
+- **SQLite concurrency defaults**: Database initialization now enforces `PRAGMA journal_mode=WAL` and `PRAGMA busy_timeout=5000` for better concurrent read behavior.
+- **Gateway memory integration**: Gateway flows now route session/history/memory operations through `MemoryService`, append canonical turns after successful responses, and record usage events from model telemetry.
+- **Compaction instrumentation**: Session maintenance now exports compacted snapshots to JSONL and records richer compaction diagnostics.
+- **Scheduled usage accounting**: Isolated scheduled task runs now record usage events for aggregation parity with interactive turns.
+
+## [0.2.5](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.5)
+
+### Added
+
+- **Trusted-coworker approval flow**: Added green/yellow/red approval runtime with contextual red prompts and support for `yes`, `yes for session`, `yes for agent`, and `skip` (including `1/2/3/4` shorthand replies).
+- **TUI approval selector**: Added an interactive TUI approval menu for pending red actions to reduce reply friction while preserving explicit consent.
+- **Agent-scoped approval trust persistence**: Added durable per-agent trust state in `.hybridclaw/approval-trust.json` for `yes for agent` decisions.
+
+### Changed
+
+- **Approval policy location**: Moved policy configuration from `.claude/policy.yaml` to `.hybridclaw/policy.yaml` and updated workspace bootstrap seeding/docs accordingly.
+- **Yellow-tier timing**: Increased yellow implicit approval countdown from 2s to 5s and simplified yellow narration text.
+- **CI quality gates**: Updated CI to install container dependencies and enforce changed-file Biome checks plus root/container TypeScript lint before running unit tests.
+
+### Fixed
+
+- **Pinned red trust behavior**: Pinned-red actions now correctly reject session/agent trust promotion and fall back to one-time approval only.
+- **Approval audit classification**: Approval audit events now mark `approved_agent` decisions as approved and include richer approval reason metadata.
+
+## [0.2.4](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.4)
+
+### Added
+
+- **Dynamic Discord self-presence states**: Added health-aware presence management that maps runtime state to Discord status (`online`, `idle`, `dnd`) and applies maintenance `invisible` presence during shutdown.
+- **Config-backed proactive scheduler jobs**: Added `scheduler.jobs[]` runtime jobs with `cron`/`every`/`at` schedules, `agent_turn`/`system_event` actions, and `channel`/`last-channel`/`webhook` delivery targets.
+- **Scheduler metadata persistence for config jobs**: Added atomic persisted state at `data/scheduler-jobs-state.json` for per-job `lastRun`, `lastStatus`, `consecutiveErrors`, `disabled`, and one-shot completion tracking.
+- **Discord humanization behaviors**: Added time-of-day/weekend pacing, conversation cooldown scaling after long back-and-forth, selective silence in active group channels, short-ack read-without-reply reactions, and reconnect startup staggering.
+
+### Changed
+
+- **Scheduler execution model**: Scheduler now co-schedules legacy DB tasks and config jobs in one timer loop with consistent due-time arming and persisted per-job error recovery behavior.
+- **Discord inbound debounce behavior**: Debounce batching now skips immediate flush delays for commands/media and keeps per-channel debounce tuning for normal chat messages.
+- **Documentation sync for Discord humanization/scheduler controls**: Updated README and site docs to cover health-driven presence, proactive job config, and human-like reply pacing behavior.
+
+### Fixed
+
+- **Uncanny Discord response timing**: Reduced robotic burst behavior by adding natural delay variation over long exchanges and reconnect bursts.
+- **Over-eager group replies**: Free-mode channels now avoid unnecessary follow-up replies when another participant likely already answered.
+
 ## [0.2.3](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.3)
 
 ### Added

package/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+## Development setup
+
+```bash
+npm install
+```
+
+`npm install` runs the `prepare` script and installs Husky git hooks.
+
+## Code quality checks
+
+```bash
+# TypeScript checks
+npm run typecheck
+npm run lint
+
+# Biome (lint + formatting + import sorting)
+npm run check
+
+# Apply Biome fixes to src
+npm run format
+```
+
+## Git hooks
+
+This repo uses Husky with a pre-commit hook:
+
+```bash
+npx biome check --write --staged
+```
+
+Before committing, stage your files (`git add ...`). The hook validates and auto-formats staged changes.

package/README.md

@@ -11,15 +11,17 @@ npm install -g @hybridaione/hybridclaw
 hybridclaw onboarding
 ```
 
-Latest release: [v0.2.3](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.2.3)
+Latest release: [v0.2.7](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.2.7)
 
-## What's new in v0.2.3
+## Release highlights (v0.2.7)
 
-- Added Discord guild channel policy controls with typed config: `discord.groupPolicy`, `discord.freeResponseChannels`, and `discord.guilds.<guildId>.channels.<channelId>.mode`
-- Added `/channel-mode` slash command to switch a channel between `off`, `mention`, and `free`
-- Added `!claw channel mode` and `!claw channel policy` command flows for in-chat policy changes
-- Enforced channel mode/policy in Discord trigger logic while keeping prefixed commands available
-- Updated status/activation labeling to reflect allowlist/disabled/mixed channel policy modes
+- Private approval flow via `/approve [view|yes|session|agent|no] [approval_id]` with ephemeral responses, and DM-ready global slash registration for `/status` + `/approve`.
+- Discord command access controls now support `discord.commandMode` (`public|restricted`) plus `discord.commandAllowedUserIds` (with legacy `commandUserId` compatibility).
+- Free-mode Discord replies now apply stronger relevance gating (for example short acknowledgements/URL-only chatter are skipped, and messages mentioning other users are de-prioritized).
+- `browser_upload` now supports selector targets and automatic fallback from wrapper refs to detected `input[type="file"]` elements.
+- HybridAI status/usage context metrics now use a curated static context-window catalog (Claude/Gemini/GPT-5) with family-aware fallback matching, and runtime supports `hybridai.maxTokens` for default completion budgeting.
+- Model-usage telemetry now captures cache read/write token counters where providers expose them, and prompt-dump diagnostics include media plus allowed/blocked tool context.
+- CLI container readiness checks now resolve the package install root to avoid non-root invocation failures.
 
 ## HybridAI Advantage
 
@@ -32,7 +34,7 @@ Latest release: [v0.2.3](https://github.com/HybridAIOne/hybridclaw/releases/tag/
 
 ## Architecture
 
-- **Gateway service** (Node.js) — shared message/command handlers, SQLite persistence, scheduler, heartbeat, web/API, and optional Discord integration
+- **Gateway service** (Node.js) — shared message/command handlers, SQLite persistence (KV + semantic + knowledge graph + canonical sessions + usage events), scheduler, heartbeat, web/API, and optional Discord integration
 - **TUI client** — thin client over HTTP (`/api/chat`, `/api/command`)
 - **Container** (Docker, ephemeral) — HybridAI API client, sandboxed tool executor, and preinstalled browser automation runtime
 - Communication via file-based IPC (input.json / output.json)
@@ -40,7 +42,7 @@ Latest release: [v0.2.3](https://github.com/HybridAIOne/hybridclaw/releases/tag/
 ## Quick start
 
 ```bash
-# Install dependencies (this also installs container deps via postinstall)
+# Install dependencies
 npm install
 
 # Run onboarding (also auto-runs on first `gateway`/`tui` start if API key is missing)
@@ -84,14 +86,18 @@ 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`)
-- Discord conversational UX: edit-in-place streaming responses, fence-safe chunking beyond Discord's 2000-char limit, typing keepalive, debounce batching, reply-chain-aware context, and concise attachment-first screenshot replies
+- 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
 
@@ -103,13 +109,36 @@ HybridClaw uses typed runtime config in `config.json` (auto-created on first run
 - 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` changes guild trigger behavior: `false` (default) replies only on mention/`!claw`; `true` replies to every user message in the channel
-- `discord.commandUserId` restricts `!claw <command>` admin commands to a single Discord user ID (all other messages still use normal chat handling)
-- `discord.commandsOnly` optional hard mode: if `true`, the bot ignores non-`!claw` messages and only accepts prefixed commands (optionally limited by `discord.commandUserId`)
-- `discord.groupPolicy` controls guild channel scope: `open` (default), `allowlist`, or `disabled`
+- `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.guilds.<guildId>.channels.<channelId>.mode` sets per-channel behavior to `off`, `mention`, or `free` (works with `allowlist` policy)
-- Discord slash commands: `/status` and `/channel-mode <off|mention|free>` (ephemeral replies)
+- `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)
@@ -117,6 +146,7 @@ HybridClaw uses typed runtime config in `config.json` (auto-created on first run
 - `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`:
 
@@ -313,7 +343,7 @@ The agent has access to these sandboxed tools inside the container:
 - `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`, `press`, `scroll`, `back`, `screenshot`, `pdf`, `close`)
+- `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:
 
@@ -343,6 +373,9 @@ HybridClaw also supports automatic session compaction with pre-compaction memory
 
 - 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:
 
@@ -385,6 +418,7 @@ Test layout and scopes:
 
 CLI runtime commands:
 
+- `hybridclaw --version` / `-v` — Print installed HybridClaw version
 - `hybridclaw gateway start [--foreground]` — Start gateway (backend by default; foreground with flag)
 - `hybridclaw gateway restart [--foreground]` — Restart managed gateway backend process
 - `hybridclaw gateway stop` — Stop managed gateway backend process
@@ -406,7 +440,11 @@ In Discord, use `!claw help` to see all commands. Key ones:
 - `!claw audit verify [sessionId]` — Verify audit hash chain integrity
 - `!claw audit search <query>` — Search structured audit history
 - `!claw audit approvals [n] [--denied]` — Show policy approval decisions
-- `!claw schedule add "<cron>" <prompt>` — Add scheduled task
+- `!claw usage [summary|daily|monthly|model [daily|monthly] [agentId]]` — Show token/cost aggregates
+- `!claw export session [sessionId]` — Export session snapshot as JSONL
+- `!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
 

package/SECURITY.md

@@ -40,6 +40,23 @@ Before tool execution, HybridClaw applies policy hooks that block known dangerou
 
 Implementation: [container/src/extensions.ts](./container/src/extensions.ts)
 
+### 2.1) Trusted-Coworker Approvals
+
+Tool actions are risk-tiered at runtime:
+
+- Green: execute silently (read/search/status checks)
+- Yellow: execute with narrated intent and a short interrupt window
+- Red: explicit user approval required (`yes` / `yes for session` / `yes for agent` / `skip`, or `1/2/3/4`)
+
+The policy layer is repo-controlled through `.hybridclaw/policy.yaml`:
+
+- `approval.pinned_red` (never auto-promoted high-risk actions)
+- `approval.workspace_fence` (no writes outside workspace fence)
+- `approval.max_pending_approvals` and `approval.approval_timeout_secs`
+- `audit.log_all_red` and `audit.log_denials`
+
+Implementation: [container/src/approval-policy.ts](./container/src/approval-policy.ts)
+
 ### 3) Container Isolation
 
 Tool execution runs inside Docker with sandbox constraints:

package/biome.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.5/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": ["**", "!!**/dist"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

package/config.example.json

@@ -1,5 +1,5 @@
 {
-  "version": 3,
+  "version": 5,
   "security": {
     "trustModelAccepted": false,
     "trustModelAcceptedAt": "",
@@ -15,21 +15,56 @@
     "presenceIntent": false,
     "respondToAllMessages": false,
     "commandsOnly": false,
+    "commandMode": "public",
+    "commandAllowedUserIds": [],
     "commandUserId": "",
     "groupPolicy": "open",
     "freeResponseChannels": [],
+    "textChunkLimit": 2000,
+    "maxLinesPerMessage": 17,
+    "humanDelay": {
+      "mode": "natural",
+      "minMs": 800,
+      "maxMs": 2500
+    },
+    "typingMode": "thinking",
+    "presence": {
+      "enabled": true,
+      "intervalMs": 30000,
+      "healthyText": "Watching the channels",
+      "degradedText": "Thinking slowly...",
+      "exhaustedText": "Taking a break",
+      "activityType": "watching"
+    },
+    "lifecycleReactions": {
+      "enabled": true,
+      "removeOnComplete": true,
+      "phases": {
+        "queued": "⏳",
+        "thinking": "🤔",
+        "toolUse": "⚙️",
+        "streaming": "✍️",
+        "done": "✅",
+        "error": "❌"
+      }
+    },
+    "ackReaction": "👀",
+    "ackReactionScope": "group-mentions",
+    "removeAckAfterReply": true,
+    "debounceMs": 2500,
+    "rateLimitPerUser": 0,
+    "rateLimitExemptRoles": [],
+    "suppressPatterns": ["/stop", "/pause", "brb", "afk"],
+    "maxConcurrentPerChannel": 2,
     "guilds": {}
   },
   "hybridai": {
     "baseUrl": "https://hybridai.one",
     "defaultModel": "gpt-5-nano",
     "defaultChatbotId": "",
+    "maxTokens": 4096,
     "enableRag": true,
-    "models": [
-      "gpt-5-nano",
-      "gpt-5-mini",
-      "gpt-5"
-    ]
+    "models": ["gpt-5-nano", "gpt-5-mini", "gpt-5"]
   },
   "container": {
     "image": "hybridclaw-agent",
@@ -45,6 +80,10 @@
     "intervalMs": 1800000,
     "channel": ""
   },
+  "memory": {
+    "decayRate": 0.1,
+    "consolidationIntervalHours": 24
+  },
   "ops": {
     "healthHost": "127.0.0.1",
     "healthPort": 9090,
@@ -68,7 +107,9 @@
   },
   "sessionCompaction": {
     "enabled": true,
-    "threshold": 120,
+    "tokenBudget": 100000,
+    "budgetRatio": 0.7,
+    "threshold": 200,
     "keepRecent": 40,
     "summaryMaxChars": 8000,
     "preCompactionMemoryFlush": {
@@ -106,5 +147,29 @@
     "ralph": {
       "maxIterations": 0
     }
+  },
+  "scheduler": {
+    "jobs": [
+      {
+        "id": "morning-standup",
+        "name": "Daily Standup Report",
+        "description": "Runs standup summary every weekday at 9am.",
+        "schedule": {
+          "kind": "cron",
+          "expr": "0 9 * * 1-5",
+          "tz": "America/New_York"
+        },
+        "action": {
+          "kind": "agent_turn",
+          "message": "Post a brief morning standup update for the team."
+        },
+        "delivery": {
+          "kind": "channel",
+          "channel": "discord",
+          "to": "123456789012345678"
+        },
+        "enabled": false
+      }
+    ]
   }
 }

package/container/package-lock.json

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

package/container/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hybridclaw-agent",
-  "version": "0.2.3",
+  "version": "0.2.7",
   "type": "module",
   "scripts": {
     "build": "tsc",