@beevibe/daemon 0.1.0 → 0.1.2

package/README.md

@@ -1,354 +1,144 @@
-# beevibe
+# @beevibe/daemon
 
-> A self-hosted runtime for autonomous AI agent teams. Tasks flow between agents through hierarchy and peer mesh; memory carries forward; humans review and approve from a dashboard.
+The local worker. Runs on a user's machine, registers with the api as a `(daemon, runtime)` pair, then claims sessions whose agent's `preferred_runtime_id` matches and spawns the local CLI (`claude`, etc.) to fulfill them. Streams steps back via `/runtime/events` and finalizes with `/runtime/done`.
 
-beevibe lets you run a small organization of Claude Code agents that delegate to each other, negotiate, escalate to humans when stuck, and build up shared memory over time. You provide the agents (a captain and a few ICs is a fine starting point), the work, and the review judgment. The platform handles the rest.
+The daemon never proxies MCP tool calls — the spawned CLI calls the api's `/mcp` endpoint directly using the `bv_a_` agent token written into its workspace's `mcp-config.json`. The daemon only writes that file and supervises the subprocess.
 
-It's open source under the Apache-2.0 license. Everything is self-hosted: your Postgres, your `claude` CLI binaries, your filesystem.
+For full setup, see the [root README](../../README.md).
 
-## Deploy
+## Run it
 
-One-click cloud deploy:
+Three subcommands. `setup` once; `start` to claim sessions; `update` for the brew/curl install path.
 
