# @whalent/agent Unified CLI agent for [Whalent Memory](https://memory.whalent.com). Protocol reference: - [Agent Communication Protocol v3](docs/agent-protocol-v3.md) ## Install ```bash npm install -g @whalent/agent ``` Requires Node.js 20 or newer: ```bash npm install -g @whalent/agent --prefer-online --registry=https://registry.npmjs.org ``` Node.js 20 is still the safest choice on older Linux hosts. Newer Node.js releases can force native `node-pty` fallback builds that need newer C++ compilers when prebuilt binaries are unavailable. Self-updates stay in the npm prefix that owns the running `whalent` command, verify that prefix before restarting, and explicitly allow only the reviewed `node-pty` and `ssh2` lifecycle scripts required by the runtime. The Whalent packages themselves rely on the `engines` declaration and do not run install hooks. The HTTP, HTTPS, and SOCKS proxy paths are regression-tested on Node.js 20 and Node.js 26. Whalent keeps its `fetch` implementation and custom dispatchers on the same bundled Undici version so Node runtime upgrades do not break proxies. The official npm package `@moonshot-ai/kimi-code` requires Node.js 22.19.0 or newer, so the daemon checks that requirement before npm install/upgrade. An already-installed native Kimi executable can run under a daemon hosted by Node.js 20 and is not blocked by that package-install requirement. Kimi uses the official ACP transport, supports native `kimi login`, managed `kimi-code/k3` and `kimi-code/kimi-for-coding*` aliases, direct API-key `kimi-k3`, resume, approvals/questions, thinking/tool/plan streaming, and local history import. Codex SQLite history reads require the Whalent sqlite helper. The helper is a small Go binary cached under `~/.whalent-agent/helpers/sqlite`; if it is missing, cannot run, or is older than the required protocol, Codex history import is treated as unavailable instead of falling back to native npm sqlite bindings or `history.jsonl`. Set `WHALENT_SQLITE_HELPER_BASE_URL` to a release/CDN directory containing `sqlite-helper-0.1.7-manifest.json`, or set `WHALENT_SQLITE_HELPER_MANIFEST_URL` directly. By default the daemon checks Platform's release API at startup and every five minutes for newer `sqlite-helper`, `terminal-helper`, and enabled desktop `tray-helper` releases, then downloads and activates the returned manifests. All due helper identities are sent in one authenticated `check-batch` request; downloads and installs remain serial. A Platform without the batch route falls back to the legacy per-helper checks, while an edge/server failure remains one failed request and one warning. Helper releases are independent from daemon/npm releases. A guacd installation that already uses Whalent's managed component is updated through the same flow; system-installed or missing guacd remains an explicit user choice. ## Start Daemon ```bash whalent --token ``` The daemon connects to the Whalent Memory platform, fetches agent configurations, and auto-starts workers marked with `auto_restart`. It also accepts remote commands (upgrade, restart) via the gateway. Codex workers reserve their agent-scoped `CODEX_HOME` with a process-generation lease before starting app-server. Worker restart and shutdown wait for the whole native process tree to exit; daemon startup and periodic maintenance reclaim orphaned app-servers, including those whose old Agent directory was already deleted. A genuine live-writer conflict parks only that startup attempt and does not silently switch off the saved auto-restart setting. To allow a last-known-good startup while Platform is temporarily unreachable: ```bash whalent daemon --offline ``` `--offline` is a fallback, not a forced disconnected mode: the daemon still connects normally when possible. After every successful agent-config inventory fetch (and each authenticated config push), it atomically replaces the private `agent-config-cache.json` in the active account profile. On a transient network, timeout, rate-limit, or 5xx startup failure, the daemon starts runnable workers from that same-machine snapshot and keeps reconnecting in the background. Explicit 401/403/404 responses never use the cache. A first-ever launch with no snapshot remains online-waiting and starts no cached workers. The equivalent environment switch is `WHALENT_OFFLINE=1`; `whalent status` reports whether the active config source is `platform`, `cache`, or `none`. On Windows, macOS, and graphical Linux sessions, daemon mode installs and starts the native `tray-helper` automatically. Its menu shows the current Whalent login, Gateway/worker status, opens Whalent Memory or today's daemon log, checks and installs the latest Platform-approved Agent release, and can restart or stop the daemon. **主动上报日志** directly collects the recent logs; double-clicking the icon where the desktop supports it, or choosing **Status & diagnostics**, opens a loopback-only page with the same action and its detected error reason/count. Captured logs are redacted, classified, gzipped, and uploaded (up to seven rotating files plus bounded local crash/status records). The Platform keeps one compressed report per account/machine/report kind and never extracts it; the completion notification and the diagnostics page show the Platform **report ID** (stable per account/machine, always pointing at the latest upload) so users can quote it to support, and support can also trigger a collection remotely from the admin console. Headless and SSH sessions skip the tray without affecting daemon work. To specify a custom gateway: ```bash whalent --token --gateway wss://your-server/gw/sdk/ws ``` ## MCP Gateway Routing When starting the legacy `whalent mcp` subcommand directly, pass the gateway routing instance with `--gateway-instance-id` or `WHALENT_GATEWAY_INSTANCE_ID`. The older `--app-id` and `WHALENT_APP_ID` forms remain accepted as deprecated input aliases for existing integrations. For Codex workers, every streamable HTTP MCP server rendered by Whalent Agent receives a dedicated versioned header: ```text User-Agent: whalent-agent-mcp/ ``` This identity is separate from Codex's own HTTP client defaults so an MCP edge can apply an explicit allow rule and correlate startup failures to the installed Whalent Agent version. Stdio MCP servers are unchanged. ## License Copyright © 2025 Whalent. All rights reserved.