@vclawhub/vclaw 0.2.7 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +19 -281
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,83 +1,41 @@
1
- # VClaw Agent — Local Agentic Mesh Wrapper
1
+ # VClaw Hub — Local Agentic Mesh
2
2
 
3
3
  > **One command to set up pi.dev + pi-web.dev + NATS leaf node on any machine.**
4
4
 
5
- This project is the orchestration layer that wraps three open-source components into a single, self-contained developer playground. Run one `curl | sh` and you get a persistent AI agent workspace with local NATS messaging, a browser-based control plane, and optional connectivity to the [vchat.email](https://vchat.email) agent network.
5
+ Run one `curl | sh` and you get a persistent AI agent workspace with local NATS messaging, a browser-based control plane, and optional connectivity to the vchat.email agent network.
6
6
 
7
7
  ---
8
8
 
9
9
  ## Quick Start
10
10
 
11
11
  ```bash
12
- # Install everything: NATS server, pi.dev CLI, pi-web.dev, vchat-agent
12
+ # Install everything: NATS server, pi.dev CLI, pi-web.dev
13
13
  curl -fsSL https://vclawhub.com/install | sh
14
14
 
15
- # Launch the local mesh (NATS + pi-web.dev)
15
+ # Launch the local mesh
16
16
  vclaw-up
17
17
 
18
18
  # Optional: join the vchat.email agent network
19
19
  vclaw-up --onboard you@email.com
20
20
  ```
21
21
 
22
- That's it. Open a browser to `https://pi-web.dev/?connect=127.0.0.1:4222` and start chatting with your AI agent from any device.
22
+ That's it. Open `http://localhost:4321` in your browser and start chatting with your AI agent from any device on your local network.
23
23
 
24
24
  ---
25
25
 
26
26
  ## What You Get
27
27
 
28
- After install, your machine has:
29
-
30
- | Component | Binary | Purpose |
31
- |-----------|--------|---------|
32
- | **NATS Server** | `nats-server` | Local message broker on `127.0.0.1:4222` with JetStream for offline caching |
33
- | **pi.dev CLI** | `pi` | Terminal AI agent with skill system, multi-provider LLM support |
34
- | **PI WEB** | `pi-web` / `pi-web-sessiond` | Browser-based agent workspace, project management, session persistence |
35
- | **vchat-agent** | `vchat-agent` (via `npx`) | Identity & onboarding CLI for the vchat.email agent network |
36
- | **vclaw-up** | `~/.local/bin/vclaw-up` | Unified orchestrator — starts everything with one command |
28
+ | Component | What It Is |
29
+ |-----------|-----------|
30
+ | **NATS Server** | Local message broker on `127.0.0.1:4222` with JetStream for offline caching |
31
+ | **pi.dev CLI** (`pi`) | Terminal AI agent with skill system, multi-provider LLM support |
32
+ | **PI WEB** | Browser-based agent workspace at `http://localhost:4321` |
33
+ | **vclaw-up** | Unified orchestrator — starts everything with one command |
37
34
 
38
35
  Installed to `~/.local/bin/` with data in `~/.local/share/vclaw/`.
39
36
 
40
37
  ---
41
38
 
42
- ## Architecture
43
-
44
- ```
45
- ┌──────────────────────────────────────────────┐
46
- │ Browser (any device) │
47
- │ laptop · desktop · tablet · phone │
48
- └──────────────────────┬───────────────────────┘
49
- │ HTTPS + WebSocket
50
- ▼
51
- ┌──────────────────────────────────────────────┐
52
- │ PI WEB (pi-web.dev) │
53
- │ Fastify HTTP server · Real-time WebSocket │
54
- │ Session daemon · Project management │
55
- └──────────┬───────────────────┬────────────────┘
56
- │ Unix socket/TCP │ WebSocket
57
- ▼ ▼
58
- ┌──────────────────┐ ┌────────────────────────┐
59
- │ Pi Agent (pi) │ │ NATS Leaf Node │
60
- │ LLM + skills │ │ 127.0.0.1:4222 │
61
- │ Tavily, TTS, │ │ JetStream (offline) │
62
- │ PDF, Kolors... │ │ Optional: upstream to │
63
- └──────────────────┘ │ nats.vchat.email:443 │
64
- └──────────┬─────────────┘
65
- │ (if enabled)
66
- ┌──────────▼─────────────┐
67
- │ vchat.email Mesh │
68
- │ agents.vchat.email │
69
- │ A2A · fleet mgmt │
70
- └────────────────────────┘
71
- ```
72
-
73
- The stack uses a **local-first architecture**:
74
- - **NATS** runs locally with JetStream — no internet required for core operation.
75
- - **PI WEB** connects to NATS via WebSocket for real-time agent communication.
76
- - **Pi Agent** runs LLM interactions with loaded skills.
77
- - **vchat.email** is optional — only if you want agent-to-agent networking across devices.
78
-
79
- ---
80
-
81
39
  ## Daily Use
82
40
 
83
41
  ### Launch the stack
@@ -86,18 +44,14 @@ The stack uses a **local-first architecture**:
86
44
  vclaw-up
87
45
  ```
88
46
 
89
- Opens `https://pi-web.dev/?connect=127.0.0.1:4222` in your browser. NATS and the agent loop run in the background.
47
+ Opens `http://localhost:4321` in your browser. NATS and pi-web run in the background.
90
48
 
91
49
  ### Watch agent messages in real time
92
50
 
93
- Open another terminal:
94
-
95
51
  ```bash
96
52
  nats sub ">"
97
53
  ```
98
54
 
99
- You'll see JSON packets fly by as your agent searches the web, generates images, or processes documents.
100
-
101
55
  ### Stop everything
102
56
 
103
57
  ```bash
@@ -122,238 +76,22 @@ pi "/help"
122
76
 
123
77
  ## Joining the vchat.email Network
124
78
 
125
- For agent-to-agent collaboration, fleet management, and cross-device persistence, join the vchat.email mesh:
79
+ For agent-to-agent collaboration, fleet management, and cross-device persistence:
126
80
 
127
81
  ```bash
128
- # Interactive onboarding
129
82
  vclaw-up --onboard you@email.com
130
-
131
- # Or standalone
132
- vchat-onboard.sh you@email.com
133
83
  ```
134
84
 
135
- **The flow:**
85
+ The flow:
136
86
  1. Generates an ED25519 Nkey identity for your agent.
137
- 2. Introduces it to vgate (`api.vchat.email`) as a pending agent.
87
+ 2. Introduces it to vgate as a pending agent.
138
88
  3. Opens your browser to `https://login.vchat.email/a/<hash>`.
139
- 4. You log in and approve the agent at `agents.vchat.email`.
89
+ 4. You log in and approve the agent.
140
90
  5. Credentials saved to `~/.vchat/credentials.json`.
141
- 6. Your agent now appears on the mesh — discoverable, addressable, delegatable.
142
-
143
- Once onboarded, agents communicate on NATS subjects like `agents.hb.pi.<email>.<session>`, `agents.prompt.pi.<email>.<session>`, and `agents.a2a.<target_email>`.
144
-
145
- ---
146
-
147
- ## Installation Options
148
-
149
- ### Option A: One-liner (recommended)
150
-
151
- ```bash
152
- curl -fsSL https://vclawhub.com/install | sh
153
- ```
154
-
155
- Detects your OS/arch, downloads NATS server, pi.dev CLI, vclaw binary, and the `vclaw-up` orchestrator. Also installs `@vchatemail/agent` for optional network onboarding.
156
-
157
- ### Option B: From source
158
-
159
- Source will be published at `https://github.com/chatek` — check back soon.
160
-
161
- ### Option C: Manual component install
162
-
163
- ```bash
164
- # NATS Server
165
- npm install -g nats-server
166
-
167
- # Pi Agent
168
- npm install -g @earendil-works/pi-coding-agent
169
-
170
- # PI WEB
171
- npm install -g @jmfederico/pi-web
172
- pi-web install
173
-
174
- # vchat-agent (optional)
175
- npm install -g @vchatemail/agent
176
- ```
177
-
178
- ---
179
-
180
- ## Agent Skills
181
-
182
- Skills live in `~/.pi/agent/skills/`. This project ships with 9 curated skills:
183
-
184
- | Skill | What It Does | API Key |
185
- |-------|-------------|---------|
186
- | **Tavily Search** | Real-time web search with relevance filtering | `TAVILY_API_KEY` |
187
- | **Brave Search** | Alternative web search | `BRAVE_API_KEY` |
188
- | **PDF Reader** | Text + scanned PDF extraction via vision models | (uses LLM provider) |
189
- | **Edge TTS** | Text-to-speech via Microsoft Edge engine (no API key) | None |
190
- | **Kolors Image** | Local text-to-image generation (Kuaishou) | None (GPU +12GB VRAM) |
191
- | **Hyperframes** | HTML/CSS → deterministic MP4 video | None |
192
- | **Skywork Search** | Chinese/English web search | `SKYWORK_API_KEY` |
193
- | **Bun Registry** | Publish CLI tools to npm/Bun registry | None (npm login) |
194
- | **vchat Network** | Join the vchat.email agent mesh | None (email + browser) |
195
-
196
- Skills are documented as `SKILL.md` files in each directory — Pi Agent reads them automatically.
197
-
198
- ---
199
-
200
- ## Project Structure
201
-
202
- ```
203
- vclaw-agent/
204
- ├── install.sh # One-liner installer
205
- ├── vclaw-up # Stack orchestrator
206
- ├── src/ # Bun CLI source
207
- ├── dist/ # Bun build output (gitignored)
208
- ├── package.json # @vclawhub/vclaw (publishable to npm)
209
- ├── .env.d/ # Local secrets (gitignored)
210
- │ ├── vclawhub.env # npm publish token (VCLAW_NPM_TOKEN)
211
- │ └── _template.env # Template for new env vars
212
- ├── config/
213
- │ └── nats-leaf.conf # Canonical NATS leaf-node config
214
- ├── scripts/
215
- │ └── vchat-onboard.sh # vchat.email network join
216
- ├── deploy/ # OS provisioning roles
217
- │ └── roles/
218
- │ ├── 01-nats-leaf.sh # NATS leaf node setup
219
- │ ├── 02-pi-agent.sh # Pi Agent + skills
220
- │ ├── 03-pi-web.sh # PI WEB + session daemon
221
- │ └── 07-vclawos-agent.sh # @vclawos/agent build & link
222
- ├── vendors/
223
- │ ├── pi/ # pi-mono monorepo (vendored submodule)
224
- │ ├── pi-web/ # PI WEB (vendored submodule)
225
- │ ├── nats-s3/ # NATS S3 storage plugin
226
- │ └── synadia-nats-pi-channel/ # @synadia-ai/nats-pi-channel (vendored tarball)
227
- ├── vclaw-pkg/ # @vclawos/* npm packages
228
- │ └── packages/
229
- │ ├── agent/ # @vclawos/agent runtime
230
- │ ├── pi-mono/ # @vclawos/pi-mono wrapper
231
- │ └── pi-web/ # @vclawos/pi-web wrapper
232
- ├── .pi/agent/skills/ # 9 agent skill packages
233
- ├── .github/workflows/
234
- │ └── publish.yml # CI/CD — Bun + pnpm parallel publish
235
- └── docs/
236
- ├── NODES_members.md # Node inventory & deployment profiles
237
- ├── archive/ # Archived reference docs
238
- │ ├── ALPHA.md, BRIEFING.md, VCHAT_idp.md, RELEASES.md
239
- │ └── onboard.sh # Legacy onboard script
240
- ├── help/ # Archived HTML pages & proxy scripts
241
- ├── things/ # IoT / device reference
242
- └── firmwares/ # NanoPi R5C firmware
243
- ```
91
+ 6. Your agent appears on the mesh — discoverable, addressable, delegatable.
244
92
 
245
93
  ---
246
94
 
247
- ## Publishing to npm
248
-
249
- Two groups of packages publish to the npm registry:
250
-
251
- | Package | Build Tool | How to Install |
252
- |---------|-----------|----------------|
253
- | **`@vclawhub/vclaw`** (root — wrapper CLI) | **Bun** `bun build --target=bun` | `bunx @vclawhub/vclaw install` |
254
- | **`@vclawos/agent`**, `pi-mono`, `pi-web` (vclaw-pkg/) | **pnpm** (TypeScript → tsc) | `npm install @vclawos/agent` |
255
-
256
- A publish token is stored in `.env.d/vclawhub.env` under `VCLAW_NPM_TOKEN`.
257
-
258
- ### Local publish: wrapper CLI (Bun)
259
-
260
- ```bash
261
- # Build and publish the root wrapper package
262
- source .env.d/vclawhub.env
263
- export NPM_TOKEN="${VCLAW_NPM_TOKEN}"
264
- bun run build # bun build ./src/cli.ts → dist/cli.js
265
- bun publish --access public
266
- ```
267
-
268
- Users can then install and run it in one step:
269
-
270
- ```bash
271
- # Global install
272
- bun install -g @vclawhub/vclaw
273
- vclaw-agent up
274
-
275
- # Or direct execution (no install)
276
- bunx @vclawhub/vclaw install
277
- bunx @vclawhub/vclaw up --onboard you@email.com
278
- ```
279
-
280
- ### Local publish: vclaw-pkg packages (pnpm)
281
-
282
- ```bash
283
- cd vclaw-pkg
284
- source ../.env.d/vclawhub.env
285
- export NPM_TOKEN="${VCLAW_NPM_TOKEN}"
286
- pnpm publish:all
287
- ```
288
-
289
- ### CI/CD — GitHub Actions
290
-
291
- The workflow at `.github/workflows/publish.yml` runs automatically when a `v*` tag is pushed. It publishes **both** groups in parallel:
292
-
293
- ```mermaid
294
- graph LR
295
- A[git tag v0.1.0] --> B[Workflow triggers]
296
- B --> C[publish-root job]
297
- B --> D[publish-packages job]
298
- C --> E[Bun build src/cli.ts]
299
- C --> F[publish @vclawhub/vclaw]
300
- D --> G[pnpm build all]
301
- D --> H[pnpm test]
302
- D --> I[publish @vclawos/*]
303
- E --> J[create-release job]
304
- F --> J
305
- I --> J
306
- J --> K[GitHub Release with changelog]
307
- ```
308
-
309
- #### Step-by-step: Add the secret to GitHub
310
-
311
- 1. Go to **repo Settings → Secrets and variables → Actions**.
312
- 2. Click **New repository secret**.
313
- 3. **Name:** `VCLAW_NPM_TOKEN`
314
- 4. **Value:** the automation token from `.env.d/vclawhub.env`
315
- 5. Click **Add secret**.
316
-
317
- That's it — the workflow reads it automatically.
318
-
319
- #### To trigger a publish
320
-
321
- ```bash
322
- # Tag the current commit and push
323
- git tag v0.1.0
324
- git push origin v0.1.0
325
- ```
326
-
327
- The workflow then:
328
- 1. **publish-root** — Bun-bundles `src/cli.ts` → `dist/cli.js`, publishes `@vclawhub/vclaw`
329
- 2. **publish-packages** — pnpm installs, builds, tests, and publishes all `@vclawos/*` packages
330
- 3. **create-release** — creates a GitHub Release with auto-generated notes (runs after both succeed)
331
-
332
- #### Manual trigger
333
-
334
- You can also run the workflow manually from the GitHub Actions UI by selecting **Run workflow** and entering a version tag.
335
-
336
- ### Skill: bun-registry-publish
337
-
338
- Pi Agent has a built-in skill (`~/.pi/agent/skills/bun-registry-publish/SKILL.md`) that walks through the full publish flow step by step — from `bun init` to `bunx` consumption.
339
-
340
- ---
341
-
342
- ## References
343
-
344
- | Resource | URL |
345
- |----------|-----|
346
- | Pi.dev | [https://pi.dev](https://pi.dev) |
347
- | PI WEB | [https://pi-web.dev](https://pi-web.dev) |
348
- | NATS Server | [https://nats.io](https://nats.io) |
349
- | vchat.email | [https://vchat.email](https://vchat.email) |
350
- | @vchatemail/agent (npm) | [https://www.npmjs.com/package/@vchatemail/agent](https://www.npmjs.com/package/@vchatemail/agent) |
351
- | @vclawos/agent (npm) | [https://www.npmjs.com/package/@vclawos/agent](https://www.npmjs.com/package/@vclawos/agent) |
352
- | @synadia-ai/nats-pi-channel (pi.dev) | [https://pi.dev/packages/@synadia-ai/nats-pi-channel](https://pi.dev/packages/@synadia-ai/nats-pi-channel) |
353
- | @synadia-ai/nats-pi-channel (GitHub) | [https://github.com/synadia-ai/nats-pi-channel](https://github.com/synadia-ai/nats-pi-channel) |
354
- | VClaw Hub Install | `https://vclawhub.com/install` (serves `install.sh`) |
355
-
356
- ---
95
+ ## License
357
96
 
358
- > **VClaw Agent** — MIT Licensed.
359
- > Build your own Local Agentic Mesh: pi.dev + pi-web.dev + NATS leaf node, one command away.
97
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vclawhub/vclaw",
3
- "version": "0.2.7",
3
+ "version": "0.2.8",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "VClaw Agent — one-command setup for pi.dev + pi-web.dev + NATS leaf node + vchat.email network",