-[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template?repo=https://github.com/beevibe-ai/beevibe)
-
-This brings up `api` + `scheduler` + `web` services and a managed Postgres in one click. After the deploy finishes, set `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` in the project's Variables tab, then visit the web service's public URL to sign up. You'll be prompted to install the local daemon as part of the welcome flow.
-
-Self-host options:
-
-- **Docker / docker-compose** — `git clone && docker compose up` against a tagged release (see [Self-hosting](#self-hosting) below).
-- **Manual** — `pnpm install && pnpm build && pnpm start` per service against your own Postgres.
-
-The repo and its tagged releases are the source of truth. The Railway button is a convenience layer; you can deploy the same code to Fly, Render, Coolify, k8s, or any container host.
+```bash
+# 1. one-time registration with an api server
+beevibe-daemon setup --api https://api.beevibe.io --user-token bv_u_…
+#   detects CLIs on PATH (claude, …), POSTs /runtime/register,
+#   writes ~/.beevibe/config.json (mode 0600) with the bv_d_ token
 
-## What's inside
+# 2. start claiming
+beevibe-daemon start
+#   loads config, syncs ~/.beevibe/skills, opens WS to /runtime/ws,
+#   polls /runtime/claim every 30s, heartbeats every 15s
 
-```
-beevibe/
-├── packages/
-│   ├── core/         shared library (domain, ports, services, adapters, auth)
-│   ├── api/          MCP tool surface for agents + REST for humans + mesh broker
-│   ├── scheduler/    fallback claimant for null-runtime sessions + orphan reaper
-│   ├── daemon/       runs on each user's machine; claims sessions and spawns CLIs locally
-│   └── web/          Next.js dashboard with live updates over SSE
-│
-├── skills/           Anthropic Agent Skills (markdown behavioral protocols)
-├── migrations/       node-pg-migrate SQL files
-├── scripts/          dev orchestrator + e2e smokes + provisioning helpers
-└── docker-compose.yml Postgres 16 + pgvector
+# 3. update self (Bun-compiled binaries only)
+beevibe-daemon update
+#   downloads latest GitHub release, SHA-256 verifies, atomic rename.
+#   For npm / source installs, prints the right install command and bails.
 ```
 
-Each package has its own README with details:
+`setup` flags:
 
-- [packages/core](./packages/core/README.md) — the library
-- [packages/api](./packages/api/README.md) — the agent + human API server
-- [packages/scheduler](./packages/scheduler/README.md) — server-fallback claimant + orphan reaper
-- [packages/daemon](./packages/daemon/README.md) — local-runtime daemon (one per user machine)
-- [packages/web](./packages/web/README.md) — the dashboard
+| Flag | Default | Purpose |
+|---|---|---|
+| `--api` / `-a` | (required) | Api base URL (http or https). |
+| `--user-token` / `-t` | (required) | Your `bv_u_` user key — used once to mint the `bv_d_` daemon key. |
+| `--device-name` | `<user>@<hostname>` | Human label shown in the Runtimes panel. |
+| `--external-id` | `<hostname>` | Stable per-machine id; lets `setup` re-run idempotently. |
 
-## Concepts in 60 seconds
+`start` takes no flags — everything comes from `~/.beevibe/config.json` + env. `update` takes `--yes` / `-y` to skip the confirmation prompt.
 
-- **Agent**. Has a hierarchy level — `ic` (worker), `team` (delegator), or `org` (decider). Owns a persona, a set of stable core-memory blocks, and a vector-indexed archive of facts. Identified by an `agent_id` and authenticates with a `bv_a_…` API key.
-- **Person / user**. A human owner. Authenticates with a `bv_u_…` API key. Can act as their top-level agent through MCP, or use the dashboard for review.
-- **Task**. A unit of work assigned to an agent. Moves through `pending → running → review → done` (or `failed` / `blocked` / `cancelled`). Tasks can spawn child tasks; parents auto-complete when their children settle.
-- **Session**. One run of the `claude` CLI for one task. Has a transcript, a `cli_session_id` (for `--resume`), and usage telemetry (including cache-hit ratios).
-- **Mesh**. Agents can `ask` peers one-shot questions or `negotiate` with team/org peers across multiple rounds. If they can't agree, either side can `escalate_to_humans` and a person resolves it from the dashboard.
-- **Memory**. `save_memory(...)` archives a fact (`belief`/`pattern`/`gotcha`/`preference`/`decision`); after the session ends, the FactPromoter LLM may elevate it from `ic` scope to `team` or `org` based on whether it generalizes. `update_core_memory(...)` writes the durable per-agent blocks.
-- **Skills**. Markdown procedural protocols ([Anthropic Agent Skills standard](https://agentskills.io/specification)) auto-discovered by `claude` from `<workspace>/.claude/skills/`. We ship two: `beevibe-pre-task-setup` and `beevibe-team-mesh-negotiation`.
+## Setup flow
 
-## Quick start
+1. **`setup`** probes `PATH` for known CLIs (`KNOWN_CLIS` from `@beevibe/core`), running `<cli> --version` for each one it finds.
+2. POSTs `/runtime/register` with `{ external_id, device_name, runtimes }` and `Authorization: Bearer <bv_u_…>`.
+3. Server returns `{ daemon_id, daemon_token, runtimes: [{id, cli}] }`. The daemon token is shown ONCE — saved straight to `~/.beevibe/config.json` (server stores only the SHA-256).
+4. **`start`** loads config, fetches `/runtime/skills` (version-cached), syncs into `~/.beevibe/skills/`, opens the WS, and starts the claim/heartbeat loops.
 
-You'll need:
+`~/.beevibe/config.json` (dir `0700`, file `0600`):
 
-- Node ≥ 20 + pnpm 9
-- Docker (for the Postgres + pgvector container)
-- The [`claude`](https://docs.claude.com/en/docs/claude-code/overview) CLI on PATH
-- An Anthropic API key + an OpenAI API key (the latter is for embeddings)
-
-```bash
-git clone https://github.com/beevibe-ai/beevibe.git
-cd beevibe
-pnpm install
-
-cp .env.example .env
-# fill in ANTHROPIC_API_KEY and OPENAI_API_KEY
-
-docker compose up -d                  # postgres + pgvector
-pnpm migrate up                       # apply migrations to dev DB
-pnpm dev                              # postgres + api + scheduler (+ tunnel if cloudflared is on PATH)
+```json
+{
+  "api_url": "https://api.beevibe.io",
+  "external_id": "macbook-pro.local",
+  "daemon_id": "dmn_…",
+  "daemon_token": "bv_d_…",
+  "runtimes": [{ "id": "rt_…", "cli": "claude" }]
+}
 ```
 
-`pnpm dev` runs [`scripts/dev.sh`](./scripts/dev.sh), which:
-
-- starts Postgres if it isn't already running
-- applies migrations
-- spawns `@beevibe/api` (port 3000) and `@beevibe/scheduler` (health on 3001) in watch mode with `[api]` / `[exec]` log prefixes
-- if `cloudflared` is on PATH, exposes the api at a `*.trycloudflare.com` URL and prints a paste-ready `mcp.json` snippet for remote `claude` CLI access (pass `--no-tunnel` to disable)
-
-`Ctrl+C` tears the whole tree down.
+## Concurrency cap
 
-To bring up the dashboard alongside, in a second terminal:
+A single global hardware cap across all sessions on this machine. Default: **10**. Override:
 
 ```bash
-pnpm --filter @beevibe/web dev -- -p 3030
-# then visit http://localhost:3030
+BEEVIBE_DAEMON_MAX_CONCURRENT=4 beevibe-daemon start
 ```
 
-The web app reads `NEXT_PUBLIC_BV_API_URL` (origin of the api server). For a working demo flow, run `pnpm seed-demo` to provision demo users (each with a password) — then sign in at `/sign-in`. The welcome wizard guides daemon setup.
+The `Supervisor` tracks each session under its own `AbortController`; cancel frames received over the WS abort the named session. `SIGINT` / `SIGTERM` calls `cancelAll()` and exits.
 
-## Try it from your own Claude CLI
+Per-agent caps (`max_task_sessions=1`, mesh=3) are enforced server-side at claim time, so you don't have to set those here.
 
-The `provision-demo.ts` script creates an idempotent demo team in your dev DB and prints a paste-ready MCP config so you can act *as* the captain agent from your own `claude` CLI:
+## Polling, heartbeat, reconnect
 
-```bash
-# Terminal 1
-pnpm dev
-# Wait for: "Tunnel URL: https://<random>.trycloudflare.com"
-
-# Terminal 2
-pnpm tsx scripts/provision-demo.ts
-```
+| Signal | Cadence | Source |
+|---|---|---|
+| WS push (`task_available`, `cancel`) | event-driven | api `DaemonHub.notify` |
+| HTTP `/runtime/claim` poll | 30s | `claimer.ts` `DEFAULT_POLL_MS` |
+| `/runtime/heartbeat` | 15s | `RUNTIME_HEARTBEAT_INTERVAL_MS` from `@beevibe/core` |
+| WS reconnect | exponential 1s → 30s cap | `DEFAULT_WS_RECONNECT_MAX_MS` |
 
-This creates:
+The WS push is the low-latency wakeup; the HTTP poll is the catch-up + safety net. Server stales a runtime after 60s of silence (`packages/core/src/services/orphan-reaper.ts`) — well over 2× the heartbeat interval.
 
-```
-person:   demo-user (bv_u_<token>)
-  └── captain   (team-tier, owned by demo-user)
-        ├── ic-alice  (ic-tier)
-        └── ic-bob    (ic-tier)
-```
+When the WS opens, the daemon drains `/runtime/claim` until it returns 204 or the supervisor is full, then idles waiting for the next push.
 
-Drop the printed snippet into your local `claude` CLI's MCP config (`~/.config/claude/mcp.json` or wherever your CLI reads it), then in any directory:
+## Workspaces + env
 
-```bash
-claude
-# In the chat, try:
-#   "who are my subordinates?"        → find_subordinates → [ic-alice, ic-bob]
-#   "create a task for ic-alice: write a hello-world bash script"
-#   wait ~30-60s, watching [exec] logs in Terminal 1
-#   "what's the status of that task?" → check_work_status → done
-#   "ask ic-alice: where is hello.sh?" → mesh-ask round-trip
-```
+Per-agent workspace dirs are created lazily on first claim:
 
-Cleanup:
+- Default: `~/.beevibe/workspaces/<agent_id>/`
+- Override: `WORKSPACE_ROOT=/path/to/dir`
 
-```bash
-pnpm tsx scripts/provision-demo.ts --print  # re-print existing keys/snippet
-pnpm tsx scripts/provision-demo.ts --clean  # wipe demo rows (no reseed)
-```
+Each workspace contains `mcp-config.json` (mode `0600`) with `Bearer <bv_a_…>` for that agent and the api's `/mcp` URL. The CLI reads this file directly; the daemon never sees the `bv_a_` token in a request path.
 
-`--clean` only removes rows owned by `demo-user`. It refuses if a demo agent has a live OS process so you don't wedge mid-flight tasks.
+Skills cache: `~/.beevibe/skills/`, version-gated via `.version`. Refreshed on every `start`.
 
-## Skills
+## What it doesn't do
 
-beevibe ships agent behavioral skills as `SKILL.md` files in [`/skills/`](./skills) — Anthropic's [Agent Skills open standard](https://agentskills.io/specification). The api and daemons sync them into each agent's workspace at dispatch time automatically; agent-spawned sessions get them for free.
+- **No MCP proxy.** The CLI calls `/mcp` directly using the `bv_a_` token in `mcp-config.json`. The daemon's job stops at writing the file and supervising the subprocess.
+- **No agent semantics.** `/runtime/claim` payloads are self-contained — agent_id, intent, prior_session_id (for `--resume`), workspace dir. The daemon never queries agents or tasks.
+- **No persistence beyond config.** No DB connection, no cache of agent state. The token is plaintext locally; the server stores only the SHA-256.
 
-For human users running `claude` locally and acting *as* a beevibe agent (the manual-smoke path above), install them once into your local Claude Code skill discovery dir:
+## Source layout
 
-```bash
-pnpm install-skills
 ```
-
-The install is idempotent — re-run after `git pull` to refresh. Only dirs named exactly `beevibe` or starting with `beevibe-` in `~/.claude/skills/` are touched; your other personal skills are left alone.
-
-> **Reserved namespace**: the `beevibe-` prefix in `~/.claude/skills/` is reserved for skills shipped by this repo. If you author your own personal skills, use a different prefix (e.g., `mybeevibe-foo`) — anything not matching `beevibe-*` is invisible to the install command.
-
-## Self-hosting
-
-Beyond the Railway one-click button, the same code runs anywhere that can run a container or Node 20+.
-
-### Option 1: Docker
-
-Each service has a Dockerfile under [`infra/railway/`](./infra/railway). To run the full stack via Docker:
-
-```bash
-git clone https://github.com/beevibe-ai/beevibe.git
-cd beevibe
-# Optional: pin to a tagged release for reproducible builds
-#   git checkout v0.1.0
-
-# 1. Build the three service images
-docker build -f infra/railway/Dockerfile.api       -t beevibe-api .
-docker build -f infra/railway/Dockerfile.scheduler -t beevibe-scheduler .
-docker build -f infra/railway/Dockerfile.web \
-  --build-arg NEXT_PUBLIC_BV_API_URL=http://localhost:3000 \
-  -t beevibe-web .
-
-# 2. Start Postgres
-docker compose up -d postgres
-
-# 3. Run migrations once
-docker run --rm --network host \
-  -e DATABASE_URL=postgresql://beevibe:beevibe@localhost:5433/beevibe \
-  beevibe-api pnpm migrate:deploy up
-
-# 4. Run the services (each in its own terminal or via your orchestrator)
-docker run -p 3000:3000 --network host --env-file .env beevibe-api
-docker run --network host --env-file .env beevibe-scheduler
-docker run -p 8080:3000 --env-file .env beevibe-web
+src/
+├── main.ts            CLI arg parser + subcommand dispatch
+├── setup.ts           runSetup: detect CLIs, POST /runtime/register, write config
+├── start.ts           runStart: load config, sync skills, build Supervisor + Claimer
+├── update.ts          runUpdate: GitHub-release self-update for compiled binaries
+├── config.ts          load/save ~/.beevibe/config.json (DaemonConfig shape)
+├── api-client.ts      thin GET/POST/claim over /runtime/* with bv_d_ auth + WS open
+├── claimer.ts         WS push + 30s HTTP poll + 15s heartbeat + WS reconnect
+├── supervisor.ts      bounded concurrency cap with per-session AbortControllers
+├── spawner.ts         runDispatch: workspace + ClaudeCodeRuntime + batched events
+├── skills-cache.ts    syncSkillsCache: pull /runtime/skills into ~/.beevibe/skills/
+└── supervisor.test.ts vitest unit tests
 ```
 
-Then visit `http://localhost:8080` to sign up.
+## Build distribution
 
-### Option 2: Bare Node
-
-If you'd rather not use Docker:
+For local dev:
 
 ```bash
-git clone https://github.com/beevibe-ai/beevibe.git
-cd beevibe
-# Optional: pin to a tagged release
-#   git checkout v0.1.0
-
-pnpm install --frozen-lockfile
-pnpm build
-pnpm migrate:deploy up
-
-# Start each service in its own process (use systemd, pm2, or your service manager)
-node packages/api/dist/main.js          # api on $PORT (default 3000)
-node packages/scheduler/dist/main.js    # scheduler (background worker)
-pnpm --filter @beevibe/web start        # web (next start, port from $PORT)
+pnpm --filter @beevibe/daemon build      # tsc → dist/
+pnpm --filter @beevibe/daemon dev        # tsx watch
 ```
 
-Required env vars are listed in [`.env.example`](./.env.example). The api needs `DATABASE_URL`, `BEEVIBE_MCP_SERVER_URL`, `ANTHROPIC_API_KEY`, and `OPENAI_API_KEY` at minimum.
-
-### Notes for production self-hosting
-
-- **Single api replica** for v1 (see [v1 single-instance API constraint](#v1-single-instance-api-constraint) below).
-- **Postgres 16+** with `pgvector` extension. The included `docker-compose.yml` uses `pgvector/pgvector:pg16`.
-- **Reverse proxy** in front of the api (nginx / Caddy / Cloudflare) must support WebSockets (`/runtime/ws`) and long-held HTTP responses (mesh negotiate held connections, up to 5 minutes idle).
-- **CORS**: set `BEEVIBE_CORS_ORIGINS` to the public URL of the web service. Localhost variants are always allowed in addition.
-- **Daemon distribution**: end users still install the [`beevibe-daemon`](./packages/daemon) on their own machines to run agent CLIs locally. The hosted api never spawns user CLIs.
-
-## Architecture
-
-The dependency direction across packages is one-way and ESLint-enforced:
-
-```
-core/domain     → nothing
-core/ports      → domain
-core/services   → domain + ports     (NEVER adapters)
-core/adapters   → ports it implements + domain
-api/            → core (composition root)
-scheduler/      → core (composition root)
-daemon/         → core (workspace + runtime adapters, direct imports)
-web/            → core (types only) + api (HTTP)
-```
-
-The api, scheduler, and per-user daemons are independent processes. The api never talks to the scheduler or daemons over HTTP for task dispatch — Postgres is the integration point:
-
-- The api writes task lifecycle changes (created, approved, revised, cancelled) and inserts `session` rows with `status='pending'`.
-- A daemon claims sessions whose `preferred_runtime_id` matches its registered runtime and spawns the CLI locally on the user's machine.
-- The scheduler claims null-runtime sessions (server-fallback for offline-target mesh asks) and runs the daemon-orphan reaper.
-- Cancellation: api `UPDATE`s the row + `pg_notify('cancel_task', task_id)`; the active claimant (daemon or scheduler) aborts the in-flight session in <200ms.
-- Live updates: every state-changing INSERT/UPDATE fires a `pg_notify`; api's `/api/stream` SSE endpoint relays them to the dashboard.
-
-That decoupling means each component scales independently — many daemons (one per user machine), one or a few schedulers, a single api replica per region (see [v1 single-instance API constraint](#v1-single-instance-api-constraint) below).
-
-### v1 single-instance API constraint
-
-The mesh resolver (`packages/api/src/mesh/server.ts:90`) and the
-forthcoming chat / room resolvers are in-process `Map`s — when an agent's
-`ask` fires, the API holds the HTTP request open and resolves it from
-that map when the target's `respond_ask` lands. **Both halves of the
-round-trip must hit the same API process** for v1; a multi-instance API
-fronted by a load balancer can drop responses on the floor when the two
-HTTP requests land on different replicas. Documented in code; tracked
-for cross-instance federation via `pg_notify` as a follow-up. **Self-hosters
-should run a single API replica until that ships.** The scheduler and
-per-user daemons scale horizontally either way.
-
-## Common commands
+For releases (Bun-compiled standalone binaries — no Node required):
 
 ```bash
-pnpm build              # tsc across all packages (turbo-cached)
-pnpm typecheck          # types only
-pnpm lint               # eslint
-pnpm test               # vitest (unit + integration)
-pnpm dev                # full local stack (postgres + api + scheduler + tunnel)
-pnpm migrate up         # apply migrations to DATABASE_URL
-pnpm migrate:test up    # apply migrations to DATABASE_URL_TEST
-pnpm install-skills     # install beevibe skills into ~/.claude/skills/
+pnpm --filter @beevibe/daemon build:binaries
+#   bun build --compile for darwin-{arm64,x64} + linux-{x64,arm64}
+#   outputs dist-bin/ with size + SHA-256, ready for GitHub release upload
 ```
 
-## Tech stack
-
-- TypeScript strict (ES2022, NodeNext)
-- pnpm workspaces + Turborepo
-- Postgres 16 + pgvector, raw `pg` driver (no ORM)
-- node-pg-migrate
-- Claude Code CLI runtime (spawned per-session)
-- `@modelcontextprotocol/sdk`
-- Next.js 14 + TanStack Query + Tailwind (dashboard)
+Used by `.github/workflows/release.yml`. The companion `scripts/prepare-publish.sh` bundles the workspace dep `@beevibe/core` into one ESM file via `bun build` for `npm publish`.
 
-## End-to-end smokes
-
-Live integration tests against real Postgres + LLM APIs. Each is gated by an env flag.
+## Build / test
 
 ```bash
-# In-process smoke — api + scheduler bootstrapped in the same VM
-RUN_M6_E2E=1 \
-  DATABASE_URL_TEST=postgresql://beevibe:beevibe@localhost:5433/beevibe_test \
-  OPENAI_API_KEY=... ANTHROPIC_API_KEY=... \
-  pnpm tsx scripts/m6-e2e.ts
-
-# Multi-process smoke — api + scheduler as actual `node dist/main.js`
-# subprocesses; verifies cross-process IPC, signal propagation, no orphans
-RUN_M7_E2E=1 \
-  DATABASE_URL_TEST=postgresql://beevibe:beevibe@localhost:5433/beevibe_test \
-  OPENAI_API_KEY=... ANTHROPIC_API_KEY=... \
-  pnpm tsx scripts/m7-e2e.ts
-
-# Skills + memory + cache-hit ratio smoke (M9 features)
-RUN_M9_E2E=1 \
-  DATABASE_URL_TEST=postgresql://beevibe:beevibe@localhost:5433/beevibe_test \
-  OPENAI_API_KEY=... ANTHROPIC_API_KEY=... \
-  pnpm tsx scripts/m9-e2e.ts
+pnpm --filter @beevibe/daemon build
+pnpm --filter @beevibe/daemon typecheck
+pnpm --filter @beevibe/daemon test
 ```
-
-Apply test-DB migrations first with `pnpm migrate:test up`. All scripts truncate the test DB at the start, so back-to-back runs work.
-
-## Project status
-
-The platform was built in milestones (M0 → M9), each with its own integration test:
-
-| Milestone | What landed |
-|---|---|
-| M0 | Repo scaffold |
-| M1 | Domain + ports + Postgres adapter + schema + migrations |
-| M2 | Claude Code runtime adapter + workspace adapter |
-| M3 | Memory subsystem + pgvector + LLM providers |
-| M4 | API-key auth + agent provisioning |
-| M5 | Executor binary (polling + dispatch) |
-| M6 | API binary (MCP tools + REST + mesh + escalation + cancellation) |
-| M7 | Multi-process integration test + dev orchestrator |
-| M8 | Web dashboard (Next.js + SSE) |
-| M9 | Skill system (auto-discovered behavioral protocols) + memory tooling refresh |
-
-The full design discussions and PR references live in the [closed issues](https://github.com/beevibe-ai/beevibe/issues?q=is%3Aissue+is%3Aclosed) — each milestone has one tracking issue.
-
-## Contributing
-
-Issues and PRs welcome. For non-trivial changes, open an issue first so we can align on direction.
-
-A few conventions worth knowing:
-
-- **Plan first, build second.** Each milestone is scoped end-to-end (schema → types → unit tests → integration test) before any code is written. See `tasks/` (gitignored) for the workflow.
-- **TDD where it pays.** Domain types and pure services are test-first. Adapters get integration tests against real services (Postgres, real LLM keys).
-- **No parallel systems.** When a feature replaces an older one, the old code is deleted in the same PR — no `if (new) ... else if (old) ...` branches.
-
-## License
-
-The Beevibe source code is licensed under the [Apache License 2.0](./LICENSE).
-
-The **Beevibe** name and logo are trademarks of the project — see
-[TRADEMARK.md](./TRADEMARK.md). Apache 2.0 grants rights to the source
-code; it does not grant rights to use the project's name or marks. Forks
-and derivative works are welcome under any name that is not "Beevibe."
-
-Contributing? See [CONTRIBUTING.md](./CONTRIBUTING.md). All commits must
-include a `Signed-off-by:` trailer (the [Developer Certificate of Origin
-v1.1](./CONTRIBUTING.md#developer-certificate-of-origin-v11)) — `git commit -s`.
-
-Copyright (c) 2026 Zhe Pang. Rights to be assigned to Beevibe Inc. upon
-its formation.

package/dist/main.js

@@ -4,6 +4,205 @@
 import { hostname, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
 
+// ../../node_modules/.pnpm/nanoid@5.1.9/node_modules/nanoid/index.js
+import { webcrypto as crypto } from "node:crypto";
+var POOL_SIZE_MULTIPLIER = 128;
+var pool;
+var poolOffset;
+function fillPool(bytes) {
+  if (!pool || pool.length < bytes) {
+    pool = Buffer.allocUnsafe(bytes * POOL_SIZE_MULTIPLIER);
+    crypto.getRandomValues(pool);
+    poolOffset = 0;
+  } else if (poolOffset + bytes > pool.length) {
+    crypto.getRandomValues(pool);
+    poolOffset = 0;
+  }
+  poolOffset += bytes;
+}
+function random(bytes) {
+  fillPool(bytes |= 0);
+  return pool.subarray(poolOffset - bytes, poolOffset);
+}
+function customRandom(alphabet, defaultSize, getRandom) {
+  let safeByteCutoff = 256 - 256 % alphabet.length;
+  if (safeByteCutoff === 256) {
+    let mask = alphabet.length - 1;
+    return (size = defaultSize) => {
+      if (!size)
+        return "";
+      let id = "";
+      while (true) {
+        let bytes = getRandom(size);
+        let i = size;
+        while (i--) {
+          id += alphabet[bytes[i] & mask];
+          if (id.length >= size)
+            return id;
+        }
+      }
+    };
+  }
+  let step = Math.ceil(1.6 * 256 * defaultSize / safeByteCutoff);
+  return (size = defaultSize) => {
+    if (!size)
+      return "";
+    let id = "";
+    while (true) {
+      let bytes = getRandom(step);
+      let i = step;
+      while (i--) {
+        if (bytes[i] < safeByteCutoff) {
+          id += alphabet[bytes[i] % alphabet.length];
+          if (id.length >= size)
+            return id;
+        }
+      }
+    }
+  };
+}
+function customAlphabet(alphabet, size = 21) {
+  return customRandom(alphabet, size, random);
+}
+
+// ../core/dist/domain/ids.js
+var alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+var nanoid12 = customAlphabet(alphabet, 12);
+// ../core/dist/domain/core-memory.js
+var DEFAULT_BLOCK_TEMPLATES = {
+  ic: [
+    {
+      block_name: "tag_line",
+      char_limit: 100,
+      is_system: true,
+      initial_content: "",
+      description: "One-line headline of my enduring specialization — shown on agent " + "cards in the UI. Describes what I'm an expert in, not what " + "project I'm currently on. Examples: 'Go backend specialist " + "(Chi/sqlc, websockets)', 'Next.js + React UI lead'. Max 100 " + "chars. Update only when my specialization itself shifts."
+    },
+    {
+      block_name: "persona",
+      char_limit: 2000,
+      is_system: true,
+      initial_content: "",
+      description: "Who I am and how I work — my role and working style, persistent " + "across every project I touch. 1-3 sentences in first person. " + "Update when my self-conception genuinely shifts (acquired a " + "major capability, refined my approach). NOT my current project " + "(that's `active_context`), NOT my domain scope (that's `domain`)."
+    },
+    {
+      block_name: "domain",
+      char_limit: 2000,
+      is_system: true,
+      initial_content: "",
+      description: "The areas I specialize in ACROSS all projects — my enduring " + "expertise. As I work on more projects in my domain, this can " + "deepen (becoming truly expert in narrower sub-areas). Bullet " + "format. Example: 'Go backend services: HTTP via Chi/echo, DB " + "via sqlc, websockets via gorilla, distribution via goreleaser.' " + "NOT project-specific paths (those go in `active_context`). NOT " + "the rules I follow (those go in `constraints`)."
+    },
+    {
+      block_name: "active_context",
+      char_limit: 2000,
+      is_system: true,
+      initial_content: "",
+      description: "What I'm currently working on — the specific project and its " + "in-flight details. Bullet format. Example: 'Project: " + "github.com/multica-ai/multica. Local clone: /tmp/multica-repo. " + "Owned paths in this project: server/cmd/**, server/internal/**. " + "Current task: task_xfQpuEHWjbvk.' Transient — rewrite when the " + "project changes. This is where ALL project/codebase-specific " + "details live, NOT in `domain`."
+    },
+    {
+      block_name: "constraints",
+      char_limit: 2000,
+      is_system: true,
+      initial_content: "",
+      description: "Hard rules I follow — non-negotiable conventions and " + "coordination boundaries. Mix of persistent rules ('queries " + "always via sqlc — never hand-write the DB layer') and " + "project-specific rules ('read /CLAUDE.md before changes in " + "this codebase'). Bullet format. Reference docs by path, not " + "content."
+    }
+  ],
+  team: [
+    {
+      block_name: "tag_line",
+      char_limit: 100,
+      is_system: true,
+      initial_content: "",
+      description: "One-line headline of my enduring role — shown on agent cards. " + "Describes the team I lead, not the project we're on. Examples: " + "'Daniel's team — orchestrates 3 backend/frontend/platform " + "specialists', 'Solo lead — driving a small team for hire'. " + "Max 100 chars."
+    },
+    {
+      block_name: "persona",
+      char_limit: 2000,
+      is_system: true,
+      initial_content: "",
+      description: "Who I am as a team lead — my orchestration style and how I " + "delegate. 1-3 sentences in first person. Persistent across " + "projects. NOT my team roster (that's `team_members`), NOT the " + "current work (that's `active_work`)."
+    },
+    {
+      block_name: "team_members",
+      char_limit: 3000,
+      is_system: true,
+      initial_content: "",
+      description: "Roster of my direct reports — for each: name, agent_id, " + "specialization (NOT project assignment — same agents stay over " + "time as we work different projects). Bullet format. Update " + "when subordinates are spawned/archived/reassigned."
+    },
+    {
+      block_name: "active_work",
+      char_limit: 2000,
+      is_system: true,
+      initial_content: "",
+      description: "What my team is currently working on — the active project + " + "high-level work in flight across specialists. Bullet format. " + "Example: 'Project: github.com/multica-ai/multica. Backend " + "specialist running CLI audit (task_xfQpuEHWjbvk); Frontend on " + "standby.' Transient — rewrite on project shifts."
+    },
+    {
+      block_name: "patterns",
+      char_limit: 2000,
+      is_system: true,
+      initial_content: "",
+      description: "Cross-project patterns I've observed in how my team operates — " + "what works, what trips them up. Persistent. Example: 'When I " + "assign an audit task, the IC tends to produce thorough work " + "products but forgets to save_memory mid-pass.' NOT specific " + "findings about a codebase (those go in archival memory via " + "save_memory)."
+    }
+  ],
+  org: [
+    {
+      block_name: "tag_line",
+      char_limit: 100,
+      is_system: true,
+      initial_content: "",
+      description: "One-line headline of my org-level role — shown on agent cards. " + "Describes the scope I oversee, not the current project. " + "Examples: 'Eng org lead — 3 teams (product/platform/infra)'. " + "Max 100 chars."
+    },
+    {
+      block_name: "persona",
+      char_limit: 2000,
+      is_system: true,
+      initial_content: "",
+      description: "Who I am as an org leader — my decision style and how I balance " + "across teams. 1-3 sentences. Persistent."
+    },
+    {
+      block_name: "teams",
+      char_limit: 3000,
+      is_system: true,
+      initial_content: "",
+      description: "Teams under my oversight — for each: name, team-lead agent_id, " + "scope. Persistent identity. Bullet format."
+    },
+    {
+      block_name: "strategy",
+      char_limit: 2000,
+      is_system: true,
+      initial_content: "",
+      description: "Cross-project / cross-team direction I'm driving. Higher-level " + "than active_work. Examples: 'Q2 focus: ship Multica self-host " + "v1', 'Hiring: prioritize backend over frontend this quarter'."
+    },
+    {
+      block_name: "decisions",
+      char_limit: 2000,
+      is_system: true,
+      initial_content: "",
+      description: "Cross-team decisions I've resolved — bullet log. Each entry: " + "what was decided, when, why. Persistent record so the same " + "question doesn't come back up."
+    }
+  ]
+};
+// ../core/dist/domain/memory.js
+var FACT_TYPE_DESCRIPTIONS = {
+  belief: "A position you hold based on multiple sessions of evidence. A lasting view, " + "not a fleeting reaction to one session.",
+  pattern: "A recurring observation about the codebase or the domain you work in — " + "knowledge another agent could reuse. NOT a pattern about your own behavior " + "(your search habits, your memory-keeping, how you should have responded next " + "time). Save the thing you learned about the world, not a note-to-self about " + "how to behave.",
+  gotcha: "A non-obvious thing-that-bites — a footgun that's easy to step on, where the " + "surprise itself is the value. Concrete and reusable across future tasks in " + "the same area.",
+  preference: `A user's stated durable rule. Trigger words: "always", "from now on", ` + '"every time", "as a default", "going forward". Do NOT save preferences ' + "for one-off requests scoped to a specific task, session, or work-product " + '("after this task", "for this audit", "now"). When in doubt, just do the ' + "thing once without saving — the user can restate it if they want it to stick.",
+  decision: 'A chosen path with rationale. The "why" that future-you (or another agent) ' + "needs to understand why the codebase / approach looks the way it does — not " + 'the mechanical "what" (read the code for that).'
+};
+// ../core/dist/domain/runtime.js
+var KNOWN_CLIS = ["claude", "codex", "opencode"];
+var RUNTIME_HEARTBEAT_INTERVAL_MS = 15000;
+// ../core/dist/auth/api-key.js
+var KEY_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+var nanoid24 = customAlphabet(KEY_ALPHABET, 24);
+// ../core/dist/auth/password.js
+import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+import { promisify } from "node:util";
+var scryptAsync = promisify(scrypt);
+var SCRYPT_N = 16384;
+var SCRYPT_R = 8;
+var SCRYPT_MAXMEM = 128 * SCRYPT_N * SCRYPT_R * 2;
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -26,7 +225,6 @@ function saveConfig(cfg) {
 }
 
 // src/setup.ts
-var KNOWN_CLIS = ["claude", "codex", "opencode"];
 async function runSetup(options) {
   if (!/^https?:\/\//.test(options.apiUrl)) {
     throw new Error("--api must be an http(s) URL");
@@ -83,9 +281,9 @@ function detectClis() {
 }
 
 // ../core/dist/adapters/local-workspace/manager.js
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join2 } from "node:path";
+import { isAbsolute, join as join2 } from "node:path";
 
 // ../core/dist/services/skills/sync.js
 import { promises as fs } from "node:fs";
@@ -216,35 +414,38 @@ class LocalWorkspaceManager {
   root;
   constructor(config) {
     this.config = config;
-    this.root = config.workspaceRoot ?? join2(homedir2(), ".beevibe", "workspaces");
+    this.root = config.workspaceRoot || join2(homedir2(), ".beevibe", "workspaces");
+    if (!isAbsolute(this.root)) {
+      throw new Error(`LocalWorkspaceManager: workspaceRoot must be absolute, got "${this.root}"`);
+    }
   }
-  async ensureWorkspace({ agent }) {
-    const path2 = join2(this.root, agent.id);
+  async ensureWorkspace({ agent: agent2 }) {
+    const path2 = join2(this.root, agent2.id);
     mkdirSync2(path2, { recursive: true, mode: 448 });
+    if (!agent2.api_key) {
+      throw new Error(`Cannot write mcp-config.json for agent ${agent2.id}: agent.api_key is missing`);
+    }
     const configPath = join2(path2, "mcp-config.json");
-    if (!existsSync2(configPath)) {
-      if (!agent.api_key) {
-        throw new Error(`Cannot write mcp-config.json for agent ${agent.id}: agent.api_key is missing`);
-      }
-      writeFileSync2(configPath, buildMcpConfig(agent.api_key, this.config.mcpServerUrl), {
-        mode: 384
-      });
+    const expected = buildMcpConfig(agent2.api_key, this.config.mcpServerUrl);
+    const needsWrite = !existsSync2(configPath) || readFileSync2(configPath, "utf-8") !== expected;
+    if (needsWrite) {
+      writeFileSync2(configPath, expected, { mode: 384 });
     }
-    const workspace = { path: path2 };
-    const runtime = this.config.runtimeRegistry[agent.runtime_config.type];
-    if (!runtime) {
-      throw new Error(`No runtime registered for agent ${agent.id} (runtime_config.type='${agent.runtime_config.type}')`);
+    const workspace2 = { path: path2 };
+    const runtime3 = this.config.runtimeRegistry[agent2.runtime_config.type];
+    if (!runtime3) {
+      throw new Error(`No runtime registered for agent ${agent2.id} (runtime_config.type='${agent2.runtime_config.type}')`);
     }
     await syncSkills({
       sourceDir: this.config.skillsSourceDir,
-      targetDir: runtime.skillsDir(workspace),
-      filter: tierFilterFor(agent.hierarchy_level),
+      targetDir: runtime3.skillsDir(workspace2),
+      filter: tierFilterFor(agent2.hierarchy_level),
       namespacePrefix: "beevibe"
     });
-    return workspace;
+    return workspace2;
   }
-  async removeWorkspace(workspace) {
-    rmSync(workspace.path, { recursive: true, force: true });
+  async removeWorkspace(workspace2) {
+    rmSync(workspace2.path, { recursive: true, force: true });
   }
 }
 function buildMcpConfig(apiKey, mcpServerUrl) {
@@ -594,12 +795,15 @@ function parseClaudeMessages(messages, exitCode) {
   } : undefined;
   return {
     status: succeeded ? "completed" : "failed",
-    output: output || (succeeded ? "Session completed." : `CLI exited with code ${exitCode}`),
+    output: output || (succeeded ? "Session completed." : bareCliExitMessage(exitCode)),
     transcript: transcript || undefined,
     usage,
     cli_session_id: sessionId
   };
 }
+function bareCliExitMessage(exitCode) {
+  return `CLI exited with code ${exitCode}`;
+}
 
 // ../core/dist/adapters/claude-code/runtime.js
 var NESTING_GUARD_VARS = [
@@ -644,13 +848,13 @@ class ClaudeCodeRuntime {
     if (context.system_prompt_append.length > 0) {
       args.push("--append-system-prompt", context.system_prompt_append);
     }
-    const env = { ...process.env };
+    const env2 = { ...process.env };
     for (const key of NESTING_GUARD_VARS)
-      delete env[key];
+      delete env2[key];
     for (const key of ANTHROPIC_AUTH_VARS)
-      delete env[key];
+      delete env2[key];
     if (context.env)
-      Object.assign(env, context.env);
+      Object.assign(env2, context.env);
     const messages = [];
     let pending = "";
     const handleLine = (line) => {
@@ -668,7 +872,7 @@ class ClaudeCodeRuntime {
       command: this.config.command ?? "claude",
       args,
       cwd,
-      env,
+      env: env2,
       stdin: context.intent,
       abortSignal: context.abort_signal,
       onSpawn: ({ pid, process_group_id }) => {
@@ -700,10 +904,14 @@ class ClaudeCodeRuntime {
       };
     }
     const parsed = parseClaudeMessages(messages, result.exitCode);
+    const STDERR_TAIL_BYTES = 4096;
+    const stderrTail = parsed.status === "failed" && result.stderr ? result.stderr.slice(-STDERR_TAIL_BYTES) : undefined;
     return {
       ...parsed,
       process_pid: result.pid ?? undefined,
-      process_group_id: result.process_group_id ?? undefined
+      process_group_id: result.process_group_id ?? undefined,
+      exit_code: result.exitCode,
+      ...stderrTail ? { stderr: stderrTail } : {}
     };
   }
   async healthCheck() {
@@ -724,8 +932,8 @@ class ClaudeCodeRuntime {
     }
   }
   async shutdown() {}
-  skillsDir(workspace) {
-    return join3(workspace.path, ".claude", "skills");
+  skillsDir(workspace2) {
+    return join3(workspace2.path, ".claude", "skills");
   }
 }
 
@@ -803,7 +1011,8 @@ async function runDispatch(deps, payload, abortSignal) {
     runtime_config: { type: "claude" }
   };
   const ws = await deps.workspaceManager.ensureWorkspace({ agent: syntheticAgent });
-  const runtime = deps.runtime ?? new ClaudeCodeRuntime;
+  console.log(`[daemon/spawn] sess=${payload.session_id} agent=${payload.agent_id} type=${payload.type} cwd=${ws.path}`);
+  const runtime3 = deps.runtime ?? new ClaudeCodeRuntime;
   const buffer = [];
   let flushTimer;
   const flush = async () => {
@@ -839,7 +1048,7 @@ async function runDispatch(deps, payload, abortSignal) {
   let result;
   let runError;
   try {
-    result = await runtime.execute({
+    result = await runtime3.execute({
       intent: payload.intent,
       workspace: ws,
       system_prompt_append: payload.system_prompt_append,
@@ -859,15 +1068,25 @@ async function runDispatch(deps, payload, abortSignal) {
   }
   await flush();
   const status = runError ? "failed" : result?.status === "completed" ? "succeeded" : result?.status === "cancelled" ? "cancelled" : "failed";
+  const errorDetail = runError?.message ?? result?.stderr;
   const done = {
     session_id: payload.session_id,
     status,
     cli_session_id: result?.cli_session_id,
     result_summary: result?.output ?? "",
-    exit_code: status === "succeeded" ? 0 : 1,
-    error: runError?.message,
+    exit_code: result?.exit_code ?? null,
+    error: errorDetail,
     usage: result?.usage
   };
+  if (status === "succeeded") {
+    console.log(`[daemon/spawn] sess=${payload.session_id} exit=0`);
+  } else {
+    console.error(`[daemon/spawn] sess=${payload.session_id} status=${status} exit=${done.exit_code}` + (errorDetail ? `
+  error:
+    ${errorDetail.split(`
+`).join(`
+    `)}` : ""));
+  }
   try {
     await deps.api.post("/runtime/done", done);
   } catch (err) {
@@ -877,7 +1096,6 @@ async function runDispatch(deps, payload, abortSignal) {
 
 // src/claimer.ts
 var DEFAULT_POLL_MS = 30000;
-var DEFAULT_HEARTBEAT_MS = 15000;
 var DEFAULT_WS_RECONNECT_MAX_MS = 30000;
 
 class Claimer {
@@ -894,7 +1112,7 @@ class Claimer {
   constructor(cfg) {
     this.cfg = cfg;
     this.pollIntervalMs = cfg.pollIntervalMs ?? DEFAULT_POLL_MS;
-    this.heartbeatIntervalMs = cfg.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+    this.heartbeatIntervalMs = cfg.heartbeatIntervalMs ?? RUNTIME_HEARTBEAT_INTERVAL_MS;
     this.wsReconnectMaxDelayMs = cfg.wsReconnectMaxDelayMs ?? DEFAULT_WS_RECONNECT_MAX_MS;
   }
   start() {
@@ -991,6 +1209,7 @@ class Claimer {
       const payload = await this.cfg.api.claim(runtimeId);
       if (!payload)
         return;
+      console.log(`[daemon/claim] sess=${payload.session_id} agent=${payload.agent_id} runtime=${runtimeId}`);
       const ctrl = this.cfg.supervisor.start(payload.session_id);
       runDispatch({ api: this.cfg.api, workspaceManager: this.cfg.workspaceManager }, payload, ctrl.signal).catch((err) => console.error(`[daemon] dispatch ${payload.session_id} failed:`, err instanceof Error ? err.message : String(err))).finally(() => this.cfg.supervisor.finish(payload.session_id));
     }
@@ -1157,7 +1376,7 @@ var PLATFORM_ASSETS = {
   "linux-arm64": "beevibe-daemon-linux-arm64"
 };
 function currentVersion() {
-  return "0.1.0";
+  return "0.1.2";
 }
 function isCompiledBinary() {
   if (!process.versions.bun)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beevibe/daemon",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Beevibe daemon — runs on each user's machine, claims pending sessions and spawns the CLI locally",
   "license": "Apache-2.0",
   "author": "Zhe Pang",