@askalf/agent - npm Package Compare versions

Comparing version 3.3.0 to 3.3.1

package.json

 {
   "name": "@askalf/agent",
-  "version": "3.3.0",
-  "description": "Connect any device to an AI workforce that thinks, heals, remembers, and evolves. Nervous system signals, immune system alerts, auto-reconnect, capabilities scan. One command to install as a persistent service.",
+  "version": "3.3.1",
+  "description": "Connect any device to your askalf fleet. A WebSocket connector that registers a machine and runs the shell or Claude Code tasks the fleet dispatches, streaming results back. Installs as a system service; auto-reconnect, heartbeat, capability scan.",
   "type": "module",
@@ -6,0 +6,0 @@ "main": "dist/index.js",

README.md

@@ -0,9 +1,26 @@
+<div align="center">
+
 # @askalf/agent
 
-### Connect any device to the organism.
+connect any device to your askalf fleet
 
-WebSocket bridge that registers your machine as a node in the AskAlf fleet. Once connected, autonomous agents dispatch tasks to your device — executed via Claude CLI or native shell. Your device becomes part of a AI workforce that thinks, heals, remembers, and evolves.
+[![npm](https://img.shields.io/npm/v/@askalf/agent?style=flat-square&color=00ff88&label=npm&labelColor=020612)](https://www.npmjs.com/package/@askalf/agent)
+[![Node](https://img.shields.io/node/v/@askalf/agent?style=flat-square&color=00ff88&label=node&labelColor=020612)](https://nodejs.org)
+[![License](https://img.shields.io/badge/MIT-00ff88?style=flat-square&label=license&labelColor=020612)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/askalf/agent/ci.yml?style=flat-square&label=CI&labelColor=020612)](https://github.com/askalf/agent/actions)
 
-Part of [AskAlf](https://askalf.org) — an AI workforce that thinks, heals, remembers, and evolves with a nervous system, immune system, and collective memory.
+**[askalf.org](https://askalf.org)** · **[@ask_alf](https://x.com/ask_alf)** · **[Changelog](CHANGELOG.md)**
 
+</div>
+
+---
+
+## What this is
+
+`@askalf/agent` is the device-side half of an [askalf](https://github.com/askalf/platform) workforce. You run it on a machine you want the fleet to be able to act on — a server, a laptop, a remote box — and it opens a persistent WebSocket to your askalf forge. From then on, agents in the fleet can run shell commands or Claude Code on that machine, see what's installed, and stream results back.
+
+It's not a chat client, an MCP server, or an autonomous coder. It's a connector — the substrate side of "agents can do real things on real computers."
+
+---
+
 ## Install
@@ -15,111 +32,83 @@
 
-## One Command Setup
+Requires Node 22+. For Claude Code execution, install `@anthropic-ai/claude-code` globally as well.
 
+## One-command setup
+
 ```bash
-askalf-agent connect <your-api-key> --url ws://your-server:3005 --name prod-box --install
+askalf-agent connect <api-key> --url ws://your-forge:3005 --name laptop --install
 ```
 
-That's it. Config saved, service installed, runs on boot. Close the terminal — it keeps running.
+Writes config, registers with the forge, installs a system service that auto-starts. Close the terminal — the agent keeps running.
 
-## What It Does
+---
 
-When connected, your device:
+## Commands
 
-1. **Registers** with the fleet via WebSocket
-2. **Scans capabilities** — CPU, RAM, 18 tools checked, Claude CLI detection
-3. **Receives tasks** dispatched by the fleet's unified scheduler
-4. **Executes autonomously** — Claude CLI or native shell
-5. **Emits signals** — confidence, urgency, stuck status flow to the nervous system
-6. **Receives alerts** — incident notifications, agent messages, signal broadcasts
-7. **Reports results** — output, tokens, cost, duration back to the fleet
-8. **Streams progress** — the dashboard sees output in real-time
+| Command | What it does |
+|---|---|
+| `connect <key>` | Connect to a forge. Add `--install` to also register as a service. |
+| `disconnect` | Stop the running daemon. |
+| `status` | Show connection + service state. |
+| `scan` | List the device's discoverable capabilities (CPU, RAM, installed tools, Claude Code presence). |
+| `doctor` | Diagnose common setup issues and offer fixes. |
+| `daemon` | Run in foreground. Mostly useful for debugging — `--install` is the normal path. |
+| `install-service` | Install the service after a `connect` without `--install`. |
+| `uninstall-service` | Remove the service. |
 
-## Nervous System Integration
+### Options
 
-The agent participates in the fleet's nervous system:
+| Flag | Description | Default |
+|---|---|---|
+| `--url <url>` | Forge WebSocket URL | `wss://askalf.org` |
+| `--name <name>` | Device display name in the dashboard | system hostname |
+| `--install` | Install as a service after connecting | — |
+| `-v, --version` | Print version | — |
+| `-h, --help` | Print help | — |
 
-```
-Fleet Chief  ──signal──>  Your Device  ──signal──>  Watchdog
-     │                         │                        │
-     └──── agent:message ──────┘                        │
-                               │                        │
-                               └── incident:alert ──────┘
-```
+---
 
-- **Emits signals** after every execution (success, stuck, urgency)
-- **Receives agent messages** with urgency levels (CRITICAL / HIGH / INFO)
-- **Receives incident alerts** when the immune system activates
-- **Receives signal broadcasts** from fleet-wide awareness
+## Service install
 
-## Service Installation
+| OS | Backend | Auto-start |
+|---|---|---|
+| Linux | systemd unit | on boot |
+| macOS | launchd plist | on login |
+| Windows | Scheduled Task (or `nssm` if installed) | on login |
 
-```bash
-askalf-agent install-service
-```
+---
 
-| OS | Service Type | Auto-start |
-|----|-------------|------------|
-| **Linux** | systemd unit | On boot |
-| **macOS** | launchd plist | On login |
-| **Windows** | Scheduled Task (or nssm) | On login |
+## How it works
 
-## Commands
-
 ```
-askalf-agent connect <key>         Connect to fleet
-askalf-agent connect <key> --install  Connect + install as service
-askalf-agent doctor                Diagnose and fix setup issues
-askalf-agent install-service       Install as OS service
-askalf-agent uninstall-service     Remove OS service
-askalf-agent daemon                Background daemon
-askalf-agent status                Connection + service status
-askalf-agent scan                  Local capabilities scan
-askalf-agent disconnect            Stop daemon
+your device                          askalf forge
+┌──────────────┐                  ┌──────────────────────┐
+│ askalf-agent │ ──── wss ──────► │ dispatcher           │
+│              │ ◄─── task ────── │ agent fleet          │
+│  shell       │ ──── stream ───► │ dashboard / discord  │
+│  Claude Code │ ──── result ───► │                      │
+│  device tools│                  └──────────────────────┘
+└──────────────┘
 ```
 
-## Options
+- **Heartbeat** every 30s with memory and uptime.
+- **Auto-reconnect** with backoff after a disconnect.
+- **Capability scan** on registration and on demand — reports CPU, RAM, OS, and presence of `git`, `docker`, `node`, `npm`, `python`, `gh`, `claude`, and more.
+- **5-minute subprocess timeout** by default per task.
+- **Streaming output** — the dashboard sees what the task prints, line by line, while it's still running. A final result with token + cost numbers follows.
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--url <url>` | Server WebSocket URL | `wss://askalf.org` |
-| `--name <name>` | Device display name | System hostname |
-| `--install` | Install as service after connecting | |
-| `-v, --version` | Show version | |
-| `-h, --help` | Show help | |
+---
 
-## How It Works
+## Programmatic usage
 
-```
-Your Device                     AskAlf Fleet
-┌──────────────┐    WSS     ┌────────────────────┐
-│ askalf-agent  │◄──────────►│ Forge Orchestrator  │
-│              │            │ Unified Scheduler   │
-│ Claude CLI   │  signals   │ Nervous System      │
-│ Shell        │◄──────────►│ Immune System       │
-│ Your Tools   │  messages  │ Collective Memory   │
-└──────────────┘            └────────────────────┘
-```
-
-- **Heartbeat** every 30s with memory usage and uptime
-- **Auto-reconnect** with exponential backoff (2s → 60s max)
-- **Capabilities scan** — responds to server requests with full system info
-- **10 minute timeout** per execution (configurable)
-- **Progress streaming** — real-time output to dashboard
-
-## Programmatic Usage
-
 ```typescript
+import os from 'node:os';
 import { AgentBridge, scanCapabilities } from '@askalf/agent';
 
-const caps = scanCapabilities();
-console.log(caps);
-// { cpu_cores: 8, tools: ['shell', 'git', 'docker', ...], claude_cli: true, ... }
-
 const bridge = new AgentBridge({
-  apiKey: 'your-api-key',
-  url: 'ws://your-server:3005',
-  deviceName: 'my-server',
-  hostname: 'prod-01',
-  os: 'Linux 6.1',
-  capabilities: caps,
+  apiKey: process.env.ASKALF_AGENT_KEY!,
+  url: 'wss://your-forge.example.com',
+  deviceName: 'edge-laptop',
+  hostname: os.hostname(),
+  os: `${os.type()} ${os.release()}`,
+  capabilities: scanCapabilities(),
 });
@@ -130,15 +119,45 @@
 
+Most users want the CLI. This is for embedding the connector in something larger.
+
+---
+
+## Known limitations
+
+Building in public — real today:
+
+- **systemd restart can corrupt the stored apiKey (Linux).** A `systemctl restart askalf-agent` re-encrypts the config and, in some cases, leaves the apiKey unrecoverable. Until the upstream fix lands, recover with `askalf-agent disconnect && askalf-agent connect <key> --install`.
+- **Per-user/machine key binding.** Keys are bound to the user that ran `connect` on the machine that ran it. Switching Linux users on the same box means minting a new key, not reusing the old one.
+- **Older `ws` versions reject base64-encoded API keys as subprotocols.** If you embed `AgentBridge` in a project with an older `ws`, pin to `^8.20.0` or move the key to the `Authorization` header.
+
+---
+
 ## Requirements
 
-- Node.js 22+
-- [Claude Code](https://claude.com/claude-code) for AI execution (`npm i -g @anthropic-ai/claude-code`)
-- An AskAlf instance (`npx create-askalf` or `curl -fsSL https://get.askalf.org | bash`)
+- Node 22+
+- [`@anthropic-ai/claude-code`](https://www.npmjs.com/package/@anthropic-ai/claude-code) globally installed, if you want the fleet to run Claude Code tasks here
+- A reachable askalf forge (`npx create-askalf` or `curl -fsSL https://get.askalf.org | bash`)
 
-## Links
+---
 
-- [AskAlf](https://askalf.org) — Landing page
-- [Demo](https://demo.askalf.org) — Try it free
-- [GitHub](https://github.com/askalf/platform) — Platform source
-- [Discord](https://discord.gg/fENVZpdYcX) — Community
+## Related projects
 
-MIT — [askalf.org](https://askalf.org)
+| Project | What it does |
+|---|---|
+| **[askalf/platform](https://github.com/askalf/platform)** | The forge + dashboard the agent connects to. |
+| **[@askalf/dario](https://github.com/askalf/dario)** | Local LLM router. Use your Claude Max subscription as an API. |
+| **[@askalf/hands](https://github.com/askalf/hands)** | Computer-use SDK. Agents drive a browser. |
+| **[@askalf/deepdive](https://github.com/askalf/deepdive)** | Deep-research SDK with citation tracking. |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<div align="center">
+
+**[askalf.org](https://askalf.org)** · **[npm](https://www.npmjs.com/package/@askalf/agent)** · **[@ask_alf](https://x.com/ask_alf)**
+
+</div>

New alerts

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

Found 1 instance in 1 package

Fixed alerts

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

143713

0.88%

Number of lines in readme file

162

13.29%

No dependency changes