# @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.5-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.
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 <YOUR_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.

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. Double-clicking the icon where the desktop supports it, or choosing
**Status & diagnostics**, opens a
loopback-only page where the user can collect, redact, gzip, and upload the three
most recent rotating logs. The Platform keeps one compressed report per
account/machine and never extracts it. Headless and SSH sessions skip the tray
without affecting daemon work.

To specify a custom gateway:

```bash
whalent --token <YOUR_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/<agent-version>
```

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.