mirror of
https://github.com/qwibitai/nanoclaw.git
synced 2026-07-09 18:57:08 +08:00
Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 gavrielc
|
1912419137 | ||
|
gavrielc
|
c97548db60 |
@@ -1,22 +0,0 @@
|
||||
# Remove /add-clidash
|
||||
|
||||
clidash is fully self-contained, so removal is a single directory delete. It
|
||||
made no edits to NanoClaw `src/`, added no dependency, and wired into nothing.
|
||||
|
||||
```bash
|
||||
# Stop the service first if you set one up:
|
||||
systemctl --user disable --now clidash 2>/dev/null || true
|
||||
rm -f ~/.config/systemd/user/clidash.service
|
||||
|
||||
# Remove the tool:
|
||||
rm -rf tools/clidash
|
||||
```
|
||||
|
||||
If you added the config to `.gitignore` in step 2 of the install, remove that
|
||||
line too:
|
||||
|
||||
```
|
||||
tools/clidash/clidash.config.json
|
||||
```
|
||||
|
||||
Nothing else needs reverting.
|
||||
@@ -1,168 +0,0 @@
|
||||
---
|
||||
name: add-clidash
|
||||
description: Add clidash — a zero-dependency, read-only web dashboard that derives its tabs and tables at runtime from any CLI that lists resources as JSON. Ships pre-wired for NanoClaw's ncl CLI (agent groups, sessions, channels, users, roles), plus message-activity charts, a log tail, and a read-only file viewer for group skills/CLAUDE.md/profiles.
|
||||
---
|
||||
|
||||
# /add-clidash — CLI-derived read-only dashboard
|
||||
|
||||
clidash is a small, read-only web dashboard. You point it at any CLI that can
|
||||
list resources as JSON (NanoClaw's `ncl`, `docker`, `kubectl`, …) and it builds
|
||||
the dashboard at runtime: one tab per resource, a generic table over whatever
|
||||
columns the rows have. A new `ncl` resource becomes a new tab and a new column
|
||||
becomes a new table column with **zero code changes**.
|
||||
|
||||
It ships pre-wired for NanoClaw's `ncl` CLI and adds three NanoClaw-aware
|
||||
panels driven entirely by config:
|
||||
|
||||
- **Agents overview** — status cards joining groups + sessions + messaging
|
||||
groups + wirings (green <15m / amber <2h / red older).
|
||||
- **Activity** — per-session inbound/outbound message totals and a daily series,
|
||||
read directly from the session DBs (`ncl` has no messages resource).
|
||||
- **Logs** — last N lines of allowlisted host log files.
|
||||
- **Files** — a read-only viewer for group skills, `CLAUDE.md`, and profiles.
|
||||
|
||||
## Why it's safe
|
||||
|
||||
clidash is **read-only by construction**: the server can only `execFile` the
|
||||
argv templates in its config. `{resource}` is the sole substitution and is
|
||||
allowlist-validated against the discovered/static resource set before exec —
|
||||
never a shell, no free-form input reaches argv. There is no auth; **the network
|
||||
is the auth boundary** — it binds `127.0.0.1` by default. Only ever bind a
|
||||
private interface (e.g. a tailnet IP), never a public one.
|
||||
|
||||
It's distinct from `/add-dashboard` (which pushes JSON snapshots to a separate
|
||||
`@nanoco/nanoclaw-dashboard` npm package): clidash has **zero dependencies**, no
|
||||
build step, no push pipeline, and no edits to NanoClaw source — it just reads
|
||||
`ncl` and the session DBs.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Copy the tool into place
|
||||
|
||||
clidash is fully self-contained — copy the whole directory in:
|
||||
|
||||
`tools/` is not a standard NanoClaw directory and `cp -R` won't create it, so
|
||||
make it first:
|
||||
|
||||
```bash
|
||||
mkdir -p tools
|
||||
cp -R .claude/skills/add-clidash/add/tools/clidash tools/clidash
|
||||
```
|
||||
|
||||
That is the only file change this skill makes. Nothing in NanoClaw `src/` is
|
||||
touched, no dependency is added.
|
||||
|
||||
### 2. Create the config
|
||||
|
||||
The example config is pre-wired for NanoClaw with paths relative to the repo
|
||||
root, so it works as-is when you run clidash from `tools/clidash/`:
|
||||
|
||||
```bash
|
||||
cd tools/clidash
|
||||
cp clidash.config.example.json clidash.config.json
|
||||
```
|
||||
|
||||
`clidash.config.json` is your local config — add it to `.gitignore` if you
|
||||
don't want to commit install-specific paths:
|
||||
|
||||
```bash
|
||||
echo 'tools/clidash/clidash.config.json' >> ../../.gitignore
|
||||
```
|
||||
|
||||
The example assumes `ncl` is built at `bin/ncl`. If `bin/ncl` doesn't exist,
|
||||
build it first (`pnpm run build`) or point `clis.ncl.bin` at the right path.
|
||||
|
||||
### 3. Test
|
||||
|
||||
Tests use a stub CLI — no real `ncl` or `docker` needed:
|
||||
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
All tests should pass (Node ≥ 22.5, `node:test`, zero dependencies).
|
||||
|
||||
### 4. Run and verify
|
||||
|
||||
```bash
|
||||
node server.js # serves http://127.0.0.1:4690
|
||||
```
|
||||
|
||||
In another shell, confirm it's live and that `ncl` discovery worked:
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:4690/api/clis | head -c 400 # CLIs + discovered resources
|
||||
curl -s http://127.0.0.1:4690/api/r/ncl/groups | head -c 400 # a real resource table
|
||||
```
|
||||
|
||||
Then open `http://127.0.0.1:4690/` in a browser. You should see the Agents
|
||||
overview plus a tab per `ncl` resource.
|
||||
|
||||
### 5. (Optional) Run as a service
|
||||
|
||||
clidash binds `127.0.0.1` by default. To reach it from other devices, bind a
|
||||
private (e.g. tailnet) IP via the `BIND` env var or `bind` in config — never a
|
||||
public interface.
|
||||
|
||||
```ini
|
||||
# ~/.config/systemd/user/clidash.service (Linux)
|
||||
[Unit]
|
||||
Description=clidash read-only CLI dashboard
|
||||
|
||||
[Service]
|
||||
WorkingDirectory=%h/nanoclaw/tools/clidash
|
||||
ExecStart=/usr/bin/node %h/nanoclaw/tools/clidash/server.js
|
||||
Environment=BIND=127.0.0.1
|
||||
Restart=on-failure
|
||||
|
||||
[Install]
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
```bash
|
||||
systemctl --user enable --now clidash
|
||||
```
|
||||
|
||||
On macOS, wrap `node server.js` (with `WorkingDirectory` = `tools/clidash`) in a
|
||||
launchd plist the same way the main NanoClaw service is configured.
|
||||
|
||||
## Configuration reference
|
||||
|
||||
`clidash.config.json` keys (see `tools/clidash/README.md` and
|
||||
`clidash.config.example.json` for the full shape):
|
||||
|
||||
| Key | Purpose |
|
||||
|-----|---------|
|
||||
| `port`, `bind`, `refreshSeconds` | server bind + UI auto-refresh cadence |
|
||||
| `clis.<name>.bin` / `cwd` / `env` | how to invoke the CLI (`bin` is relative to `cwd`) |
|
||||
| `clis.<name>.discover` or `resources` | runtime discovery (`ncl help`) vs a static resource list |
|
||||
| `clis.<name>.list` | argv template; `{resource}` is the only substitution |
|
||||
| `clis.<name>.output` | `json` or `jsonlines` (docker/kubectl style) |
|
||||
| `clis.<name>.unwrap` | dot-path into a response envelope (e.g. `data`) |
|
||||
| `clis.<name>.enrich`/`badges`/`summary` | table decorations (ID→name joins, status colors, summary cards) |
|
||||
| `activity` | `sessionsRoot` + `days` for the message-activity charts |
|
||||
| `logs` | `dir`, `tailLines`, and an allowlist of `files` to tail |
|
||||
| `docs` | file viewer: `root`, a `deny` glob list, and `collections` of glob patterns |
|
||||
|
||||
Adding a second CLI is config-only — e.g. `docker` is included as a `jsonlines`
|
||||
example. View plugins (`views/<cli>-<view>.js`) are the only per-CLI code and
|
||||
are optional.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **`ENOENT` / config not found** — run from `tools/clidash/` and make sure you
|
||||
copied `clidash.config.example.json` to `clidash.config.json` (step 2), or set
|
||||
`CLIDASH_CONFIG=/abs/path.json`.
|
||||
- **No `ncl` resources / discovery empty** — `bin/ncl` isn't built or the path
|
||||
is wrong. Build it (`pnpm run build`) or fix `clis.ncl.bin`.
|
||||
- **docker tab errors** — the docker daemon isn't running, or remove the
|
||||
`docker` CLI from config if you don't need it.
|
||||
- **Can't reach it from another device** — it binds `127.0.0.1`; set
|
||||
`BIND=<private-ip>` (tailnet), never a public interface.
|
||||
- **Empty Activity/Logs/Files** — check that `activity.sessionsRoot`,
|
||||
`logs.dir`, and `docs.root` resolve to your NanoClaw root (relative to where
|
||||
you launch `node server.js`).
|
||||
|
||||
## Removal
|
||||
|
||||
See [REMOVE.md](REMOVE.md).
|
||||
@@ -1,109 +0,0 @@
|
||||
# clidash
|
||||
|
||||
CLI-agnostic **read-only** web dashboard. Point it at any CLI that can list
|
||||
resources as JSON and it derives the dashboard at runtime: one tab per
|
||||
resource, a generic table over whatever columns the rows have. New resource →
|
||||
new tab; new column → new table column; **zero code changes**.
|
||||
|
||||
It ships pre-wired for NanoClaw's `ncl` CLI (agent groups, sessions, messaging
|
||||
groups, wirings, users, roles, …) plus `docker`, but the same config shape
|
||||
works for any list-as-JSON CLI.
|
||||
|
||||
- **Zero dependencies** — Node built-ins only (Node ≥ 22.5, for `node:sqlite`),
|
||||
no build step,
|
||||
vanilla-JS frontend.
|
||||
- **Read-only by construction** — the server can only `execFile` the configured
|
||||
argv templates; `{resource}` is the sole substitution and is validated
|
||||
against the discovered/static resource allowlist. Never a shell.
|
||||
- **Standalone** — no imports from NanoClaw source; the core is extractable to
|
||||
its own repo. The NanoClaw-specific knowledge lives entirely in the config
|
||||
and in the `views/ncl-overview.js` view plugin.
|
||||
|
||||
## Run
|
||||
|
||||
```bash
|
||||
cp clidash.config.example.json clidash.config.json # then edit paths if needed
|
||||
node server.js # uses ./clidash.config.json
|
||||
CLIDASH_CONFIG=/path/to.json node server.js
|
||||
PORT=4690 BIND=127.0.0.1 node server.js # env overrides
|
||||
```
|
||||
|
||||
Run it from `tools/clidash/`; the example config uses paths relative to the
|
||||
NanoClaw root two levels up, so it works out of the box once `ncl` is built.
|
||||
|
||||
## Configure (`clidash.config.json`)
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"port": 4690,
|
||||
"bind": "127.0.0.1", // never a public interface; a tailnet IP at most
|
||||
"refreshSeconds": 60,
|
||||
"clis": {
|
||||
"ncl": {
|
||||
"bin": "bin/ncl", // relative to cwd below
|
||||
"cwd": "../..", // the NanoClaw root
|
||||
"discover": { "args": ["help"], "parser": "ncl-help" }, // runtime resource discovery
|
||||
"list": ["{resource}", "list", "--json"], // argv template
|
||||
"output": "json", // or "jsonlines" (docker/kubectl style)
|
||||
"unwrap": "data" // dot-path into a response envelope
|
||||
},
|
||||
"docker": {
|
||||
"bin": "docker",
|
||||
"resources": ["ps", "images"], // static alternative to discover
|
||||
"list": ["{resource}", "--format", "{{json .}}"],
|
||||
"output": "jsonlines"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`{resource}` may appear as a whole argv element or inside one — e.g. a remote
|
||||
CLI via ssh: `"list": ["-i", "key.pem", "user@host", "ncl {resource} list --json"]`.
|
||||
|
||||
Per-CLI `env` (merged over the server's env) and `cwd` are supported. See
|
||||
`clidash.config.example.json` for the full NanoClaw config, including the
|
||||
`enrich`/`badges`/`summary` table decorations and the `activity`/`logs`/`docs`
|
||||
sections.
|
||||
|
||||
## API
|
||||
|
||||
| Route | Returns |
|
||||
|---|---|
|
||||
| `GET /api/clis` | configured CLIs + discovered/static resources (discovery cached 60s) |
|
||||
| `GET /api/r/<cli>/<resource>` | `{ok, rows, fetchedAt}` — coalesced, 10s exec timeout |
|
||||
| `GET /api/view/<cli>/<view>` | curated view plugin from `views/<cli>-<view>.js` |
|
||||
|
||||
View plugins are the only per-CLI *code*, and optional: a default-exported
|
||||
async function receiving `{ fetch }` (bound to that CLI) returning JSON.
|
||||
`views/ncl-overview.js` joins groups + sessions + messaging-groups + wirings
|
||||
into per-agent status cards (green <15m / amber <2h / red older).
|
||||
|
||||
## Test
|
||||
|
||||
```bash
|
||||
npm test # unit + integration (node:test, stub CLI — no real CLI needed)
|
||||
./test/smoke.sh # against a running instance
|
||||
```
|
||||
|
||||
## Deploy as a service
|
||||
|
||||
clidash binds `127.0.0.1` by default. To reach it from other devices, bind a
|
||||
private (e.g. tailnet) IP — **never a public interface**; the network is the
|
||||
auth boundary. Example systemd user service:
|
||||
|
||||
```ini
|
||||
# ~/.config/systemd/user/clidash.service
|
||||
[Unit]
|
||||
Description=clidash read-only CLI dashboard
|
||||
|
||||
[Service]
|
||||
WorkingDirectory=%h/nanoclaw/tools/clidash
|
||||
ExecStart=/usr/bin/node %h/nanoclaw/tools/clidash/server.js
|
||||
Environment=BIND=127.0.0.1
|
||||
Restart=on-failure
|
||||
|
||||
[Install]
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
Then `systemctl --user enable --now clidash`.
|
||||
@@ -1,80 +0,0 @@
|
||||
// Message-activity reader for clidash.
|
||||
//
|
||||
// ncl has no `messages` resource — message data lives in the per-session SQLite
|
||||
// DBs (`data/v2-sessions/<group>/<session>/{inbound,outbound}.db`). We read them
|
||||
// read-only with Node's built-in `node:sqlite` (no new dependency) and aggregate
|
||||
// per-session in/out totals + a daily time-series for charting.
|
||||
|
||||
import { readdirSync, existsSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { DatabaseSync } from 'node:sqlite';
|
||||
|
||||
// Timestamps come in two shapes across tables: SQLite "YYYY-MM-DD HH:MM:SS" (UTC)
|
||||
// and already-ISO "YYYY-MM-DDTHH:MM:SS.sssZ". Normalize to a comparable ISO form
|
||||
// so date-bucketing and max("last") work regardless of which a row used.
|
||||
function normTs(ts) {
|
||||
if (typeof ts !== 'string' || ts.length < 10) return null;
|
||||
if (ts.includes('T')) return ts; // already ISO
|
||||
return `${ts.replace(' ', 'T')}Z`;
|
||||
}
|
||||
|
||||
function readTable(dbPath, table) {
|
||||
let db;
|
||||
try {
|
||||
db = new DatabaseSync(dbPath, { readOnly: true });
|
||||
const rows = db.prepare(`SELECT timestamp FROM ${table}`).all();
|
||||
const byDay = new Map();
|
||||
let last = null;
|
||||
for (const r of rows) {
|
||||
const ts = normTs(r.timestamp);
|
||||
if (!ts) continue;
|
||||
const day = ts.slice(0, 10); // ISO date prefix
|
||||
byDay.set(day, (byDay.get(day) ?? 0) + 1);
|
||||
if (last === null || ts > last) last = ts;
|
||||
}
|
||||
return { total: rows.length, byDay, last };
|
||||
} catch {
|
||||
return { total: 0, byDay: new Map(), last: null }; // missing/locked/corrupt → skip
|
||||
} finally {
|
||||
try { db?.close(); } catch { /* already closed */ }
|
||||
}
|
||||
}
|
||||
|
||||
function listDirs(path) {
|
||||
try {
|
||||
return readdirSync(path, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Aggregate message activity across all session DBs under `sessionsRoot`.
|
||||
* @returns {{ sessions: Array, series: Array<{date,in,out}> }}
|
||||
* sessions — per session: { agent_group_id, session_id, in, out, lastActivity }
|
||||
* series — one bucket per day for the last `days` days (UTC, newest last)
|
||||
*/
|
||||
export function collectActivity(sessionsRoot, days, now) {
|
||||
const dates = [];
|
||||
for (let i = days - 1; i >= 0; i--) {
|
||||
dates.push(new Date(now.getTime() - i * 86_400_000).toISOString().slice(0, 10));
|
||||
}
|
||||
const series = new Map(dates.map((d) => [d, { date: d, in: 0, out: 0 }]));
|
||||
const sessions = [];
|
||||
|
||||
for (const group of listDirs(sessionsRoot)) {
|
||||
for (const session of listDirs(join(sessionsRoot, group))) {
|
||||
const base = join(sessionsRoot, group, session);
|
||||
// a real session dir has at least one of the two message DBs; skip shared
|
||||
// scaffolding dirs like `.claude-shared` that don't.
|
||||
if (!existsSync(join(base, 'inbound.db')) && !existsSync(join(base, 'outbound.db'))) continue;
|
||||
const inb = readTable(join(base, 'inbound.db'), 'messages_in');
|
||||
const out = readTable(join(base, 'outbound.db'), 'messages_out');
|
||||
const lastActivity = [inb.last, out.last].filter(Boolean).sort().at(-1) ?? null;
|
||||
sessions.push({ agent_group_id: group, session_id: session, in: inb.total, out: out.total, lastActivity });
|
||||
for (const [day, n] of inb.byDay) series.get(day)?.in !== undefined && (series.get(day).in += n);
|
||||
for (const [day, n] of out.byDay) series.get(day)?.out !== undefined && (series.get(day).out += n);
|
||||
}
|
||||
}
|
||||
return { sessions, series: dates.map((d) => series.get(d)) };
|
||||
}
|
||||
@@ -1,106 +0,0 @@
|
||||
{
|
||||
"port": 4690,
|
||||
"bind": "127.0.0.1",
|
||||
"refreshSeconds": 60,
|
||||
"clis": {
|
||||
"ncl": {
|
||||
"bin": "bin/ncl",
|
||||
"cwd": "../..",
|
||||
"discover": { "args": ["help"], "parser": "ncl-help" },
|
||||
"list": ["{resource}", "list", "--json"],
|
||||
"output": "json",
|
||||
"unwrap": "data",
|
||||
"commands": {
|
||||
"get": ["{resource}", "get", "--id", "{id}", "--json"],
|
||||
"config-get": ["groups", "config", "get", "--id", "{id}", "--json"]
|
||||
},
|
||||
"help": ["{resource}", "help"],
|
||||
"enrich": {
|
||||
"sessions": {
|
||||
"agent_group_id": { "ref": "groups", "label": "name" },
|
||||
"messaging_group_id": { "ref": "messaging-groups", "label": "name" }
|
||||
},
|
||||
"wirings": {
|
||||
"agent_group_id": { "ref": "groups", "label": "name" },
|
||||
"messaging_group_id": { "ref": "messaging-groups", "label": "name" }
|
||||
},
|
||||
"roles": {
|
||||
"agent_group_id": { "ref": "groups", "label": "name" },
|
||||
"user_id": { "ref": "users", "label": "display_name" },
|
||||
"granted_by": { "ref": "users", "label": "display_name" }
|
||||
},
|
||||
"members": {
|
||||
"agent_group_id": { "ref": "groups", "label": "name" },
|
||||
"user_id": { "ref": "users", "label": "display_name" }
|
||||
},
|
||||
"destinations": {
|
||||
"agent_group_id": { "ref": "groups", "label": "name" }
|
||||
},
|
||||
"user-dms": {
|
||||
"user_id": { "ref": "users", "label": "display_name" },
|
||||
"messaging_group_id": { "ref": "messaging-groups", "label": "name" }
|
||||
}
|
||||
},
|
||||
"badges": {
|
||||
"container_status": { "running": "green", "idle": "green", "starting": "amber", "stopped": "gray", "error": "red" },
|
||||
"status": { "active": "green", "stopped": "gray", "error": "red", "pending": "amber" }
|
||||
},
|
||||
"summary": {
|
||||
"sessions": "container_status",
|
||||
"messaging-groups": "channel_type",
|
||||
"roles": "role",
|
||||
"users": "kind",
|
||||
"destinations": "target_type",
|
||||
"dropped-messages": "reason"
|
||||
}
|
||||
},
|
||||
"docker": {
|
||||
"bin": "docker",
|
||||
"resources": ["ps", "images"],
|
||||
"list": ["{resource}", "--format", "{{json .}}"],
|
||||
"output": "jsonlines"
|
||||
}
|
||||
},
|
||||
"activity": {
|
||||
"sessionsRoot": "../../data/v2-sessions",
|
||||
"days": 14
|
||||
},
|
||||
"logs": {
|
||||
"dir": "../../logs",
|
||||
"tailLines": 500,
|
||||
"files": [
|
||||
{ "name": "nanoclaw.log", "label": "host log" },
|
||||
{ "name": "nanoclaw.error.log", "label": "errors" }
|
||||
]
|
||||
},
|
||||
"docs": {
|
||||
"root": "../..",
|
||||
"deny": ["node_modules", ".env", "*token*", "*secret*", "*.pem", "*.key", "*.lock", "pnpm-lock.yaml"],
|
||||
"collections": [
|
||||
{
|
||||
"name": "skills",
|
||||
"label": "Skills",
|
||||
"lang": "markdown",
|
||||
"patterns": ["groups/*/skills/*/SKILL.md", "container/skills/*/SKILL.md"]
|
||||
},
|
||||
{
|
||||
"name": "claude-md",
|
||||
"label": "CLAUDE.md",
|
||||
"lang": "markdown",
|
||||
"patterns": ["groups/*/CLAUDE.md", "groups/*/CLAUDE.local.md"]
|
||||
},
|
||||
{
|
||||
"name": "profiles",
|
||||
"label": "Profiles",
|
||||
"lang": "json",
|
||||
"patterns": ["groups/*/profile.json"]
|
||||
},
|
||||
{
|
||||
"name": "conversations",
|
||||
"label": "Conversations",
|
||||
"lang": "markdown",
|
||||
"patterns": ["groups/*/conversations/*.md"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,102 +0,0 @@
|
||||
// Read-only file viewer for clidash.
|
||||
//
|
||||
// Surfaces on-disk documents (skills, CLAUDE.md, profile.json, conversations)
|
||||
// that are NOT ncl resources. Same security posture as the rest of clidash:
|
||||
// only files matching a configured collection's glob patterns are listable or
|
||||
// readable; a deny-list blocks secrets; path traversal is impossible because a
|
||||
// requested path must be a member of the freshly-globbed allow-set.
|
||||
|
||||
import { readdirSync, realpathSync } from 'node:fs';
|
||||
import { join, resolve, sep } from 'node:path';
|
||||
|
||||
// Convert one glob segment to an anchored regex. `*` matches any run of
|
||||
// non-slash chars (so it works both as a whole segment and inside a filename,
|
||||
// e.g. `CLAUDE*.md`). All other regex metacharacters are escaped.
|
||||
function segToRegExp(seg) {
|
||||
const esc = seg.replace(/[.+^${}()|[\]\\?]/g, '\\$&').replace(/\*/g, '[^/]*');
|
||||
return new RegExp('^' + esc + '$');
|
||||
}
|
||||
|
||||
// A path is denied if any of its segments matches any deny glob.
|
||||
function isDenied(relPath, deny) {
|
||||
const segs = relPath.split('/');
|
||||
return deny.some((d) => {
|
||||
const re = segToRegExp(d);
|
||||
return segs.some((s) => re.test(s));
|
||||
});
|
||||
}
|
||||
|
||||
// Directed walk: descend only entries matching each successive pattern segment.
|
||||
function walk(root, rel, segs, depth, out, deny) {
|
||||
if (depth >= segs.length) return;
|
||||
let entries;
|
||||
try {
|
||||
entries = readdirSync(join(root, rel), { withFileTypes: true });
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
const re = segToRegExp(segs[depth]);
|
||||
const last = depth === segs.length - 1;
|
||||
for (const e of entries) {
|
||||
if (e.name === '.' || e.name === '..') continue;
|
||||
if (!re.test(e.name)) continue;
|
||||
const childRel = rel ? `${rel}/${e.name}` : e.name;
|
||||
if (isDenied(childRel, deny)) continue;
|
||||
if (last) {
|
||||
if (e.isFile()) out.add(childRel);
|
||||
} else if (e.isDirectory()) {
|
||||
walk(root, childRel, segs, depth + 1, out, deny);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Relative paths under `root` matching any of `patterns`, minus `deny` matches.
|
||||
* Sorted, de-duplicated. Patterns use `*` per the segment rules above; no `**`.
|
||||
*/
|
||||
export function globFiles(root, patterns, deny = []) {
|
||||
const out = new Set();
|
||||
for (const pattern of patterns) {
|
||||
walk(root, '', pattern.split('/'), 0, out, deny);
|
||||
}
|
||||
return [...out].sort();
|
||||
}
|
||||
|
||||
/**
|
||||
* Human-friendly grouping/label for a relative path.
|
||||
* `groups/<g>/...` → group `<g>`; `container/...` → group `shared`.
|
||||
*/
|
||||
const CONTAINER_SEGS = new Set(['skills', 'conversations']); // redundant grouping dirs
|
||||
export function describeFile(relPath) {
|
||||
const parts = relPath.split('/');
|
||||
if (parts[0] === 'groups' && parts.length > 2) {
|
||||
const rest = parts.slice(2).filter((s) => !CONTAINER_SEGS.has(s)).join('/');
|
||||
return { group: parts[1], label: `${parts[1]} / ${rest}` };
|
||||
}
|
||||
if (parts[0] === 'container') {
|
||||
const rest = parts.slice(2).filter((s) => !CONTAINER_SEGS.has(s)).join('/');
|
||||
return { group: 'shared', label: `shared / ${rest}` };
|
||||
}
|
||||
return { group: '', label: relPath };
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate a requested doc path against a collection and return its absolute
|
||||
* path, or throw. A path is allowed only if it is a member of the collection's
|
||||
* freshly-globbed allow-set — this single check enforces the patterns, the
|
||||
* deny-list, and traversal safety at once.
|
||||
*/
|
||||
export function resolveDoc(root, collection, relPath, deny = []) {
|
||||
const allowed = new Set(globFiles(root, collection.patterns, deny));
|
||||
if (!allowed.has(relPath)) {
|
||||
throw new Error(`Path not allowed: ${relPath}`);
|
||||
}
|
||||
// Defence in depth: the resolved real path must still live under root.
|
||||
const abs = resolve(root, relPath);
|
||||
const rootReal = realpathSync(root);
|
||||
const absReal = realpathSync(abs);
|
||||
if (absReal !== rootReal && !absReal.startsWith(rootReal + sep)) {
|
||||
throw new Error(`Path not allowed: ${relPath}`);
|
||||
}
|
||||
return abs;
|
||||
}
|
||||
@@ -1,18 +0,0 @@
|
||||
// Log tailing for clidash — reads the last N lines of an allowlisted log file
|
||||
// and strips ANSI color codes (the host logger writes colored output).
|
||||
|
||||
import { readFile } from 'node:fs/promises';
|
||||
|
||||
const ANSI_RE = /\x1b\[[0-9;]*m/g;
|
||||
|
||||
/**
|
||||
* Last `maxLines` lines of a log file, ANSI-stripped.
|
||||
* @returns {{ lines: string[], text: string }}
|
||||
*/
|
||||
export async function tailFile(path, maxLines) {
|
||||
const raw = (await readFile(path, 'utf8')).replace(ANSI_RE, '');
|
||||
const all = raw.split('\n');
|
||||
if (all.length && all.at(-1) === '') all.pop(); // drop trailing newline's empty field
|
||||
const lines = all.slice(-maxLines);
|
||||
return { lines, text: lines.join('\n') };
|
||||
}
|
||||
@@ -1,14 +0,0 @@
|
||||
{
|
||||
"name": "clidash",
|
||||
"version": "0.1.0",
|
||||
"description": "CLI-agnostic read-only web dashboard — derives tabs and tables from any CLI that lists resources as JSON",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"start": "node server.js",
|
||||
"test": "node --test 'test/*.test.js'"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=22.5"
|
||||
}
|
||||
}
|
||||
@@ -1,101 +0,0 @@
|
||||
// Pluggable parsers for clidash.
|
||||
//
|
||||
// discoveryParsers — turn a CLI's "help"-style output into a resource list.
|
||||
// parseOutput / unwrapPath — turn a CLI's list output into rows.
|
||||
// All per-CLI knowledge beyond these small functions lives in clidash.config.json.
|
||||
|
||||
/**
|
||||
* Discovery parsers, keyed by the `discover.parser` name in config.
|
||||
* Each receives the raw discovery output and returns
|
||||
* [{ name, description, verbs }] for resources that support `list`.
|
||||
* They must throw loudly on unrecognized formats — silent empty results
|
||||
* would render as silently-stale tabs.
|
||||
*/
|
||||
export const discoveryParsers = {
|
||||
/**
|
||||
* Parses ncl's two-column help format:
|
||||
*
|
||||
* Resources:
|
||||
* sessions Session — the runtime unit. ...
|
||||
* verbs: list, get
|
||||
* Commands:
|
||||
* help ...
|
||||
*/
|
||||
'ncl-help'(text) {
|
||||
const lines = String(text).split('\n');
|
||||
const start = lines.findIndex((l) => l.trim() === 'Resources:');
|
||||
if (start === -1) {
|
||||
throw new Error('ncl-help parser: no "Resources:" section in output — format may have changed');
|
||||
}
|
||||
const resources = [];
|
||||
let current = null;
|
||||
for (let i = start + 1; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
if (line.trim() === '') continue;
|
||||
if (/^\S/.test(line)) break; // next top-level section, e.g. "Commands:"
|
||||
const verbsMatch = line.match(/^\s+verbs:\s*(.+)$/);
|
||||
if (verbsMatch && current) {
|
||||
current.verbs = verbsMatch[1].split(',').map((v) => v.trim()).filter(Boolean);
|
||||
continue;
|
||||
}
|
||||
const resMatch = line.match(/^ (\S+)\s{2,}(\S.*)$/);
|
||||
if (resMatch) {
|
||||
current = { name: resMatch[1], description: resMatch[2].trim(), verbs: [] };
|
||||
resources.push(current);
|
||||
}
|
||||
}
|
||||
return resources.filter((r) => r.verbs.includes('list'));
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* Parses a CLI's list output per the config's `output` field.
|
||||
* - 'json' — one JSON document.
|
||||
* - 'jsonlines' — one JSON object per line (docker/kubectl style).
|
||||
* Thrown errors carry the raw output on `err.raw` so the UI can show it.
|
||||
*/
|
||||
export function parseOutput(text, format) {
|
||||
if (format === 'json') {
|
||||
try {
|
||||
return JSON.parse(text);
|
||||
} catch (e) {
|
||||
const err = new Error(`Invalid JSON output: ${e.message}`);
|
||||
err.raw = text;
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
if (format === 'jsonlines') {
|
||||
const rows = [];
|
||||
const lines = String(text).split('\n');
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i].trim();
|
||||
if (!line) continue;
|
||||
try {
|
||||
rows.push(JSON.parse(line));
|
||||
} catch (e) {
|
||||
const err = new Error(`Invalid JSON on line ${i + 1}: ${e.message}`);
|
||||
err.raw = text;
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
throw new Error(`Unknown output format: ${format}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Follows a dot-path into a response envelope (e.g. 'data' for ncl's
|
||||
* {id, ok, data} frame). No path → value passes through unchanged.
|
||||
* Missing path throws — a changed envelope must fail loudly.
|
||||
*/
|
||||
export function unwrapPath(value, path) {
|
||||
if (!path) return value;
|
||||
let cur = value;
|
||||
for (const key of path.split('.')) {
|
||||
if (cur === null || typeof cur !== 'object' || !(key in cur)) {
|
||||
throw new Error(`Unwrap path "${path}" not found in CLI output (missing "${key}")`);
|
||||
}
|
||||
cur = cur[key];
|
||||
}
|
||||
return cur;
|
||||
}
|
||||
@@ -1,715 +0,0 @@
|
||||
// clidash frontend — vanilla JS, no build step.
|
||||
//
|
||||
// Layout: a left sidebar with top-level items (Overview, Activity) and grouped
|
||||
// sections (one per CLI — ncl, docker — and a Files section for on-disk docs).
|
||||
// Each page shows the exact command that produced it. Tables auto-derive from
|
||||
// `ncl <resource> list --json`; rows drill into their `get` detail.
|
||||
//
|
||||
// Refresh UX: on first load every resource of every CLI is prefetched so nav is
|
||||
// instant. 60s auto-refresh + a manual button. Background refreshes diff-and-
|
||||
// inject (the data DOM rebuilds only when the data signature changes).
|
||||
|
||||
import { mdToHtml } from './md.js';
|
||||
|
||||
const $ = (id) => document.getElementById(id);
|
||||
|
||||
const state = {
|
||||
clis: [],
|
||||
docCollections: [],
|
||||
activeView: 'overview', // 'overview' | 'activity' | 'r:<cli>:<resource>' | 'doc:<collection>'
|
||||
paused: false,
|
||||
refreshSeconds: 60,
|
||||
lastUpdated: null,
|
||||
refreshing: false,
|
||||
snapshots: new Map(), // "cli/resource" -> { rows, fetchedAt, command }
|
||||
errors: new Map(),
|
||||
activity: null, // { sessions, series }
|
||||
activityConfigured: false,
|
||||
activityCommand: null,
|
||||
logs: [], // [{ name, label }]
|
||||
logCache: new Map(), // name -> { text, command }
|
||||
activeDocPath: null,
|
||||
openDocGroups: new Set(), // which doc groups (e.g. agents) are expanded
|
||||
docCache: new Map(),
|
||||
configCache: new Map(), // groupId -> container config (for the overview page)
|
||||
helpCache: new Map(), // "cli/resource" -> help text | null (prefetched each cycle)
|
||||
detail: null,
|
||||
sidebarOpen: false,
|
||||
renderedSig: null,
|
||||
};
|
||||
|
||||
const SVG_NS = 'http://www.w3.org/2000/svg';
|
||||
function svg(tag, attrs = {}, children = []) {
|
||||
const node = document.createElementNS(SVG_NS, tag);
|
||||
for (const [k, v] of Object.entries(attrs)) node.setAttribute(k, v);
|
||||
for (const c of [].concat(children)) if (c != null) node.append(c);
|
||||
return node;
|
||||
}
|
||||
|
||||
// Lucide-style inline icons (static trusted markup) — crisp, themeable via currentColor.
|
||||
const ICONS = {
|
||||
overview: '<rect x="3" y="3" width="7" height="9" rx="1"/><rect x="14" y="3" width="7" height="5" rx="1"/><rect x="14" y="12" width="7" height="9" rx="1"/><rect x="3" y="16" width="7" height="5" rx="1"/>',
|
||||
activity: '<path d="M3 3v18h18"/><path d="M18 17V9"/><path d="M13 17V5"/><path d="M8 17v-3"/>',
|
||||
terminal: '<rect x="2" y="4" width="20" height="16" rx="2"/><path d="m6 9 3 3-3 3"/><path d="M13 15h4"/>',
|
||||
box: '<path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/>',
|
||||
folder: '<path d="M4 20h16a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13c0 1.1.9 2 2 2Z"/>',
|
||||
logs: '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v5h5"/><path d="M8 13h8"/><path d="M8 17h5"/>',
|
||||
};
|
||||
function icon(name) {
|
||||
const s = document.createElementNS(SVG_NS, 'svg');
|
||||
s.setAttribute('viewBox', '0 0 24 24');
|
||||
s.setAttribute('fill', 'none');
|
||||
s.setAttribute('stroke', 'currentColor');
|
||||
s.setAttribute('stroke-width', '1.8');
|
||||
s.setAttribute('stroke-linecap', 'round');
|
||||
s.setAttribute('stroke-linejoin', 'round');
|
||||
s.innerHTML = ICONS[name] ?? '';
|
||||
return s;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- helpers
|
||||
|
||||
const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/;
|
||||
|
||||
function relTime(iso) {
|
||||
const ms = Date.now() - new Date(iso).getTime();
|
||||
if (Number.isNaN(ms)) return iso;
|
||||
const s = Math.round(ms / 1000);
|
||||
if (s < 0) return new Date(iso).toLocaleString();
|
||||
if (s < 60) return `${s}s ago`;
|
||||
const m = Math.round(s / 60);
|
||||
if (m < 60) return `${m}m ago`;
|
||||
const h = Math.round(m / 60);
|
||||
if (h < 48) return `${h}h ago`;
|
||||
return `${Math.round(h / 24)}d ago`;
|
||||
}
|
||||
|
||||
function coarseAgo(date) {
|
||||
const s = (Date.now() - date.getTime()) / 1000;
|
||||
if (s < 60) return 'less than a minute ago';
|
||||
const m = Math.floor(s / 60);
|
||||
if (m < 60) return m === 1 ? '1 minute ago' : `${m} minutes ago`;
|
||||
const h = Math.floor(m / 60);
|
||||
if (h < 24) return h === 1 ? '1 hour ago' : `${h} hours ago`;
|
||||
const d = Math.floor(h / 24);
|
||||
return d === 1 ? '1 day ago' : `${d} days ago`;
|
||||
}
|
||||
|
||||
function staleness(lastActive) {
|
||||
if (!lastActive) return 'gray';
|
||||
const min = (Date.now() - new Date(lastActive).getTime()) / 60000;
|
||||
if (Number.isNaN(min)) return 'gray';
|
||||
return min < 15 ? 'green' : min < 120 ? 'amber' : 'red';
|
||||
}
|
||||
|
||||
function el(tag, attrs = {}, children = []) {
|
||||
const node = document.createElement(tag);
|
||||
for (const [k, v] of Object.entries(attrs)) {
|
||||
if (k === 'class') node.className = v;
|
||||
else if (k.startsWith('on')) node.addEventListener(k.slice(2), v);
|
||||
else node.setAttribute(k, v);
|
||||
}
|
||||
for (const child of [].concat(children)) {
|
||||
if (child == null) continue;
|
||||
node.append(child instanceof Node ? child : document.createTextNode(String(child)));
|
||||
}
|
||||
return node;
|
||||
}
|
||||
|
||||
function fmtValue(value) {
|
||||
if (value === null || value === undefined) return { text: 'null', cls: 'null' };
|
||||
if (typeof value === 'string' && ISO_RE.test(value)) return { iso: value };
|
||||
return { text: typeof value === 'object' ? JSON.stringify(value) : String(value) };
|
||||
}
|
||||
|
||||
function cellFor(value) {
|
||||
const f = fmtValue(value);
|
||||
if (f.cls === 'null') return el('td', { class: 'null' }, 'null');
|
||||
if (f.iso) {
|
||||
return el('td', {}, el('span', { class: 'reltime', title: f.iso }, [
|
||||
relTime(f.iso), el('span', { class: 'abs' }, f.iso.slice(0, 16).replace('T', ' ')),
|
||||
]));
|
||||
}
|
||||
if (f.text.length > 42) {
|
||||
const span = el('span', { class: 'trunc', title: f.text }, f.text.slice(0, 39) + '…');
|
||||
span.addEventListener('click', (e) => { e.stopPropagation(); span.textContent = f.text; span.classList.remove('trunc'); });
|
||||
return el('td', {}, span);
|
||||
}
|
||||
return el('td', {}, f.text);
|
||||
}
|
||||
|
||||
function kvRows(obj) {
|
||||
return Object.entries(obj ?? {}).map(([k, v]) => {
|
||||
let valEl;
|
||||
if (v && typeof v === 'object') valEl = el('pre', { class: 'kv-json' }, JSON.stringify(v, null, 2));
|
||||
else if (typeof v === 'string' && ISO_RE.test(v)) valEl = el('span', { class: 'reltime', title: v }, `${relTime(v)} (${v.slice(0, 16).replace('T', ' ')})`);
|
||||
else if (v === null || v === undefined) valEl = el('span', { class: 'null' }, 'null');
|
||||
else valEl = el('span', {}, String(v));
|
||||
return el('div', { class: 'kv-row' }, [el('span', { class: 'kv-key' }, k), valEl]);
|
||||
});
|
||||
}
|
||||
|
||||
function resolveRef(cliName, ref, id) {
|
||||
const snap = state.snapshots.get(`${cliName}/${ref.ref}`);
|
||||
const row = snap?.rows?.find((r) => String(r.id) === String(id));
|
||||
return row ? (row[ref.label] ?? null) : null;
|
||||
}
|
||||
|
||||
function badgeChip(value, colorMap) {
|
||||
const color = colorMap[String(value).toLowerCase()] ?? 'gray';
|
||||
return el('span', { class: `badge-status ${color}` }, [el('span', { class: `dot ${color}` }), String(value)]);
|
||||
}
|
||||
|
||||
function buildCell(value, column, ctx) {
|
||||
if (ctx.badges?.[column] && value != null && typeof value !== 'object') {
|
||||
return el('td', {}, badgeChip(value, ctx.badges[column]));
|
||||
}
|
||||
if (ctx.enrich?.[column] && value != null) {
|
||||
const name = resolveRef(ctx.cliName, ctx.enrich[column], value);
|
||||
if (name != null) {
|
||||
return el('td', { class: 'enriched', title: String(value) }, [
|
||||
el('span', {}, String(name)), el('span', { class: 'raw-id' }, String(value)),
|
||||
]);
|
||||
}
|
||||
}
|
||||
return cellFor(value);
|
||||
}
|
||||
|
||||
function summaryBar(resource, rows, col, cli) {
|
||||
let label = resource.replace(/-/g, ' ');
|
||||
if (rows.length === 1 && label.endsWith('s')) label = label.slice(0, -1);
|
||||
const bits = [el('span', { class: 'sum-count' }, `${rows.length} ${label}`)];
|
||||
if (col && rows.some((r) => col in r)) {
|
||||
const counts = new Map();
|
||||
for (const r of rows) { const v = r[col] ?? '—'; counts.set(v, (counts.get(v) ?? 0) + 1); }
|
||||
const colorMap = cli.badges?.[col];
|
||||
for (const [v, n] of [...counts.entries()].sort((a, b) => b[1] - a[1])) {
|
||||
bits.push(el('span', { class: 'sum-sep' }, '·'));
|
||||
const c = colorMap?.[String(v).toLowerCase()] ?? null;
|
||||
bits.push(c
|
||||
? el('span', { class: `badge-status ${c}` }, [el('span', { class: `dot ${c}` }), `${v} ×${n}`])
|
||||
: el('span', { class: 'sum-chip' }, `${v} ×${n}`));
|
||||
}
|
||||
}
|
||||
return el('div', { class: 'summary-bar' }, bits);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- views
|
||||
|
||||
const nclCli = () => state.clis.find((c) => c.name === 'ncl') ?? state.clis[0];
|
||||
function currentView() {
|
||||
const v = state.activeView;
|
||||
if (v === 'overview' || v === 'activity') return { type: v };
|
||||
const m = v.match(/^r:([^:]+):(.+)$/);
|
||||
if (m) return { type: 'resource', cli: m[1], resource: m[2] };
|
||||
if (v.startsWith('doc:')) return { type: 'doc', collection: v.slice(4) };
|
||||
if (v.startsWith('log:')) return { type: 'log', name: v.slice(4) };
|
||||
return { type: 'overview' };
|
||||
}
|
||||
const activeCollection = () => {
|
||||
const v = currentView();
|
||||
return v.type === 'doc' ? state.docCollections.find((c) => c.name === v.collection) : null;
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------- fetching
|
||||
|
||||
async function fetchJson(url) {
|
||||
const res = await fetch(url);
|
||||
return res.json().catch(() => ({ ok: false, error: `Bad response from ${url}` }));
|
||||
}
|
||||
|
||||
async function refresh(force = false) {
|
||||
state.refreshing = true;
|
||||
if (force) renderControls();
|
||||
|
||||
const [cliList, docList, logList] = await Promise.all([
|
||||
fetchJson('/api/clis').catch(() => null),
|
||||
fetchJson('/api/docs').catch(() => null),
|
||||
fetchJson('/api/logs').catch(() => null),
|
||||
]);
|
||||
if (cliList?.clis) {
|
||||
state.clis = cliList.clis;
|
||||
state.refreshSeconds = cliList.clis[0]?.refreshSeconds ?? state.refreshSeconds;
|
||||
}
|
||||
if (docList?.collections) state.docCollections = docList.collections;
|
||||
if (logList?.files) state.logs = logList.files;
|
||||
|
||||
render(); // paint sidebar + active view's loading state immediately
|
||||
|
||||
const jobs = [];
|
||||
jobs.push(fetchJson('/api/activity').then((body) => {
|
||||
if (body.ok && body.configured) {
|
||||
state.activity = { sessions: body.sessions, series: body.series };
|
||||
state.activityConfigured = true; state.activityCommand = body.command ?? null;
|
||||
} else state.activityConfigured = false;
|
||||
render();
|
||||
}));
|
||||
for (const lg of state.logs) {
|
||||
jobs.push(fetchJson(`/api/log/${encodeURIComponent(lg.name)}`).then((body) => {
|
||||
if (body.ok) state.logCache.set(lg.name, { text: body.text, command: body.command });
|
||||
render();
|
||||
}));
|
||||
}
|
||||
for (const c of state.clis) {
|
||||
for (const r of c.resources ?? []) {
|
||||
const key = `${c.name}/${r.name}`;
|
||||
jobs.push(fetchJson(`/api/r/${c.name}/${encodeURIComponent(r.name)}`).then((body) => {
|
||||
if (body.ok) { state.snapshots.set(key, { rows: body.rows, fetchedAt: body.fetchedAt, command: body.command }); state.errors.set(key, null); }
|
||||
else state.errors.set(key, body.raw ? `${body.error}\n\n${body.raw}` : body.error);
|
||||
render();
|
||||
}));
|
||||
if (c.help) {
|
||||
jobs.push(fetchJson(`/api/help/${c.name}/${encodeURIComponent(r.name)}`).then((body) => {
|
||||
state.helpCache.set(key, body.ok ? body.text : null);
|
||||
render();
|
||||
}));
|
||||
}
|
||||
}
|
||||
}
|
||||
await Promise.all(jobs);
|
||||
|
||||
// per-group container config (for the Overview page) — small, refetched each cycle
|
||||
const groups = state.snapshots.get('ncl/groups')?.rows ?? [];
|
||||
await Promise.all(groups.map(async (g) => {
|
||||
const c = await fetchJson(`/api/cmd/ncl/config-get?id=${encodeURIComponent(g.id)}`);
|
||||
if (c.ok) state.configCache.set(g.id, c.data);
|
||||
}));
|
||||
|
||||
state.lastUpdated = new Date();
|
||||
state.refreshing = false;
|
||||
render();
|
||||
}
|
||||
|
||||
async function openDoc(collectionName, path) {
|
||||
state.activeDocPath = path;
|
||||
const key = `${collectionName}\0${path}`;
|
||||
if (!state.docCache.has(key)) {
|
||||
const body = await fetchJson(`/api/doc?c=${encodeURIComponent(collectionName)}&p=${encodeURIComponent(path)}`);
|
||||
state.docCache.set(key, body.ok ? { lang: body.lang, content: body.content } : { lang: 'error', content: body.error || 'Failed to load' });
|
||||
}
|
||||
state.renderedSig = null;
|
||||
render();
|
||||
}
|
||||
|
||||
async function openDetail(cliName, resource, id) {
|
||||
state.detail = { cli: cliName, resource, id, loading: true };
|
||||
state.renderedSig = null;
|
||||
render();
|
||||
const rec = await fetchJson(`/api/cmd/${cliName}/get?resource=${encodeURIComponent(resource)}&id=${encodeURIComponent(id)}`);
|
||||
let config = null;
|
||||
if (resource === 'groups') {
|
||||
const cg = await fetchJson(`/api/cmd/${cliName}/config-get?id=${encodeURIComponent(id)}`);
|
||||
if (cg.ok) config = cg.data;
|
||||
}
|
||||
if (!state.detail || state.detail.id !== id) return;
|
||||
state.detail = { cli: cliName, resource, id, record: rec.ok ? rec.data : null, error: rec.ok ? null : rec.error, config };
|
||||
state.renderedSig = null;
|
||||
render();
|
||||
}
|
||||
|
||||
function closeDetail() { state.detail = null; state.renderedSig = null; render(); }
|
||||
|
||||
// Help panel: the description (first paragraph) is always visible; the verbs +
|
||||
// fields (everything after the first blank line) sit behind a collapse.
|
||||
function helpPanel(text) {
|
||||
if (text === null) return null; // explicitly no help
|
||||
if (text === undefined) return el('div', { class: 'help-panel' }, el('div', { class: 'help-head dim' }, 'loading help…'));
|
||||
const idx = text.indexOf('\n\n');
|
||||
const head = (idx >= 0 ? text.slice(0, idx) : text).trim();
|
||||
const body = idx >= 0 ? text.slice(idx + 2).trim() : '';
|
||||
return el('div', { class: 'help-panel' }, [
|
||||
el('div', { class: 'help-head' }, head),
|
||||
body ? el('details', { class: 'help-more' }, [
|
||||
el('summary', {}, 'verbs & fields'),
|
||||
el('pre', { class: 'help-text' }, body),
|
||||
]) : null,
|
||||
]);
|
||||
}
|
||||
|
||||
function go(view) {
|
||||
state.activeView = view;
|
||||
state.detail = null;
|
||||
state.sidebarOpen = false;
|
||||
state.renderedSig = null;
|
||||
const v = currentView();
|
||||
if (v.type === 'doc') {
|
||||
const coll = state.docCollections.find((c) => c.name === v.collection);
|
||||
const first = coll && (coll.name === 'conversations' ? coll.files.at(-1) : coll.files[0]); // newest conversation
|
||||
state.activeDocPath = state.activeDocPath && coll?.files.some((f) => f.path === state.activeDocPath)
|
||||
? state.activeDocPath : (first?.path ?? null);
|
||||
// expand only the group holding the active doc; the user picks the rest
|
||||
const activeFile = coll?.files.find((f) => f.path === state.activeDocPath);
|
||||
state.openDocGroups = new Set(activeFile ? [activeFile.group] : []);
|
||||
render();
|
||||
if (state.activeDocPath) openDoc(coll.name, state.activeDocPath);
|
||||
return;
|
||||
}
|
||||
render();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- rendering
|
||||
|
||||
function dataSignature() {
|
||||
const v = currentView();
|
||||
const key = v.type === 'resource' ? `${v.cli}/${v.resource}` : null;
|
||||
const coll = activeCollection();
|
||||
return JSON.stringify({
|
||||
view: state.activeView, clis: state.clis.map((c) => `${c.name}:${(c.resources || []).length}`),
|
||||
activityConfigured: state.activityConfigured,
|
||||
rows: key ? state.snapshots.get(key)?.rows ?? null : null,
|
||||
rowsError: key ? state.errors.get(key) ?? null : null,
|
||||
command: key ? state.snapshots.get(key)?.command ?? null : null,
|
||||
help: key ? state.helpCache.get(key) ?? null : null,
|
||||
overview: v.type === 'overview' ? {
|
||||
groups: state.snapshots.get('ncl/groups')?.rows ?? null,
|
||||
sessions: state.snapshots.get('ncl/sessions')?.rows ?? null,
|
||||
configs: [...state.configCache.entries()],
|
||||
activity: state.activity?.sessions ?? null,
|
||||
} : null,
|
||||
activity: v.type === 'activity' ? state.activity : null,
|
||||
log: v.type === 'log' ? state.logCache.get(v.name)?.text ?? null : null,
|
||||
docFiles: coll ? coll.files.map((f) => f.path) : null,
|
||||
docPath: state.activeDocPath,
|
||||
docGroupsOpen: coll ? [...state.openDocGroups] : null,
|
||||
docContent: coll ? state.docCache.get(`${coll.name}\0${state.activeDocPath}`)?.content ?? null : null,
|
||||
detail: state.detail, paused: state.paused, sidebarOpen: state.sidebarOpen,
|
||||
});
|
||||
}
|
||||
|
||||
function renderControls() {
|
||||
$('updated').textContent = state.lastUpdated
|
||||
? `updated ${coarseAgo(state.lastUpdated)}${state.paused ? ' · paused' : ''}` : '';
|
||||
$('refresh').classList.toggle('spinning', state.refreshing);
|
||||
}
|
||||
|
||||
function render() {
|
||||
renderControls();
|
||||
const sig = dataSignature();
|
||||
if (sig === state.renderedSig) return;
|
||||
state.renderedSig = sig;
|
||||
|
||||
$('sidebar').classList.toggle('open', state.sidebarOpen);
|
||||
$('scrim').hidden = !state.sidebarOpen;
|
||||
|
||||
renderNav();
|
||||
|
||||
const v = currentView();
|
||||
const banner = $('banner');
|
||||
const tabError = v.type === 'resource' ? state.errors.get(`${v.cli}/${v.resource}`) : null;
|
||||
const cli = v.type === 'resource' ? state.clis.find((c) => c.name === v.cli) : null;
|
||||
const bannerMsg = cli?.error ? `Discovery failed for ${v.cli}: ${cli.error}`
|
||||
: (tabError ? `CLI unreachable — showing last good snapshot. ${tabError.split('\n')[0]}` : null);
|
||||
banner.hidden = !bannerMsg;
|
||||
banner.textContent = bannerMsg ?? '';
|
||||
|
||||
renderCmdline(v);
|
||||
if (v.type === 'overview') renderOverviewPage();
|
||||
else if (v.type === 'activity') renderActivity();
|
||||
else if (v.type === 'doc') renderDocs();
|
||||
else if (v.type === 'log') renderLogPage(v.name);
|
||||
else renderTable(v.cli, v.resource);
|
||||
renderDetail();
|
||||
}
|
||||
|
||||
function navItem(label, view, cls = '', iconName = null) {
|
||||
return el('button', {
|
||||
class: `nav-item ${cls}` + (state.activeView === view ? ' active' : ''),
|
||||
onclick: () => go(view),
|
||||
}, [iconName ? icon(iconName) : null, el('span', {}, label)]);
|
||||
}
|
||||
|
||||
function renderNav() {
|
||||
const nav = $('nav');
|
||||
const items = [navItem('Overview', 'overview', '', 'overview')];
|
||||
if (state.activityConfigured) items.push(navItem('Activity', 'activity', '', 'activity'));
|
||||
|
||||
for (const cli of state.clis) {
|
||||
items.push(el('div', { class: 'nav-section' }, [icon(cli.name === 'docker' ? 'box' : 'terminal'), el('span', {}, cli.name)]));
|
||||
for (const r of cli.resources ?? []) {
|
||||
items.push(navItem(r.name, `r:${cli.name}:${r.name}`, 'nav-sub'));
|
||||
}
|
||||
}
|
||||
if (state.docCollections.length) {
|
||||
items.push(el('div', { class: 'nav-section' }, [icon('folder'), el('span', {}, 'Files')]));
|
||||
for (const coll of state.docCollections) {
|
||||
items.push(navItem(coll.label, `doc:${coll.name}`, 'nav-sub'));
|
||||
}
|
||||
}
|
||||
if (state.logs.length) {
|
||||
items.push(el('div', { class: 'nav-section' }, [icon('logs'), el('span', {}, 'Logs')]));
|
||||
for (const lg of state.logs) {
|
||||
items.push(navItem(lg.label, `log:${lg.name}`, 'nav-sub'));
|
||||
}
|
||||
}
|
||||
nav.replaceChildren(...items);
|
||||
}
|
||||
|
||||
function renderCmdline(v) {
|
||||
const bar = $('cmdline');
|
||||
let cmd = null;
|
||||
if (v.type === 'resource') cmd = state.snapshots.get(`${v.cli}/${v.resource}`)?.command;
|
||||
else if (v.type === 'activity') cmd = state.activityCommand;
|
||||
else if (v.type === 'doc') cmd = state.activeDocPath ? `file · ${state.activeDocPath}` : null;
|
||||
else if (v.type === 'log') cmd = state.logCache.get(v.name)?.command ?? null;
|
||||
else if (v.type === 'overview') cmd = 'derived · ncl groups/sessions/messaging-groups/wirings + config-get + activity';
|
||||
bar.hidden = !cmd;
|
||||
bar.textContent = cmd ? `$ ${cmd}` : '';
|
||||
}
|
||||
|
||||
// ---- Overview page (rich agent cards) ----
|
||||
|
||||
function renderOverviewPage() {
|
||||
const content = $('content');
|
||||
const groups = state.snapshots.get('ncl/groups')?.rows;
|
||||
if (!groups) { content.replaceChildren(el('div', { class: 'empty' }, 'Loading…')); return; }
|
||||
const sessions = state.snapshots.get('ncl/sessions')?.rows ?? [];
|
||||
const wirings = state.snapshots.get('ncl/wirings')?.rows ?? [];
|
||||
const mgs = state.snapshots.get('ncl/messaging-groups')?.rows ?? [];
|
||||
const act = state.activity?.sessions ?? [];
|
||||
const mgName = (id) => mgs.find((m) => m.id === id)?.name ?? mgs.find((m) => m.id === id)?.platform_id ?? id;
|
||||
|
||||
const field = (k, v, cls = '') => el('div', { class: 'ov-field' }, [el('span', { class: 'k' }, k), el('span', { class: `v ${cls}` }, v)]);
|
||||
|
||||
const cards = groups.map((g) => {
|
||||
const gs = sessions.filter((s) => s.agent_group_id === g.id);
|
||||
const lastActive = gs.map((s) => s.last_active).filter(Boolean).sort().at(-1) ?? null;
|
||||
const container = gs.some((s) => s.container_status === 'running') ? 'running' : (gs[0]?.container_status ?? 'none');
|
||||
const ga = act.filter((a) => a.agent_group_id === g.id);
|
||||
const msgIn = ga.reduce((a, s) => a + s.in, 0), msgOut = ga.reduce((a, s) => a + s.out, 0);
|
||||
const cfg = state.configCache.get(g.id);
|
||||
const chans = wirings.filter((w) => w.agent_group_id === g.id).map((w) => `${mgs.find((m) => m.id === w.messaging_group_id)?.channel_type ?? '?'}: ${mgName(w.messaging_group_id)}`);
|
||||
const status = staleness(lastActive);
|
||||
const containerColor = container === 'running' ? 'green' : container === 'idle' ? 'green' : container === 'none' ? 'gray' : 'gray';
|
||||
|
||||
const fields = [
|
||||
el('div', { class: 'ov-field' }, [el('span', { class: 'k' }, 'container'), badgeChip(container, { running: 'green', idle: 'green', stopped: 'gray', none: 'gray' })]),
|
||||
field('sessions', String(gs.length)),
|
||||
field('messages', `${msgIn} in · ${msgOut} out`),
|
||||
field('last active', lastActive ? relTime(lastActive) : '—', lastActive ? '' : 'dim'),
|
||||
];
|
||||
if (cfg) {
|
||||
fields.push(field('provider / model', `${cfg.provider ?? 'claude'} / ${cfg.model ?? 'default'}`));
|
||||
fields.push(el('div', { class: 'ov-field' }, [el('span', { class: 'k' }, 'cli scope'), badgeChip(cfg.cli_scope ?? 'group', { global: 'amber', group: 'green', disabled: 'gray' })]));
|
||||
const pkgs = (cfg.packages_apt?.length ?? 0) + (cfg.packages_npm?.length ?? 0);
|
||||
const mcp = Object.keys(cfg.mcp_servers ?? {}).length;
|
||||
if (pkgs || mcp) fields.push(field('extras', `${pkgs} pkgs · ${mcp} mcp`));
|
||||
}
|
||||
|
||||
return el('div', { class: 'ov-card' }, [
|
||||
el('div', { class: 'ov-head' }, [
|
||||
el('span', { class: `dot ${status}` }),
|
||||
el('span', { class: 'ov-name' }, g.name),
|
||||
el('span', { class: 'ov-folder' }, g.folder),
|
||||
]),
|
||||
el('div', { class: 'ov-fields' }, fields),
|
||||
el('div', { class: 'ov-chans' }, chans.map((c) => el('span', { class: 'badge' }, c))),
|
||||
]);
|
||||
});
|
||||
|
||||
content.replaceChildren(
|
||||
el('h2', { class: 'page-title' }, 'Agents overview'),
|
||||
el('div', { class: 'ov-cards' }, cards),
|
||||
);
|
||||
}
|
||||
|
||||
// ---- Activity ----
|
||||
|
||||
function renderActivity() {
|
||||
const content = $('content');
|
||||
const data = state.activity;
|
||||
if (!data) { content.replaceChildren(el('div', { class: 'empty' }, 'Loading…')); return; }
|
||||
const { series, sessions } = data;
|
||||
const totalIn = series.reduce((a, d) => a + d.in, 0);
|
||||
const totalOut = series.reduce((a, d) => a + d.out, 0);
|
||||
|
||||
const W = 720, H = 220, padL = 34, padB = 28, padT = 10;
|
||||
const max = Math.max(1, ...series.map((d) => Math.max(d.in, d.out)));
|
||||
const slot = (W - padL) / series.length;
|
||||
const bw = Math.max(3, slot / 2 - 2);
|
||||
const yOf = (vv) => padT + (H - padT - padB) * (1 - vv / max);
|
||||
const chart = svg('svg', { viewBox: `0 0 ${W} ${H}`, class: 'activity-chart', preserveAspectRatio: 'none' });
|
||||
for (const frac of [0, 0.5, 1]) {
|
||||
const y = yOf(max * frac);
|
||||
chart.append(svg('line', { x1: padL, y1: y, x2: W, y2: y, class: 'grid' }));
|
||||
chart.append(svg('text', { x: padL - 6, y: y + 3, class: 'axis', 'text-anchor': 'end' }, String(Math.round(max * frac))));
|
||||
}
|
||||
series.forEach((d, i) => {
|
||||
const x = padL + i * slot;
|
||||
chart.append(svg('rect', { x: x + 1, y: yOf(d.in), width: bw, height: yOf(0) - yOf(d.in), class: 'bar-in' }, [svg('title', {}, `${d.date}: ${d.in} in`)]));
|
||||
chart.append(svg('rect', { x: x + 1 + bw, y: yOf(d.out), width: bw, height: yOf(0) - yOf(d.out), class: 'bar-out' }, [svg('title', {}, `${d.date}: ${d.out} out`)]));
|
||||
if (i % 2 === 0) chart.append(svg('text', { x: x + bw, y: H - 8, class: 'axis', 'text-anchor': 'middle' }, d.date.slice(5)));
|
||||
});
|
||||
const legend = el('div', { class: 'activity-legend' }, [
|
||||
el('span', {}, [el('span', { class: 'lg in' }), `inbound (${totalIn})`]),
|
||||
el('span', {}, [el('span', { class: 'lg out' }), `outbound (${totalOut})`]),
|
||||
el('span', { class: 'dim' }, `last ${series.length} days`),
|
||||
]);
|
||||
const sessRows = [...sessions].sort((a, b) => (b.lastActivity || '').localeCompare(a.lastActivity || '')).map((s) => {
|
||||
const groupName = resolveRef('ncl', { ref: 'groups', label: 'name' }, s.agent_group_id) ?? s.agent_group_id;
|
||||
return el('tr', {}, [
|
||||
el('td', {}, groupName),
|
||||
el('td', {}, el('span', { class: 'trunc', title: s.session_id }, s.session_id.slice(0, 22) + '…')),
|
||||
el('td', { class: 'num' }, String(s.in)),
|
||||
el('td', { class: 'num' }, String(s.out)),
|
||||
el('td', {}, s.lastActivity ? el('span', { class: 'reltime', title: s.lastActivity }, relTime(s.lastActivity)) : el('span', { class: 'null' }, '—')),
|
||||
]);
|
||||
});
|
||||
content.replaceChildren(
|
||||
el('h2', { class: 'page-title' }, 'Message activity'),
|
||||
el('div', { class: 'activity-wrap' }, [
|
||||
legend,
|
||||
el('div', { class: 'chart-box' }, chart),
|
||||
el('div', { class: 'table-wrap' }, el('table', { class: 'activity-table' }, [
|
||||
el('thead', {}, el('tr', {}, ['agent', 'session', 'in', 'out', 'last activity'].map((h) => el('th', {}, h)))),
|
||||
el('tbody', {}, sessRows),
|
||||
])),
|
||||
]),
|
||||
);
|
||||
}
|
||||
|
||||
// ---- Logs (tail of a log file) ----
|
||||
|
||||
function renderLogPage(name) {
|
||||
const content = $('content');
|
||||
const label = state.logs.find((l) => l.name === name)?.label ?? name;
|
||||
const cached = state.logCache.get(name);
|
||||
if (!cached) { content.replaceChildren(el('h2', { class: 'page-title' }, label), el('div', { class: 'empty' }, 'Loading…')); return; }
|
||||
const view = el('div', { class: 'log-view' });
|
||||
for (const line of cached.text.split('\n')) {
|
||||
const lvl = /\bERROR\b/i.test(line) ? 'err' : /\bWARN(ING)?\b/i.test(line) ? 'warn' : '';
|
||||
view.append(el('div', { class: `log-line ${lvl}` }, line || ' '));
|
||||
}
|
||||
content.replaceChildren(el('h2', { class: 'page-title' }, label), el('div', { class: 'log-box' }, view));
|
||||
// follow the tail — scroll to the newest line
|
||||
requestAnimationFrame(() => { const b = content.querySelector('.log-box'); if (b) b.scrollTop = b.scrollHeight; });
|
||||
}
|
||||
|
||||
// ---- Files (doc viewer) ----
|
||||
|
||||
function renderDocs() {
|
||||
const coll = activeCollection();
|
||||
const content = $('content');
|
||||
if (!coll) { content.replaceChildren(el('div', { class: 'empty' }, 'No documents.')); return; }
|
||||
if (!coll.files.length) { content.replaceChildren(el('div', { class: 'empty' }, `No ${coll.label.toLowerCase()}.`)); return; }
|
||||
// display name: drop the group prefix, the `/SKILL.md` tail (show the skill
|
||||
// dir), and the .md extension — leaving e.g. "meeting-tagger" or "2026-06-13-…"
|
||||
const itemName = (label) => {
|
||||
let n = label.includes('/') ? label.split('/').slice(1).join('/').trim() : label;
|
||||
return n.replace(/\/SKILL\.md$/, '').replace(/\.md$/, '') || label;
|
||||
};
|
||||
const newestFirst = coll.name === 'conversations';
|
||||
const groups = new Map();
|
||||
for (const f of coll.files) { if (!groups.has(f.group)) groups.set(f.group, []); groups.get(f.group).push(f); }
|
||||
const toggleGroup = (g) => {
|
||||
state.openDocGroups.has(g) ? state.openDocGroups.delete(g) : state.openDocGroups.add(g);
|
||||
state.renderedSig = null; render();
|
||||
};
|
||||
const list = el('div', { class: 'doc-list' });
|
||||
for (const [group, files] of groups) {
|
||||
const open = state.openDocGroups.has(group);
|
||||
list.append(el('button', { class: 'doc-group-toggle' + (open ? ' open' : ''), onclick: () => toggleGroup(group) }, [
|
||||
el('span', { class: 'chev' }, open ? '▾' : '▸'),
|
||||
el('span', { class: 'g-name' }, group || '—'),
|
||||
el('span', { class: 'g-count' }, String(files.length)),
|
||||
]));
|
||||
if (open) {
|
||||
const ordered = newestFirst ? [...files].reverse() : files;
|
||||
for (const f of ordered) {
|
||||
list.append(el('button', { class: 'doc-item' + (f.path === state.activeDocPath ? ' active' : ''), title: f.path, onclick: () => openDoc(coll.name, f.path) }, itemName(f.label) || f.path));
|
||||
}
|
||||
}
|
||||
}
|
||||
const pane = el('div', { class: 'doc-content' });
|
||||
const cached = state.activeDocPath ? state.docCache.get(`${coll.name}\0${state.activeDocPath}`) : null;
|
||||
if (!state.activeDocPath) pane.append(el('div', { class: 'empty' }, 'Select a document.'));
|
||||
else if (!cached) pane.append(el('div', { class: 'empty' }, 'Loading…'));
|
||||
else if (cached.lang === 'error') pane.append(el('div', { class: 'tab-error' }, cached.content));
|
||||
else if (cached.lang === 'json') {
|
||||
let pretty = cached.content;
|
||||
try { pretty = JSON.stringify(JSON.parse(cached.content), null, 2); } catch { /* keep raw */ }
|
||||
pane.append(el('pre', { class: 'code json' }, pretty));
|
||||
} else if (cached.lang === 'markdown') {
|
||||
const md = el('div', { class: 'markdown' }); md.innerHTML = mdToHtml(cached.content); pane.append(md);
|
||||
} else pane.append(el('pre', { class: 'code' }, cached.content));
|
||||
content.replaceChildren(el('h2', { class: 'page-title' }, coll.label), el('div', { class: 'doc-viewer' }, [list, pane]));
|
||||
}
|
||||
|
||||
// ---- resource table ----
|
||||
|
||||
function renderTable(cliName, resource) {
|
||||
const content = $('content');
|
||||
const cli = state.clis.find((c) => c.name === cliName);
|
||||
if (!cli) { content.replaceChildren(el('div', { class: 'empty' }, 'No such CLI.')); return; }
|
||||
const key = `${cliName}/${resource}`;
|
||||
const snapshot = state.snapshots.get(key);
|
||||
const error = state.errors.get(key);
|
||||
const canDrill = (cli.commands || []).includes('get');
|
||||
const parts = [el('h2', { class: 'page-title' }, resource)];
|
||||
if (cli.help) parts.push(helpPanel(state.helpCache.get(key)));
|
||||
if (error && snapshot) parts.push(el('div', { class: 'stale-note' }, `⚠ live fetch failing — snapshot from ${new Date(snapshot.fetchedAt).toLocaleTimeString()}`));
|
||||
if (!snapshot) {
|
||||
parts.push(error ? el('div', { class: 'tab-error' }, [`Failed to load ${resource}.`, el('pre', {}, error)]) : el('div', { class: 'empty' }, 'Loading…'));
|
||||
content.replaceChildren(...parts); return;
|
||||
}
|
||||
const rows = snapshot.rows;
|
||||
parts.push(summaryBar(resource, rows, cli.summary?.[resource], cli));
|
||||
if (rows.length === 0) { parts.push(el('div', { class: 'empty' }, `No ${resource}.`)); content.replaceChildren(...parts); return; }
|
||||
const columns = [];
|
||||
for (const row of rows) for (const k of Object.keys(row)) if (!columns.includes(k)) columns.push(k);
|
||||
const ctx = { cliName, enrich: cli.enrich?.[resource], badges: cli.badges };
|
||||
const body = rows.map((row) => {
|
||||
const id = row.id; const canRow = canDrill && id != null;
|
||||
return el('tr', { class: canRow ? 'drillable' : '', ...(canRow ? { onclick: () => openDetail(cliName, resource, String(id)) } : {}) },
|
||||
columns.map((c) => buildCell(row[c], c, ctx)));
|
||||
});
|
||||
parts.push(el('div', { class: 'table-wrap' }, el('table', {}, [
|
||||
el('thead', {}, el('tr', {}, columns.map((c) => el('th', {}, c)))),
|
||||
el('tbody', {}, body),
|
||||
])));
|
||||
content.replaceChildren(...parts);
|
||||
}
|
||||
|
||||
// ---- drill-down detail overlay ----
|
||||
|
||||
function renderDetail() {
|
||||
const overlay = $('detail');
|
||||
if (!state.detail) { overlay.hidden = true; overlay.replaceChildren(); return; }
|
||||
overlay.hidden = false;
|
||||
const d = state.detail;
|
||||
const panel = el('div', { class: 'detail-panel' });
|
||||
panel.append(el('div', { class: 'detail-head' }, [
|
||||
el('div', {}, [el('span', { class: 'detail-res' }, d.resource), ' ', el('span', { class: 'detail-id' }, d.id)]),
|
||||
el('button', { class: 'detail-close', onclick: closeDetail, title: 'Close' }, '✕'),
|
||||
]));
|
||||
const sub = el('div', { class: 'detail-body' });
|
||||
if (d.loading) sub.append(el('div', { class: 'empty' }, 'Loading…'));
|
||||
else if (d.error) sub.append(el('div', { class: 'tab-error' }, d.error));
|
||||
else if (d.record) sub.append(el('div', { class: 'kv' }, kvRows(d.record)));
|
||||
if (d.config) {
|
||||
sub.append(el('div', { class: 'detail-section' }, 'Container config'));
|
||||
sub.append(el('div', { class: 'kv' }, kvRows(d.config)));
|
||||
}
|
||||
panel.append(sub);
|
||||
overlay.replaceChildren(panel);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- boot
|
||||
|
||||
$('pause').addEventListener('click', () => {
|
||||
state.paused = !state.paused;
|
||||
$('pause').textContent = state.paused ? '▶ resume' : '⏸ pause';
|
||||
$('pause').classList.toggle('paused', state.paused);
|
||||
state.renderedSig = null; render();
|
||||
});
|
||||
$('refresh').addEventListener('click', () => { if (!state.refreshing) refresh(true); });
|
||||
$('hamburger').addEventListener('click', () => { state.sidebarOpen = !state.sidebarOpen; state.renderedSig = null; render(); });
|
||||
$('scrim').addEventListener('click', () => { state.sidebarOpen = false; state.renderedSig = null; render(); });
|
||||
$('detail').addEventListener('click', (e) => { if (e.target === $('detail')) closeDetail(); });
|
||||
document.addEventListener('keydown', (e) => { if (e.key === 'Escape') { if (state.detail) closeDetail(); else if (state.sidebarOpen) { state.sidebarOpen = false; state.renderedSig = null; render(); } } });
|
||||
|
||||
async function tick() {
|
||||
if (!state.paused) { try { await refresh(); } catch { /* keep snapshots; retry next tick */ } }
|
||||
else renderControls();
|
||||
setTimeout(tick, state.refreshSeconds * 1000);
|
||||
}
|
||||
tick();
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 5.3 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 547 B |
@@ -1,11 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
|
||||
<defs>
|
||||
<linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
|
||||
<stop offset="0" stop-color="#141a24"/>
|
||||
<stop offset="1" stop-color="#0b0e14"/>
|
||||
</linearGradient>
|
||||
</defs>
|
||||
<rect width="32" height="32" rx="7.5" fill="url(#bg)"/>
|
||||
<rect x="0.5" y="0.5" width="31" height="31" rx="7" fill="none" stroke="#2b3342" stroke-width="1"/>
|
||||
<text x="16.2" y="20.8" font-family="monospace" font-size="15" font-weight="700" letter-spacing="-0.5" text-anchor="middle" fill="#5b9dff">ncl</text>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 570 B |
Binary file not shown.
|
Before Width: | Height: | Size: 6.5 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 18 KiB |
@@ -1,45 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>clidash</title>
|
||||
<link rel="icon" type="image/svg+xml" href="/favicon.svg">
|
||||
<link rel="icon" type="image/x-icon" href="/favicon.ico">
|
||||
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
|
||||
<link rel="manifest" href="/site.webmanifest">
|
||||
<meta name="theme-color" content="#0a0c11">
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
|
||||
<link rel="stylesheet" href="style.css">
|
||||
</head>
|
||||
<body>
|
||||
<button id="hamburger" class="hamburger" title="Menu" aria-label="Toggle menu">
|
||||
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="4" x2="20" y1="6" y2="6"/><line x1="4" x2="20" y1="12" y2="12"/><line x1="4" x2="20" y1="18" y2="18"/></svg>
|
||||
</button>
|
||||
<div id="scrim" class="scrim" hidden></div>
|
||||
|
||||
<div class="app">
|
||||
<aside id="sidebar" class="sidebar">
|
||||
<div class="brand"><h1>clidash</h1></div>
|
||||
<div class="controls">
|
||||
<button id="refresh" class="refresh" title="Refresh now">↻ refresh</button>
|
||||
<button id="pause" class="pause" title="Pause auto-refresh">⏸ pause</button>
|
||||
</div>
|
||||
<div id="updated" class="updated"></div>
|
||||
<nav id="nav" class="nav"></nav>
|
||||
</aside>
|
||||
|
||||
<main class="main">
|
||||
<div id="banner" class="banner" hidden></div>
|
||||
<div id="cmdline" class="cmdline" hidden></div>
|
||||
<section id="content" class="content"></section>
|
||||
</main>
|
||||
</div>
|
||||
|
||||
<div id="detail" class="detail-overlay" hidden></div>
|
||||
|
||||
<script type="module" src="app.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,68 +0,0 @@
|
||||
// Minimal, dependency-free, XSS-safe markdown → HTML for clidash's file viewer
|
||||
// (SKILL.md / CLAUDE.md). Pure string functions, no DOM — importable in both the
|
||||
// browser (app.js) and node tests.
|
||||
//
|
||||
// Safety model: the ENTIRE source is HTML-escaped first, so no raw markup from a
|
||||
// file can reach innerHTML. Markdown transforms then emit only tags this module
|
||||
// generates. Link hrefs are taken from the URL capture group and gated to an
|
||||
// http(s) scheme, so a `javascript:`/`data:` URL (or one smuggled via link text)
|
||||
// can never become an executable href.
|
||||
|
||||
export function escapeHtml(s) {
|
||||
return String(s).replace(/[&<>"']/g, (c) => (
|
||||
{ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[c]
|
||||
));
|
||||
}
|
||||
|
||||
export function mdToHtml(src) {
|
||||
const lines = escapeHtml(src).split('\n');
|
||||
const out = [];
|
||||
let i = 0;
|
||||
const inline = (t) => t
|
||||
.replace(/`([^`]+)`/g, '<code>$1</code>')
|
||||
.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
|
||||
.replace(/\*([^*]+)\*/g, '<em>$1</em>')
|
||||
.replace(/\[([^\]]+)\]\((https?:[^)\s]+)\)/g, (m, text, url) =>
|
||||
/^https?:\/\//i.test(url) ? `<a href="${url}" target="_blank" rel="noopener noreferrer">${text}</a>` : m);
|
||||
while (i < lines.length) {
|
||||
const line = lines[i];
|
||||
if (/^```/.test(line)) {
|
||||
const buf = [];
|
||||
i++;
|
||||
while (i < lines.length && !/^```/.test(lines[i])) buf.push(lines[i++]);
|
||||
i++;
|
||||
out.push(`<pre class="code"><code>${buf.join('\n')}</code></pre>`);
|
||||
continue;
|
||||
}
|
||||
const h = line.match(/^(#{1,6})\s+(.*)$/);
|
||||
if (h) { out.push(`<h${h[1].length}>${inline(h[2])}</h${h[1].length}>`); i++; continue; }
|
||||
if (/^\s*([-*])\s+/.test(line)) {
|
||||
const items = [];
|
||||
while (i < lines.length && /^\s*([-*])\s+/.test(lines[i])) {
|
||||
items.push(`<li>${inline(lines[i].replace(/^\s*([-*])\s+/, ''))}</li>`);
|
||||
i++;
|
||||
}
|
||||
out.push(`<ul>${items.join('')}</ul>`);
|
||||
continue;
|
||||
}
|
||||
if (/^\s*\d+\.\s+/.test(line)) {
|
||||
const items = [];
|
||||
while (i < lines.length && /^\s*\d+\.\s+/.test(lines[i])) {
|
||||
items.push(`<li>${inline(lines[i].replace(/^\s*\d+\.\s+/, ''))}</li>`);
|
||||
i++;
|
||||
}
|
||||
out.push(`<ol>${items.join('')}</ol>`);
|
||||
continue;
|
||||
}
|
||||
if (/^\s*(---+|\*\*\*+)\s*$/.test(line)) { out.push('<hr>'); i++; continue; }
|
||||
if (/^\s*>\s?/.test(line)) { out.push(`<blockquote>${inline(line.replace(/^\s*>\s?/, ''))}</blockquote>`); i++; continue; }
|
||||
if (line.trim() === '') { i++; continue; }
|
||||
const para = [line];
|
||||
i++;
|
||||
while (i < lines.length && lines[i].trim() !== '' && !/^(#{1,6}\s|```|\s*[-*]\s|\s*\d+\.\s|\s*>)/.test(lines[i])) {
|
||||
para.push(lines[i++]);
|
||||
}
|
||||
out.push(`<p>${inline(para.join(' '))}</p>`);
|
||||
}
|
||||
return out.join('\n');
|
||||
}
|
||||
@@ -1,11 +0,0 @@
|
||||
{
|
||||
"name": "clidash",
|
||||
"short_name": "ncl",
|
||||
"icons": [
|
||||
{ "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
|
||||
{ "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
|
||||
],
|
||||
"theme_color": "#0a0c11",
|
||||
"background_color": "#0a0c11",
|
||||
"display": "standalone"
|
||||
}
|
||||
@@ -1,328 +0,0 @@
|
||||
/* clidash — refined terminal-ops console.
|
||||
IBM Plex superfamily (Sans for UI, Mono for the CLI identity), a deep layered
|
||||
dark palette, real depth, and precise micro-interactions. */
|
||||
|
||||
:root {
|
||||
/* layered surfaces */
|
||||
--bg: #0a0c11;
|
||||
--bg-grad: #10141d;
|
||||
--panel: #13171f;
|
||||
--panel-2: #1a1f2a;
|
||||
--border: #222834;
|
||||
--border-strong: #2e3644;
|
||||
/* text */
|
||||
--text: #e8edf5;
|
||||
--dim: #98a2b3;
|
||||
--faint: #5c6675;
|
||||
/* accent + semantics */
|
||||
--accent: #5b9dff;
|
||||
--accent-soft: rgba(91, 157, 255, 0.14);
|
||||
--green: #4cc97a;
|
||||
--amber: #e0a93a;
|
||||
--red: #f76d6d;
|
||||
--purple: #c08cff;
|
||||
--gray: #6b7585;
|
||||
/* shape + motion */
|
||||
--radius: 11px;
|
||||
--radius-sm: 8px;
|
||||
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.35);
|
||||
--shadow: 0 6px 22px -8px rgba(0, 0, 0, 0.5);
|
||||
--shadow-lg: 0 18px 44px -12px rgba(0, 0, 0, 0.6);
|
||||
--ease: 160ms cubic-bezier(0.2, 0.6, 0.2, 1);
|
||||
--font-sans: "IBM Plex Sans", -apple-system, system-ui, Segoe UI, sans-serif;
|
||||
--font-mono: "IBM Plex Mono", ui-monospace, "SF Mono", Menlo, monospace;
|
||||
}
|
||||
|
||||
* { box-sizing: border-box; margin: 0; padding: 0; }
|
||||
[hidden] { display: none !important; }
|
||||
|
||||
html { scrollbar-color: var(--border-strong) transparent; }
|
||||
body {
|
||||
background:
|
||||
radial-gradient(120% 80% at 50% -10%, var(--bg-grad) 0%, transparent 55%),
|
||||
var(--bg);
|
||||
background-attachment: fixed;
|
||||
color: var(--text);
|
||||
font-family: var(--font-sans);
|
||||
font-size: 14px;
|
||||
line-height: 1.5;
|
||||
-webkit-text-size-adjust: 100%;
|
||||
-webkit-font-smoothing: antialiased;
|
||||
}
|
||||
|
||||
::selection { background: var(--accent-soft); }
|
||||
:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 4px; }
|
||||
|
||||
h1 {
|
||||
font-family: var(--font-mono); font-size: 17px; font-weight: 600;
|
||||
letter-spacing: -0.3px; color: var(--text);
|
||||
}
|
||||
h1::before { content: "▍"; color: var(--accent); margin-right: 4px; }
|
||||
|
||||
/* ---- layout ---- */
|
||||
|
||||
.app { display: flex; align-items: stretch; min-height: 100vh; min-height: 100dvh; }
|
||||
|
||||
.sidebar {
|
||||
width: 236px; flex-shrink: 0; height: 100vh; height: 100dvh;
|
||||
position: sticky; top: 0; align-self: flex-start; overflow-y: auto;
|
||||
background: linear-gradient(180deg, rgba(255, 255, 255, 0.015), transparent 200px), var(--bg);
|
||||
border-right: 1px solid var(--border);
|
||||
padding: 18px 12px 40px; display: flex; flex-direction: column; gap: 10px;
|
||||
}
|
||||
.sidebar .brand { padding: 2px 8px 6px; }
|
||||
.sidebar .controls { display: flex; gap: 8px; padding: 0 4px; }
|
||||
.sidebar .updated { color: var(--faint); font-size: 11.5px; padding: 0 8px; min-height: 16px; font-family: var(--font-mono); }
|
||||
|
||||
.pause, .refresh {
|
||||
flex: 1; background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius-sm);
|
||||
color: var(--dim); padding: 6px 10px; font-size: 12.5px; font-family: var(--font-mono);
|
||||
cursor: pointer; transition: color var(--ease), border-color var(--ease), background var(--ease);
|
||||
}
|
||||
.pause:hover, .refresh:hover { color: var(--text); border-color: var(--border-strong); background: var(--panel-2); }
|
||||
.pause.paused { color: var(--amber); border-color: var(--amber); }
|
||||
.refresh.spinning { color: var(--accent); border-color: var(--accent); animation: pulse 0.85s ease-in-out infinite; }
|
||||
@keyframes pulse { 50% { opacity: 0.5; } }
|
||||
|
||||
.nav { display: flex; flex-direction: column; gap: 1px; margin-top: 6px; }
|
||||
.nav-section {
|
||||
color: var(--faint); font-size: 10.5px; text-transform: uppercase; letter-spacing: 1px;
|
||||
font-weight: 600; margin: 16px 10px 5px; font-family: var(--font-mono);
|
||||
display: flex; align-items: center; gap: 7px;
|
||||
}
|
||||
.nav-section svg { width: 13px; height: 13px; opacity: 0.7; }
|
||||
.nav-item {
|
||||
display: flex; align-items: center; gap: 9px; text-align: left;
|
||||
background: none; border: none; border-radius: var(--radius-sm);
|
||||
color: var(--dim); padding: 7px 10px; font-size: 13.5px; cursor: pointer; width: 100%;
|
||||
font-family: var(--font-sans); position: relative;
|
||||
transition: color var(--ease), background var(--ease);
|
||||
}
|
||||
.nav-item svg { width: 16px; height: 16px; flex-shrink: 0; opacity: 0.85; }
|
||||
.nav-item:hover { background: var(--panel); color: var(--text); }
|
||||
.nav-item.active { background: var(--accent-soft); color: var(--text); }
|
||||
.nav-item.active::before {
|
||||
content: ""; position: absolute; left: -12px; top: 50%; transform: translateY(-50%);
|
||||
width: 3px; height: 18px; background: var(--accent); border-radius: 0 3px 3px 0;
|
||||
}
|
||||
.nav-item.nav-sub { padding-left: 16px; font-size: 13px; }
|
||||
.nav-item.nav-sub.active { color: var(--accent); }
|
||||
|
||||
.hamburger {
|
||||
display: none; position: fixed; top: 12px; left: 12px; z-index: 60;
|
||||
background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius-sm);
|
||||
color: var(--text); width: 40px; height: 40px; cursor: pointer; align-items: center; justify-content: center;
|
||||
}
|
||||
.hamburger svg { width: 20px; height: 20px; }
|
||||
.scrim { display: none; }
|
||||
|
||||
.main { flex: 1; min-width: 0; padding: 26px 28px 64px; max-width: 1500px; }
|
||||
.page-title {
|
||||
font-size: 20px; font-weight: 600; letter-spacing: -0.4px; margin-bottom: 16px;
|
||||
animation: fadeUp 0.3s var(--ease) both;
|
||||
}
|
||||
|
||||
.banner {
|
||||
background: rgba(247, 109, 109, 0.1); border: 1px solid rgba(247, 109, 109, 0.4);
|
||||
border-radius: var(--radius-sm); color: var(--red); padding: 9px 14px; font-size: 13.5px; margin-bottom: 16px;
|
||||
}
|
||||
.cmdline {
|
||||
font-family: var(--font-mono); font-size: 12px; color: var(--dim);
|
||||
background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius-sm);
|
||||
padding: 9px 14px; margin-bottom: 18px; overflow-x: auto; white-space: nowrap; box-shadow: var(--shadow-sm);
|
||||
}
|
||||
.cmdline::first-letter { color: var(--green); }
|
||||
|
||||
@keyframes fadeUp { from { opacity: 0; transform: translateY(7px); } }
|
||||
|
||||
/* ---- overview cards ---- */
|
||||
|
||||
.ov-cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(310px, 1fr)); gap: 16px; }
|
||||
.ov-card {
|
||||
background: linear-gradient(180deg, rgba(255, 255, 255, 0.018), transparent 40%), var(--panel);
|
||||
border: 1px solid var(--border); border-radius: var(--radius); padding: 17px 19px;
|
||||
box-shadow: var(--shadow); transition: border-color var(--ease), transform var(--ease);
|
||||
animation: fadeUp 0.4s var(--ease) both;
|
||||
}
|
||||
.ov-card:nth-child(2) { animation-delay: 0.05s; }
|
||||
.ov-card:nth-child(3) { animation-delay: 0.1s; }
|
||||
.ov-card:nth-child(4) { animation-delay: 0.15s; }
|
||||
.ov-card:hover { border-color: var(--border-strong); transform: translateY(-2px); }
|
||||
.ov-head { display: flex; align-items: center; gap: 9px; margin-bottom: 14px; }
|
||||
.ov-head .ov-name { font-weight: 600; font-size: 15px; }
|
||||
.ov-head .ov-folder { color: var(--faint); font-size: 12px; font-family: var(--font-mono); }
|
||||
.ov-fields { display: flex; flex-direction: column; gap: 7px; }
|
||||
.ov-field { display: flex; justify-content: space-between; align-items: center; font-size: 13px; }
|
||||
.ov-field .k { color: var(--dim); }
|
||||
.ov-field .v { color: var(--text); font-variant-numeric: tabular-nums; } .ov-field .v.dim { color: var(--faint); }
|
||||
.ov-chans { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 14px; }
|
||||
|
||||
.dot, .ov-head .dot { width: 9px; height: 9px; border-radius: 50%; flex-shrink: 0; }
|
||||
.dot.green { background: var(--green); box-shadow: 0 0 8px -1px var(--green); }
|
||||
.dot.amber { background: var(--amber); box-shadow: 0 0 8px -1px var(--amber); }
|
||||
.dot.red { background: var(--red); box-shadow: 0 0 8px -1px var(--red); }
|
||||
.dot.gray { background: var(--gray); }
|
||||
|
||||
.badge {
|
||||
font-size: 11.5px; border: 1px solid var(--border-strong); border-radius: 99px;
|
||||
padding: 2px 10px; color: var(--dim); background: var(--panel-2); font-family: var(--font-mono);
|
||||
}
|
||||
|
||||
/* ---- status badges + enriched cells ---- */
|
||||
.badge-status { display: inline-flex; align-items: center; gap: 6px; font-size: 12.5px; }
|
||||
.badge-status .dot { width: 7px; height: 7px; }
|
||||
.badge-status.green { color: var(--green); } .badge-status.amber { color: var(--amber); }
|
||||
.badge-status.red { color: var(--red); } .badge-status.gray { color: var(--gray); }
|
||||
td.enriched span:first-child { color: var(--text); }
|
||||
td.enriched .raw-id { display: block; color: var(--faint); font-size: 11px; font-family: var(--font-mono); }
|
||||
|
||||
/* ---- summary bar ---- */
|
||||
.summary-bar { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; margin: 2px 0 16px; font-size: 13px; }
|
||||
.summary-bar .sum-count { color: var(--text); font-weight: 600; }
|
||||
.summary-bar .sum-sep { color: var(--border-strong); }
|
||||
.summary-bar .sum-chip { color: var(--dim); font-family: var(--font-mono); font-size: 12px; }
|
||||
|
||||
/* ---- per-resource help panel ---- */
|
||||
.help-panel { margin-bottom: 18px; background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius); padding: 13px 16px; box-shadow: var(--shadow-sm); }
|
||||
.help-head { color: var(--dim); font-size: 13px; line-height: 1.6; }
|
||||
.help-head.dim { color: var(--faint); }
|
||||
.help-more { margin-top: 9px; }
|
||||
.help-more > summary { cursor: pointer; color: var(--accent); font-size: 12px; list-style: none; user-select: none; font-family: var(--font-mono); }
|
||||
.help-more > summary::-webkit-details-marker { display: none; }
|
||||
.help-more > summary::before { content: "▸ "; }
|
||||
.help-more[open] > summary::before { content: "▾ "; }
|
||||
.help-text {
|
||||
margin: 9px 0 0; background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius-sm);
|
||||
padding: 13px 15px; font-size: 12px; line-height: 1.6; color: var(--dim);
|
||||
white-space: pre-wrap; overflow-x: auto; font-family: var(--font-mono);
|
||||
}
|
||||
|
||||
/* ---- document viewer ---- */
|
||||
.doc-viewer { display: grid; grid-template-columns: 264px 1fr; gap: 20px; align-items: start; }
|
||||
.doc-list { display: flex; flex-direction: column; gap: 2px; max-height: 76vh; overflow-y: auto; padding-right: 4px; }
|
||||
.doc-group-toggle {
|
||||
flex-shrink: 0; display: flex; align-items: center; gap: 7px; width: 100%;
|
||||
background: none; border: none; cursor: pointer; text-align: left;
|
||||
color: var(--dim); font-size: 11px; text-transform: uppercase; letter-spacing: 1px;
|
||||
font-weight: 600; font-family: var(--font-mono); margin: 12px 0 4px; padding: 5px 8px;
|
||||
border-radius: var(--radius-sm); transition: color var(--ease), background var(--ease);
|
||||
}
|
||||
.doc-group-toggle:first-child { margin-top: 0; }
|
||||
.doc-group-toggle:hover { color: var(--text); background: var(--panel); }
|
||||
.doc-group-toggle.open { color: var(--text); }
|
||||
.doc-group-toggle .chev { color: var(--accent); width: 10px; }
|
||||
.doc-group-toggle .g-name { flex: 1; }
|
||||
.doc-group-toggle .g-count {
|
||||
color: var(--faint); background: var(--panel-2); border-radius: 99px;
|
||||
padding: 1px 8px; font-size: 10.5px; letter-spacing: 0;
|
||||
}
|
||||
.doc-item {
|
||||
flex-shrink: 0; text-align: left; background: none; border: none; border-radius: var(--radius-sm);
|
||||
color: var(--dim); padding: 6px 11px; font-size: 13px; line-height: 1.5; cursor: pointer;
|
||||
white-space: nowrap; overflow: hidden; text-overflow: ellipsis; transition: color var(--ease), background var(--ease);
|
||||
}
|
||||
.doc-item:hover { background: var(--panel); color: var(--text); }
|
||||
.doc-item.active { background: var(--accent-soft); color: var(--accent); }
|
||||
.doc-content {
|
||||
background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius);
|
||||
padding: 22px 26px; min-height: 220px; max-height: 78vh; overflow-y: auto; box-shadow: var(--shadow);
|
||||
}
|
||||
|
||||
.markdown { font-size: 14px; line-height: 1.7; color: var(--text); }
|
||||
.markdown h1, .markdown h2, .markdown h3, .markdown h4 { margin: 20px 0 8px; line-height: 1.3; font-family: var(--font-mono); }
|
||||
.markdown h1 { font-size: 21px; } .markdown h2 { font-size: 17px; color: var(--accent); } .markdown h3 { font-size: 15px; }
|
||||
.markdown h1:first-child, .markdown h2:first-child { margin-top: 0; }
|
||||
.markdown p { color: var(--text); margin: 8px 0; }
|
||||
.markdown ul, .markdown ol { margin: 8px 0 8px 22px; }
|
||||
.markdown li { margin: 3px 0; }
|
||||
.markdown a { color: var(--accent); }
|
||||
.markdown hr { border: none; border-top: 1px solid var(--border); margin: 18px 0; }
|
||||
.markdown blockquote { border-left: 3px solid var(--border-strong); padding-left: 12px; color: var(--dim); margin: 8px 0; }
|
||||
.markdown code { background: var(--bg); border: 1px solid var(--border); border-radius: 5px; padding: 1px 6px; font-size: 12.5px; font-family: var(--font-mono); }
|
||||
.markdown pre.code, .doc-content pre.code {
|
||||
background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius-sm);
|
||||
padding: 14px; overflow-x: auto; font-size: 12.5px; line-height: 1.6; margin: 12px 0; font-family: var(--font-mono);
|
||||
}
|
||||
.markdown pre.code code { background: none; border: none; padding: 0; }
|
||||
.doc-content pre.json { color: var(--text); white-space: pre; font-family: var(--font-mono); }
|
||||
|
||||
/* ---- activity ---- */
|
||||
.activity-wrap { max-width: 780px; }
|
||||
.activity-legend { display: flex; gap: 18px; align-items: center; margin-bottom: 12px; font-size: 13px; color: var(--dim); }
|
||||
.activity-legend .lg { display: inline-block; width: 11px; height: 11px; border-radius: 3px; margin-right: 6px; vertical-align: -1px; }
|
||||
.activity-legend .lg.in { background: var(--accent); } .activity-legend .lg.out { background: var(--purple); }
|
||||
.chart-box { background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius); padding: 16px; margin-bottom: 20px; box-shadow: var(--shadow); }
|
||||
.activity-chart { width: 100%; height: 220px; display: block; }
|
||||
.activity-chart .bar-in { fill: var(--accent); } .activity-chart .bar-out { fill: var(--purple); }
|
||||
.activity-chart .grid { stroke: var(--border); stroke-width: 1; }
|
||||
.activity-chart .axis { fill: var(--faint); font-size: 9px; font-family: var(--font-mono); }
|
||||
.activity-table td.num, .activity-table th:nth-child(3), .activity-table th:nth-child(4) { text-align: right; }
|
||||
.activity-table td.num { font-variant-numeric: tabular-nums; }
|
||||
|
||||
/* ---- log viewer ---- */
|
||||
.log-box {
|
||||
background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius);
|
||||
max-height: 78vh; overflow: auto; padding: 12px 0; box-shadow: var(--shadow);
|
||||
}
|
||||
.log-view { font-family: var(--font-mono); font-size: 12px; line-height: 1.65; min-width: max-content; }
|
||||
.log-line { padding: 0 16px; white-space: pre; color: var(--dim); }
|
||||
.log-line:hover { background: var(--panel); }
|
||||
.log-line.err { color: var(--red); background: rgba(247, 109, 109, 0.06); }
|
||||
.log-line.warn { color: var(--amber); }
|
||||
|
||||
/* ---- tables ---- */
|
||||
.table-wrap { overflow-x: auto; -webkit-overflow-scrolling: touch; border: 1px solid var(--border); border-radius: var(--radius); box-shadow: var(--shadow-sm); }
|
||||
table { border-collapse: collapse; width: 100%; font-size: 13px; }
|
||||
th, td { text-align: left; padding: 9px 14px; border-bottom: 1px solid var(--border); white-space: nowrap; }
|
||||
tbody tr:last-child td { border-bottom: none; }
|
||||
th { color: var(--dim); font-weight: 600; font-size: 10.5px; text-transform: uppercase; letter-spacing: 0.6px; position: sticky; top: 0; background: var(--panel-2); font-family: var(--font-mono); }
|
||||
td { font-variant-numeric: tabular-nums; }
|
||||
td.null { color: var(--faint); font-style: italic; }
|
||||
tr.drillable { cursor: pointer; transition: background var(--ease); }
|
||||
tr.drillable:hover td { background: var(--panel); }
|
||||
.reltime .abs { color: var(--faint); font-size: 11.5px; margin-left: 6px; font-family: var(--font-mono); }
|
||||
td .trunc { cursor: pointer; border-bottom: 1px dotted var(--faint); }
|
||||
.stale-note { color: var(--amber); font-size: 12.5px; margin-bottom: 8px; }
|
||||
.empty, .tab-error { color: var(--dim); padding: 26px 2px; font-size: 14px; }
|
||||
.tab-error { color: var(--red); }
|
||||
.tab-error pre { margin-top: 10px; background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: 12px; color: var(--dim); font-size: 12px; overflow-x: auto; white-space: pre-wrap; font-family: var(--font-mono); }
|
||||
|
||||
/* ---- drill-down detail overlay ---- */
|
||||
.detail-overlay { position: fixed; inset: 0; background: rgba(2, 4, 8, 0.62); display: flex; justify-content: flex-end; z-index: 50; backdrop-filter: blur(2px); animation: fade 0.18s ease; }
|
||||
@keyframes fade { from { opacity: 0; } }
|
||||
.detail-panel { width: min(580px, 100%); height: 100%; background: var(--bg); border-left: 1px solid var(--border-strong); overflow-y: auto; box-shadow: var(--shadow-lg); animation: slideIn 0.22s var(--ease); }
|
||||
@keyframes slideIn { from { transform: translateX(24px); opacity: 0.6; } }
|
||||
.detail-head { display: flex; justify-content: space-between; align-items: center; padding: 17px 22px; border-bottom: 1px solid var(--border); position: sticky; top: 0; background: var(--bg); }
|
||||
.detail-res { font-weight: 600; font-size: 15px; }
|
||||
.detail-id { color: var(--dim); font-family: var(--font-mono); font-size: 13px; }
|
||||
.detail-close { background: none; border: 1px solid var(--border); border-radius: var(--radius-sm); color: var(--dim); width: 30px; height: 30px; cursor: pointer; font-size: 14px; transition: color var(--ease), border-color var(--ease); }
|
||||
.detail-close:hover { color: var(--text); border-color: var(--accent); }
|
||||
.detail-body { padding: 17px 22px 44px; }
|
||||
.detail-section { margin: 24px 0 8px; color: var(--faint); font-size: 10.5px; text-transform: uppercase; letter-spacing: 1px; font-weight: 600; border-top: 1px solid var(--border); padding-top: 17px; font-family: var(--font-mono); }
|
||||
.kv { display: flex; flex-direction: column; gap: 2px; }
|
||||
.kv-row { display: grid; grid-template-columns: 168px 1fr; gap: 12px; padding: 6px 0; border-bottom: 1px solid var(--border); font-size: 13px; }
|
||||
.kv-key { color: var(--dim); font-family: var(--font-mono); font-size: 12.5px; }
|
||||
.kv-json { background: var(--panel); border: 1px solid var(--border); border-radius: 6px; padding: 8px 10px; font-size: 12px; overflow-x: auto; margin: 0; font-family: var(--font-mono); }
|
||||
|
||||
/* ---- mobile ---- */
|
||||
@media (max-width: 640px) {
|
||||
.hamburger { display: flex; }
|
||||
.sidebar {
|
||||
position: fixed; top: 0; left: 0; z-index: 70; transform: translateX(-100%);
|
||||
transition: transform 0.22s var(--ease); box-shadow: var(--shadow-lg);
|
||||
}
|
||||
.sidebar.open { transform: translateX(0); }
|
||||
.scrim { display: block; position: fixed; inset: 0; background: rgba(2, 4, 8, 0.55); z-index: 65; backdrop-filter: blur(1px); }
|
||||
.scrim[hidden] { display: none; }
|
||||
.main { padding: 58px 16px 48px; }
|
||||
.ov-cards { grid-template-columns: 1fr; }
|
||||
.doc-viewer { grid-template-columns: 1fr; gap: 12px; }
|
||||
.doc-list { max-height: 220px; flex-direction: row; flex-wrap: wrap; }
|
||||
.doc-content { max-height: none; padding: 18px; }
|
||||
.detail-panel { width: 100%; }
|
||||
.kv-row { grid-template-columns: 1fr; gap: 2px; }
|
||||
}
|
||||
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
*, *::before, *::after { animation: none !important; transition: none !important; }
|
||||
}
|
||||
@@ -1,437 +0,0 @@
|
||||
// clidash — CLI-agnostic read-only web dashboard.
|
||||
// Node built-ins only. All per-CLI knowledge lives in clidash.config.json;
|
||||
// the only per-CLI code is optional view plugins (views/) and discovery
|
||||
// parsers (parsers.js).
|
||||
//
|
||||
// Security model: the server can only exec the configured argv templates.
|
||||
// `{resource}` is the sole substitution and is validated against the
|
||||
// discovered/static resource set before exec. execFile, never a shell.
|
||||
|
||||
import { createServer } from 'node:http';
|
||||
import { execFile } from 'node:child_process';
|
||||
import { readFile, readdir } from 'node:fs/promises';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { dirname, join, resolve, sep, basename } from 'node:path';
|
||||
import { fileURLToPath, pathToFileURL } from 'node:url';
|
||||
import { discoveryParsers, parseOutput, unwrapPath } from './parsers.js';
|
||||
import { globFiles, describeFile, resolveDoc } from './docs.js';
|
||||
import { collectActivity } from './activity.js';
|
||||
import { tailFile } from './logs.js';
|
||||
|
||||
const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
|
||||
const MAX_DOC_BYTES = 2 * 1024 * 1024; // cap a single served document at 2 MB
|
||||
|
||||
const DEFAULTS = {
|
||||
bind: '127.0.0.1',
|
||||
port: 4690,
|
||||
refreshSeconds: 60,
|
||||
execTimeoutMs: 10_000,
|
||||
discoveryTtlMs: 60_000,
|
||||
};
|
||||
|
||||
const CONTENT_TYPES = {
|
||||
'.html': 'text/html; charset=utf-8',
|
||||
'.js': 'text/javascript; charset=utf-8',
|
||||
'.css': 'text/css; charset=utf-8',
|
||||
'.json': 'application/json; charset=utf-8',
|
||||
'.svg': 'image/svg+xml',
|
||||
'.png': 'image/png',
|
||||
'.ico': 'image/x-icon',
|
||||
'.webmanifest': 'application/manifest+json',
|
||||
};
|
||||
|
||||
export function createApp(userConfig) {
|
||||
const config = { ...DEFAULTS, ...userConfig };
|
||||
const publicDir = resolve(config.publicDir ?? join(MODULE_DIR, 'public'));
|
||||
const viewsDir = resolve(config.viewsDir ?? join(MODULE_DIR, 'views'));
|
||||
|
||||
// Human-readable form of a command, for display in the UI ("the command run").
|
||||
const displayCmd = (bin, args) => `${basename(bin)} ${args.join(' ')}`;
|
||||
|
||||
// ---- exec --------------------------------------------------------------
|
||||
|
||||
function execCli(cliCfg, args, label) {
|
||||
return new Promise((resolvePromise, rejectPromise) => {
|
||||
execFile(cliCfg.bin, args, {
|
||||
cwd: cliCfg.cwd,
|
||||
timeout: config.execTimeoutMs,
|
||||
maxBuffer: 32 * 1024 * 1024,
|
||||
env: { ...process.env, ...cliCfg.env },
|
||||
}, (error, stdout, stderr) => {
|
||||
if (error) {
|
||||
const timedOut = error.killed || error.signal === 'SIGTERM';
|
||||
const detail = stderr.trim() || error.message;
|
||||
const msg = timedOut
|
||||
? `${label} timed out after ${config.execTimeoutMs}ms`
|
||||
: `${label} failed: ${detail}`;
|
||||
rejectPromise(new Error(msg));
|
||||
return;
|
||||
}
|
||||
resolvePromise(stdout);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
// ---- resource discovery (cached, coalesced, keeps last good) -----------
|
||||
|
||||
const discoveryCache = new Map(); // cli -> { at, resources }
|
||||
const discoveryInflight = new Map(); // cli -> Promise
|
||||
|
||||
async function discoverResources(cliName) {
|
||||
const cliCfg = config.clis[cliName];
|
||||
if (cliCfg.resources) {
|
||||
return cliCfg.resources.map((name) =>
|
||||
typeof name === 'string' ? { name, description: '' } : name,
|
||||
);
|
||||
}
|
||||
const cached = discoveryCache.get(cliName);
|
||||
if (cached && Date.now() - cached.at < config.discoveryTtlMs) return cached.resources;
|
||||
if (discoveryInflight.has(cliName)) return discoveryInflight.get(cliName);
|
||||
|
||||
const parser = discoveryParsers[cliCfg.discover.parser];
|
||||
if (!parser) throw new Error(`Unknown discovery parser: ${cliCfg.discover.parser}`);
|
||||
const promise = execCli(cliCfg, cliCfg.discover.args, `${cliName} discovery`)
|
||||
.then((stdout) => {
|
||||
const resources = parser(stdout);
|
||||
discoveryCache.set(cliName, { at: Date.now(), resources });
|
||||
return resources;
|
||||
})
|
||||
.finally(() => discoveryInflight.delete(cliName));
|
||||
discoveryInflight.set(cliName, promise);
|
||||
return promise;
|
||||
}
|
||||
|
||||
// ---- row fetching (coalesced per cli+resource) --------------------------
|
||||
|
||||
const listInflight = new Map(); // "cli\0resource" -> Promise
|
||||
|
||||
async function fetchRows(cliName, resourceName) {
|
||||
const cliCfg = config.clis[cliName];
|
||||
const resources = await discoverResources(cliName);
|
||||
if (!resources.some((r) => r.name === resourceName)) {
|
||||
const err = new Error(`Unknown resource "${resourceName}" for CLI "${cliName}"`);
|
||||
err.statusCode = 404;
|
||||
throw err;
|
||||
}
|
||||
const key = `${cliName}\0${resourceName}`;
|
||||
if (listInflight.has(key)) return listInflight.get(key);
|
||||
|
||||
// {resource} may appear as a whole arg or inside one (e.g. an ssh remote
|
||||
// command). Safe either way — the value is allowlist-validated above.
|
||||
const args = cliCfg.list.map((a) => a.replaceAll('{resource}', resourceName));
|
||||
const promise = execCli(cliCfg, args, `${cliName} ${resourceName} list`)
|
||||
.then((stdout) => {
|
||||
const parsed = parseOutput(stdout, cliCfg.output ?? 'json');
|
||||
const rows = unwrapPath(parsed, cliCfg.unwrap);
|
||||
if (!Array.isArray(rows)) {
|
||||
const err = new Error(`${cliName} ${resourceName}: expected an array of rows`);
|
||||
err.raw = stdout;
|
||||
throw err;
|
||||
}
|
||||
return rows;
|
||||
})
|
||||
.finally(() => listInflight.delete(key));
|
||||
listInflight.set(key, promise);
|
||||
return promise;
|
||||
}
|
||||
|
||||
// ---- detail commands (drill-down: get, config-get, …) -------------------
|
||||
|
||||
const cmdInflight = new Map();
|
||||
const ID_RE = /^[A-Za-z0-9:_.-]+$/; // ncl ids / uuids; no shell metas (and execFile never shells)
|
||||
|
||||
async function runCommand(cliName, cmdName, resourceName, id) {
|
||||
const cliCfg = config.clis[cliName];
|
||||
const template = cliCfg.commands?.[cmdName];
|
||||
if (!template) {
|
||||
const err = new Error(`Unknown command "${cmdName}"`);
|
||||
err.statusCode = 404;
|
||||
throw err;
|
||||
}
|
||||
const needsResource = template.includes('{resource}');
|
||||
if (needsResource) {
|
||||
const resources = await discoverResources(cliName);
|
||||
if (!resources.some((r) => r.name === resourceName)) {
|
||||
const err = new Error(`Unknown resource "${resourceName}"`);
|
||||
err.statusCode = 404;
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
if (template.includes('{id}') && !ID_RE.test(id ?? '')) {
|
||||
const err = new Error('Invalid id');
|
||||
err.statusCode = 400;
|
||||
throw err;
|
||||
}
|
||||
const key = `${cliName}\0${cmdName}\0${resourceName}\0${id}`;
|
||||
if (cmdInflight.has(key)) return cmdInflight.get(key);
|
||||
const args = template.map((a) => a.replaceAll('{resource}', resourceName ?? '').replaceAll('{id}', id ?? ''));
|
||||
const promise = execCli(cliCfg, args, `${cliName} ${cmdName}`)
|
||||
.then((stdout) => unwrapPath(parseOutput(stdout, cliCfg.output ?? 'json'), cliCfg.unwrap))
|
||||
.finally(() => cmdInflight.delete(key));
|
||||
cmdInflight.set(key, promise);
|
||||
return promise;
|
||||
}
|
||||
|
||||
// ---- per-resource help (raw text from `<cli> <resource> help`) -----------
|
||||
|
||||
const helpInflight = new Map();
|
||||
async function runHelp(cliName, resourceName) {
|
||||
const cliCfg = config.clis[cliName];
|
||||
if (!cliCfg.help) { const e = new Error(`No help for "${cliName}"`); e.statusCode = 404; throw e; }
|
||||
const resources = await discoverResources(cliName);
|
||||
if (!resources.some((r) => r.name === resourceName)) {
|
||||
const e = new Error(`Unknown resource "${resourceName}"`); e.statusCode = 404; throw e;
|
||||
}
|
||||
const key = `${cliName}\0${resourceName}`;
|
||||
if (helpInflight.has(key)) return helpInflight.get(key);
|
||||
const args = cliCfg.help.map((a) => a.replaceAll('{resource}', resourceName));
|
||||
const promise = execCli(cliCfg, args, `${cliName} ${resourceName} help`).finally(() => helpInflight.delete(key));
|
||||
helpInflight.set(key, promise);
|
||||
return promise;
|
||||
}
|
||||
|
||||
// ---- view plugins --------------------------------------------------------
|
||||
|
||||
async function listViews(cliName) {
|
||||
try {
|
||||
const files = await readdir(viewsDir);
|
||||
return files
|
||||
.filter((f) => f.startsWith(`${cliName}-`) && f.endsWith('.js'))
|
||||
.map((f) => f.slice(cliName.length + 1, -3));
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
async function runView(cliName, viewName) {
|
||||
if (!/^[a-zA-Z0-9_-]+$/.test(viewName)) {
|
||||
const err = new Error(`Invalid view name`);
|
||||
err.statusCode = 404;
|
||||
throw err;
|
||||
}
|
||||
const file = join(viewsDir, `${cliName}-${viewName}.js`);
|
||||
let mod;
|
||||
try {
|
||||
mod = await import(pathToFileURL(file).href);
|
||||
} catch (e) {
|
||||
if (e.code === 'ERR_MODULE_NOT_FOUND') {
|
||||
const err = new Error(`No view "${viewName}" for CLI "${cliName}"`);
|
||||
err.statusCode = 404;
|
||||
throw err;
|
||||
}
|
||||
throw e;
|
||||
}
|
||||
return mod.default({ fetch: (resource) => fetchRows(cliName, resource) });
|
||||
}
|
||||
|
||||
// ---- http ----------------------------------------------------------------
|
||||
|
||||
function sendJson(res, status, body) {
|
||||
const payload = JSON.stringify(body);
|
||||
res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
|
||||
res.end(payload);
|
||||
}
|
||||
|
||||
function sendError(res, err) {
|
||||
const status = err.statusCode ?? 502;
|
||||
const body = { ok: false, error: err.message };
|
||||
if (err.raw !== undefined) body.raw = String(err.raw).slice(0, 64 * 1024);
|
||||
sendJson(res, status, body);
|
||||
}
|
||||
|
||||
async function serveStatic(res, urlPath) {
|
||||
const relative = urlPath === '/' ? 'index.html' : decodeURIComponent(urlPath.slice(1));
|
||||
const file = resolve(publicDir, relative);
|
||||
if (file !== publicDir && !file.startsWith(publicDir + sep)) {
|
||||
sendJson(res, 403, { ok: false, error: 'Forbidden' });
|
||||
return;
|
||||
}
|
||||
try {
|
||||
const content = await readFile(file);
|
||||
const ext = file.slice(file.lastIndexOf('.'));
|
||||
// always revalidate so a redeploy is picked up immediately (no stale JS/CSS)
|
||||
res.writeHead(200, { 'Content-Type': CONTENT_TYPES[ext] ?? 'application/octet-stream', 'Cache-Control': 'no-cache' });
|
||||
res.end(content);
|
||||
} catch {
|
||||
sendJson(res, 404, { ok: false, error: 'Not found' });
|
||||
}
|
||||
}
|
||||
|
||||
return createServer(async (req, res) => {
|
||||
try {
|
||||
if (req.method !== 'GET') {
|
||||
sendJson(res, 405, { ok: false, error: 'Read-only dashboard: GET only' });
|
||||
return;
|
||||
}
|
||||
const urlPath = req.url.split('?')[0];
|
||||
const segments = urlPath.split('/').map((s) => decodeURIComponent(s));
|
||||
|
||||
if (urlPath === '/api/clis') {
|
||||
const clis = await Promise.all(Object.keys(config.clis).map(async (name) => {
|
||||
const entry = {
|
||||
name,
|
||||
refreshSeconds: config.refreshSeconds,
|
||||
views: await listViews(name),
|
||||
commands: Object.keys(config.clis[name].commands ?? {}),
|
||||
enrich: config.clis[name].enrich ?? null,
|
||||
badges: config.clis[name].badges ?? null,
|
||||
summary: config.clis[name].summary ?? null,
|
||||
help: !!config.clis[name].help,
|
||||
};
|
||||
try {
|
||||
entry.resources = await discoverResources(name);
|
||||
} catch (e) {
|
||||
// keep last good discovery (≤TTL old) if we have one; always surface the error
|
||||
entry.resources = discoveryCache.get(name)?.resources ?? [];
|
||||
entry.error = e.message;
|
||||
}
|
||||
return entry;
|
||||
}));
|
||||
sendJson(res, 200, { clis });
|
||||
return;
|
||||
}
|
||||
|
||||
if (segments[1] === 'api' && segments[2] === 'r' && segments.length === 5) {
|
||||
const [, , , cliName, resourceName] = segments;
|
||||
if (!config.clis[cliName]) {
|
||||
sendJson(res, 404, { ok: false, error: `Unknown CLI "${cliName}"` });
|
||||
return;
|
||||
}
|
||||
const rows = await fetchRows(cliName, resourceName);
|
||||
const cliCfg = config.clis[cliName];
|
||||
const command = displayCmd(cliCfg.bin, cliCfg.list.map((a) => a.replaceAll('{resource}', resourceName)));
|
||||
sendJson(res, 200, { ok: true, rows, command, fetchedAt: new Date().toISOString() });
|
||||
return;
|
||||
}
|
||||
|
||||
if (segments[1] === 'api' && segments[2] === 'cmd' && segments.length === 5) {
|
||||
const [, , , cliName, cmdName] = segments;
|
||||
if (!config.clis[cliName]) {
|
||||
sendJson(res, 404, { ok: false, error: `Unknown CLI "${cliName}"` });
|
||||
return;
|
||||
}
|
||||
const q = new URL(req.url, 'http://localhost').searchParams;
|
||||
const data = await runCommand(cliName, cmdName, q.get('resource'), q.get('id'));
|
||||
const tmpl = config.clis[cliName].commands?.[cmdName] ?? [];
|
||||
const command = displayCmd(config.clis[cliName].bin,
|
||||
tmpl.map((a) => a.replaceAll('{resource}', q.get('resource') ?? '').replaceAll('{id}', q.get('id') ?? '')));
|
||||
sendJson(res, 200, { ok: true, data, command, fetchedAt: new Date().toISOString() });
|
||||
return;
|
||||
}
|
||||
|
||||
if (segments[1] === 'api' && segments[2] === 'help' && segments.length === 5) {
|
||||
const [, , , cliName, resourceName] = segments;
|
||||
if (!config.clis[cliName]) {
|
||||
sendJson(res, 404, { ok: false, error: `Unknown CLI "${cliName}"` });
|
||||
return;
|
||||
}
|
||||
const text = await runHelp(cliName, resourceName);
|
||||
sendJson(res, 200, { ok: true, text });
|
||||
return;
|
||||
}
|
||||
|
||||
if (segments[1] === 'api' && segments[2] === 'view' && segments.length === 5) {
|
||||
const [, , , cliName, viewName] = segments;
|
||||
if (!config.clis[cliName]) {
|
||||
sendJson(res, 404, { ok: false, error: `Unknown CLI "${cliName}"` });
|
||||
return;
|
||||
}
|
||||
const result = await runView(cliName, viewName);
|
||||
sendJson(res, 200, { ok: true, result, fetchedAt: new Date().toISOString() });
|
||||
return;
|
||||
}
|
||||
|
||||
// Log tails (allowlisted files under logs.dir).
|
||||
if (urlPath === '/api/logs') {
|
||||
sendJson(res, 200, { files: (config.logs?.files ?? []).map((f) => ({ name: f.name, label: f.label ?? f.name })) });
|
||||
return;
|
||||
}
|
||||
if (segments[1] === 'api' && segments[2] === 'log' && segments.length === 4) {
|
||||
const name = segments[3];
|
||||
const file = config.logs?.files?.find((f) => f.name === name);
|
||||
if (!file) { sendJson(res, 404, { ok: false, error: `Unknown log "${name}"` }); return; }
|
||||
const lines = config.logs.tailLines ?? 400;
|
||||
const { text } = await tailFile(join(config.logs.dir, name), lines);
|
||||
sendJson(res, 200, { ok: true, text, command: `tail -n ${lines} ${join(config.logs.dir, name)}`, fetchedAt: new Date().toISOString() });
|
||||
return;
|
||||
}
|
||||
|
||||
// Message activity (read per-session DBs; ncl has no messages resource).
|
||||
if (urlPath === '/api/activity') {
|
||||
if (!config.activity) { sendJson(res, 200, { ok: true, configured: false }); return; }
|
||||
const days = config.activity.days ?? 14;
|
||||
const { sessions, series } = collectActivity(config.activity.sessionsRoot, days, new Date());
|
||||
const command = `node:sqlite · ${config.activity.sessionsRoot}/*/*/{inbound,outbound}.db (last ${days}d)`;
|
||||
sendJson(res, 200, { ok: true, configured: true, sessions, series, command, fetchedAt: new Date().toISOString() });
|
||||
return;
|
||||
}
|
||||
|
||||
// Read-only file viewer (skills, CLAUDE.md, profiles, conversations).
|
||||
if (urlPath === '/api/docs') {
|
||||
const docs = config.docs;
|
||||
const collections = (docs?.collections ?? []).map((coll) => ({
|
||||
name: coll.name,
|
||||
label: coll.label ?? coll.name,
|
||||
lang: coll.lang ?? 'text',
|
||||
files: globFiles(docs.root, coll.patterns, docs.deny ?? []).map((path) => ({
|
||||
path,
|
||||
...describeFile(path),
|
||||
})),
|
||||
}));
|
||||
sendJson(res, 200, { collections });
|
||||
return;
|
||||
}
|
||||
|
||||
if (urlPath === '/api/doc') {
|
||||
const docs = config.docs;
|
||||
const query = new URL(req.url, 'http://localhost').searchParams;
|
||||
const collName = query.get('c');
|
||||
const relPath = query.get('p') ?? '';
|
||||
const collection = docs?.collections?.find((c) => c.name === collName);
|
||||
if (!collection) {
|
||||
sendJson(res, 404, { ok: false, error: `Unknown collection "${collName}"` });
|
||||
return;
|
||||
}
|
||||
let abs;
|
||||
try {
|
||||
abs = resolveDoc(docs.root, collection, relPath, docs.deny ?? []);
|
||||
} catch {
|
||||
sendJson(res, 404, { ok: false, error: 'Not found' });
|
||||
return;
|
||||
}
|
||||
const content = await readFile(abs, 'utf8');
|
||||
sendJson(res, 200, {
|
||||
ok: true,
|
||||
path: relPath,
|
||||
lang: collection.lang ?? 'text',
|
||||
content: content.length > MAX_DOC_BYTES ? content.slice(0, MAX_DOC_BYTES) : content,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
if (urlPath.startsWith('/api/')) {
|
||||
sendJson(res, 404, { ok: false, error: 'Not found' });
|
||||
return;
|
||||
}
|
||||
|
||||
await serveStatic(res, urlPath);
|
||||
} catch (err) {
|
||||
sendError(res, err);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// ---- standalone entry point ------------------------------------------------
|
||||
|
||||
const isMain = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
|
||||
if (isMain) {
|
||||
const configPath = process.env.CLIDASH_CONFIG ?? join(MODULE_DIR, 'clidash.config.json');
|
||||
const config = JSON.parse(readFileSync(configPath, 'utf8'));
|
||||
if (process.env.PORT) config.port = Number(process.env.PORT);
|
||||
if (process.env.BIND) config.bind = process.env.BIND;
|
||||
const finalConfig = { ...DEFAULTS, ...config };
|
||||
const server = createApp(finalConfig);
|
||||
server.listen(finalConfig.port, finalConfig.bind, () => {
|
||||
console.log(`clidash listening on http://${finalConfig.bind}:${finalConfig.port}`);
|
||||
});
|
||||
}
|
||||
@@ -1,46 +0,0 @@
|
||||
import { test, before, after } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { DatabaseSync } from 'node:sqlite';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
let root;
|
||||
before(() => {
|
||||
root = mkdtempSync(join(tmpdir(), 'clidash-actsrv-'));
|
||||
mkdirSync(join(root, 'ag-1', 'sess-1'), { recursive: true });
|
||||
const mk = (p, t, ts) => { const db = new DatabaseSync(p); db.exec(`CREATE TABLE ${t}(id TEXT, timestamp TEXT)`); const i = db.prepare(`INSERT INTO ${t} VALUES (?,?)`); ts.forEach((x, n) => i.run(String(n), x)); db.close(); };
|
||||
const today = new Date().toISOString().slice(0, 10);
|
||||
mk(join(root, 'ag-1', 'sess-1', 'inbound.db'), 'messages_in', [`${today} 09:00:00`, `${today} 10:00:00`]);
|
||||
mk(join(root, 'ag-1', 'sess-1', 'outbound.db'), 'messages_out', [`${today} 09:05:00`]);
|
||||
});
|
||||
after(() => rmSync(root, { recursive: true, force: true }));
|
||||
|
||||
async function withServer(config, fn) {
|
||||
const server = createApp({ port: 0, bind: '127.0.0.1', clis: {}, ...config });
|
||||
await new Promise((r) => server.listen(0, '127.0.0.1', r));
|
||||
const base = `http://127.0.0.1:${server.address().port}`;
|
||||
try { return await fn(base); } finally { await new Promise((r) => server.close(r)); }
|
||||
}
|
||||
|
||||
test('/api/activity: returns per-session totals + a daily series', async () => {
|
||||
await withServer({ activity: { sessionsRoot: root, days: 14 } }, async (base) => {
|
||||
const body = await (await fetch(`${base}/api/activity`)).json();
|
||||
assert.equal(body.ok, true);
|
||||
assert.equal(body.configured, true);
|
||||
assert.equal(body.series.length, 14);
|
||||
assert.equal(body.sessions[0].in, 2);
|
||||
assert.equal(body.sessions[0].out, 1);
|
||||
assert.equal(body.series.at(-1).in, 2); // today
|
||||
assert.equal(body.series.at(-1).out, 1);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/activity: not configured → configured:false, no crash', async () => {
|
||||
await withServer({}, async (base) => {
|
||||
const body = await (await fetch(`${base}/api/activity`)).json();
|
||||
assert.equal(body.ok, true);
|
||||
assert.equal(body.configured, false);
|
||||
});
|
||||
});
|
||||
@@ -1,75 +0,0 @@
|
||||
import { test, before, after } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { DatabaseSync } from 'node:sqlite';
|
||||
import { collectActivity } from '../activity.js';
|
||||
|
||||
let root;
|
||||
const NOW = new Date('2026-06-14T12:00:00Z');
|
||||
|
||||
function makeDb(path, table, timestamps) {
|
||||
const db = new DatabaseSync(path);
|
||||
db.exec(`CREATE TABLE ${table} (id TEXT, timestamp TEXT)`);
|
||||
const ins = db.prepare(`INSERT INTO ${table} (id, timestamp) VALUES (?, ?)`);
|
||||
timestamps.forEach((t, i) => ins.run(String(i), t));
|
||||
db.close();
|
||||
}
|
||||
|
||||
before(() => {
|
||||
root = mkdtempSync(join(tmpdir(), 'clidash-act-'));
|
||||
// session 1 (group ag-1): 3 inbound across 2 days, 2 outbound today
|
||||
mkdirSync(join(root, 'ag-1', 'sess-1'), { recursive: true });
|
||||
makeDb(join(root, 'ag-1', 'sess-1', 'inbound.db'), 'messages_in',
|
||||
['2026-06-14 09:01:23', '2026-06-14 10:00:00', '2026-06-13 08:00:00']);
|
||||
makeDb(join(root, 'ag-1', 'sess-1', 'outbound.db'), 'messages_out',
|
||||
['2026-06-14 09:05:00', '2026-06-14 10:05:00']);
|
||||
// session 2 (group ag-2): 1 inbound 20 days ago (outside 14d window), 0 outbound
|
||||
mkdirSync(join(root, 'ag-2', 'sess-2'), { recursive: true });
|
||||
makeDb(join(root, 'ag-2', 'sess-2', 'inbound.db'), 'messages_in', ['2026-05-25 08:00:00']);
|
||||
makeDb(join(root, 'ag-2', 'sess-2', 'outbound.db'), 'messages_out', []);
|
||||
});
|
||||
|
||||
after(() => rmSync(root, { recursive: true, force: true }));
|
||||
|
||||
test('collectActivity: per-session in/out totals + last activity', () => {
|
||||
const { sessions } = collectActivity(root, 14, NOW);
|
||||
const s1 = sessions.find((s) => s.session_id === 'sess-1');
|
||||
assert.equal(s1.agent_group_id, 'ag-1');
|
||||
assert.equal(s1.in, 3);
|
||||
assert.equal(s1.out, 2);
|
||||
assert.equal(s1.lastActivity, '2026-06-14T10:05:00Z'); // normalized to ISO
|
||||
const s2 = sessions.find((s) => s.session_id === 'sess-2');
|
||||
assert.equal(s2.in, 1);
|
||||
assert.equal(s2.out, 0);
|
||||
});
|
||||
|
||||
test('collectActivity: series has one bucket per day for `days`, newest last', () => {
|
||||
const { series } = collectActivity(root, 14, NOW);
|
||||
assert.equal(series.length, 14);
|
||||
assert.equal(series[0].date, '2026-06-01');
|
||||
assert.equal(series[13].date, '2026-06-14');
|
||||
});
|
||||
|
||||
test('collectActivity: counts land in the right day buckets', () => {
|
||||
const { series } = collectActivity(root, 14, NOW);
|
||||
const byDate = Object.fromEntries(series.map((d) => [d.date, d]));
|
||||
assert.equal(byDate['2026-06-14'].in, 2);
|
||||
assert.equal(byDate['2026-06-14'].out, 2);
|
||||
assert.equal(byDate['2026-06-13'].in, 1);
|
||||
assert.equal(byDate['2026-06-13'].out, 0);
|
||||
});
|
||||
|
||||
test('collectActivity: messages outside the window are counted in totals but not the series', () => {
|
||||
const { series, sessions } = collectActivity(root, 14, NOW);
|
||||
const total = series.reduce((a, d) => a + d.in + d.out, 0);
|
||||
assert.equal(total, 5); // the 20-day-old message is excluded from series
|
||||
assert.equal(sessions.find((s) => s.session_id === 'sess-2').in, 1); // but still in the total count
|
||||
});
|
||||
|
||||
test('collectActivity: a dir with no message DBs is not a session (skipped)', () => {
|
||||
mkdirSync(join(root, 'ag-1', '.claude-shared'), { recursive: true }); // scaffolding, no db files
|
||||
const { sessions } = collectActivity(root, 14, NOW);
|
||||
assert.ok(!sessions.some((s) => s.session_id === '.claude-shared'));
|
||||
});
|
||||
@@ -1,91 +0,0 @@
|
||||
import { test, after } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
const STUB = fileURLToPath(new URL('./fixtures/stub-cli.js', import.meta.url));
|
||||
const tmp = mkdtempSync(join(tmpdir(), 'clidash-cmd-'));
|
||||
after(() => rmSync(tmp, { recursive: true, force: true }));
|
||||
|
||||
function cli(extra = {}) {
|
||||
return {
|
||||
bin: process.execPath,
|
||||
discover: { args: [STUB, 'help'], parser: 'ncl-help' },
|
||||
list: [STUB, '{resource}', 'list', '--json'],
|
||||
output: 'json',
|
||||
unwrap: 'data',
|
||||
commands: {
|
||||
get: [STUB, '{resource}', 'get', '{id}', '--json'],
|
||||
'config-get': [STUB, 'groups', 'config', 'get', '--id', '{id}', '--json'],
|
||||
},
|
||||
...extra,
|
||||
};
|
||||
}
|
||||
|
||||
async function withServer(clis, fn, extra = {}) {
|
||||
const server = createApp({ port: 0, bind: '127.0.0.1', execTimeoutMs: 2000, clis, ...extra });
|
||||
await new Promise((r) => server.listen(0, '127.0.0.1', r));
|
||||
const base = `http://127.0.0.1:${server.address().port}`;
|
||||
try { return await fn(base); } finally { await new Promise((r) => server.close(r)); }
|
||||
}
|
||||
|
||||
test('/api/cmd: runs an allowlisted command with {resource} + {id}', async () => {
|
||||
await withServer({ ncl: cli() }, async (base) => {
|
||||
const body = await (await fetch(`${base}/api/cmd/ncl/get?resource=sessions&id=sess-123`)).json();
|
||||
assert.equal(body.ok, true);
|
||||
assert.equal(body.data.id, 'sessions-detail');
|
||||
assert.match(body.data.args, /sessions get sess-123/);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/cmd: config-get needs no resource', async () => {
|
||||
await withServer({ ncl: cli() }, async (base) => {
|
||||
const body = await (await fetch(`${base}/api/cmd/ncl/config-get?id=ag-1`)).json();
|
||||
assert.equal(body.ok, true);
|
||||
assert.match(body.data.args, /groups config get --id ag-1/);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/cmd: unknown command name → 404 (allowlist)', async () => {
|
||||
await withServer({ ncl: cli() }, async (base) => {
|
||||
const res = await fetch(`${base}/api/cmd/ncl/delete?resource=groups&id=ag-1`);
|
||||
assert.equal(res.status, 404);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/cmd: a {resource} not in the discovered set is rejected without exec', async () => {
|
||||
const countFile = join(tmp, 'cmd-count.txt');
|
||||
const c = cli();
|
||||
c.env = { STUB_COUNT_FILE: countFile };
|
||||
await withServer({ ncl: c }, async (base) => {
|
||||
const res = await fetch(`${base}/api/cmd/ncl/get?resource=evil&id=x`);
|
||||
assert.equal(res.status, 404);
|
||||
// only discovery ran, never a get for the bogus resource
|
||||
const calls = readFileSync(countFile, 'utf8').trim().split('\n');
|
||||
assert.deepEqual(calls, ['help']);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/cmd: an id with illegal characters is rejected', async () => {
|
||||
await withServer({ ncl: cli() }, async (base) => {
|
||||
const res = await fetch(`${base}/api/cmd/ncl/get?resource=sessions&id=${encodeURIComponent('a b;rm -rf')}`);
|
||||
assert.equal(res.status, 400);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/cmd: unknown cli → 404', async () => {
|
||||
await withServer({ ncl: cli() }, async (base) => {
|
||||
assert.equal((await fetch(`${base}/api/cmd/nope/get?resource=sessions&id=x`)).status, 404);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/cmd: a cli without a commands map → 404', async () => {
|
||||
const c = cli();
|
||||
delete c.commands;
|
||||
await withServer({ ncl: c }, async (base) => {
|
||||
assert.equal((await fetch(`${base}/api/cmd/ncl/get?resource=sessions&id=x`)).status, 404);
|
||||
});
|
||||
});
|
||||
@@ -1,20 +0,0 @@
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const css = readFileSync(fileURLToPath(new URL('../public/style.css', import.meta.url)), 'utf8');
|
||||
|
||||
// Regression: the `hidden` attribute must override author `display` rules.
|
||||
// `.detail-overlay` and `.cli-switcher` set `display:flex`, which beats the
|
||||
// browser's default `[hidden]{display:none}` — without this reset a hidden
|
||||
// overlay stays on top of the page and silently eats every click.
|
||||
test('style.css forces [hidden] to display:none with !important', () => {
|
||||
assert.match(css, /\[hidden\]\s*\{\s*display:\s*none\s*!important;?\s*\}/);
|
||||
});
|
||||
|
||||
// Guard the premise: if these stop using display:flex the reset is less load-
|
||||
// bearing, but this documents WHY the reset exists.
|
||||
test('the overlays that motivated the reset still use display:flex', () => {
|
||||
assert.match(css, /\.detail-overlay\s*\{[^}]*display:\s*flex/);
|
||||
});
|
||||
@@ -1,111 +0,0 @@
|
||||
import { test, before, after } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
let root;
|
||||
|
||||
before(() => {
|
||||
root = mkdtempSync(join(tmpdir(), 'clidash-docsrv-'));
|
||||
const w = (rel, body) => {
|
||||
const abs = join(root, rel);
|
||||
mkdirSync(join(abs, '..'), { recursive: true });
|
||||
writeFileSync(abs, body);
|
||||
};
|
||||
w('groups/alpha/skills/tagger/SKILL.md', '# tagger\nhello');
|
||||
w('container/skills/welcome/SKILL.md', '# welcome');
|
||||
w('groups/alpha/profile.json', '{"name":"Alpha"}');
|
||||
w('groups/alpha/.env', 'SECRET=nope');
|
||||
});
|
||||
|
||||
after(() => rmSync(root, { recursive: true, force: true }));
|
||||
|
||||
function docsConfig() {
|
||||
return {
|
||||
port: 0,
|
||||
bind: '127.0.0.1',
|
||||
clis: {},
|
||||
docs: {
|
||||
root,
|
||||
deny: ['node_modules', '.env', '*token*', '*secret*', '*.pem', '*.key'],
|
||||
collections: [
|
||||
{ name: 'skills', label: 'Skills', lang: 'markdown', patterns: ['groups/*/skills/*/SKILL.md', 'container/skills/*/SKILL.md'] },
|
||||
{ name: 'profiles', label: 'Profiles', lang: 'json', patterns: ['groups/*/profile.json'] },
|
||||
],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async function withServer(config, fn) {
|
||||
const server = createApp(config);
|
||||
await new Promise((r) => server.listen(0, '127.0.0.1', r));
|
||||
const base = `http://127.0.0.1:${server.address().port}`;
|
||||
try {
|
||||
return await fn(base);
|
||||
} finally {
|
||||
await new Promise((r) => server.close(r));
|
||||
}
|
||||
}
|
||||
|
||||
test('/api/docs: lists collections with their files', async () => {
|
||||
await withServer(docsConfig(), async (base) => {
|
||||
const body = await (await fetch(`${base}/api/docs`)).json();
|
||||
const skills = body.collections.find((c) => c.name === 'skills');
|
||||
assert.equal(skills.label, 'Skills');
|
||||
assert.equal(skills.lang, 'markdown');
|
||||
const paths = skills.files.map((f) => f.path);
|
||||
assert.ok(paths.includes('groups/alpha/skills/tagger/SKILL.md'));
|
||||
assert.ok(paths.includes('container/skills/welcome/SKILL.md'));
|
||||
// each file carries a readable label + group
|
||||
const f = skills.files.find((x) => x.path.includes('tagger'));
|
||||
assert.equal(f.group, 'alpha');
|
||||
assert.match(f.label, /tagger/);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/doc: returns file content + lang', async () => {
|
||||
await withServer(docsConfig(), async (base) => {
|
||||
const url = `${base}/api/doc?c=skills&p=${encodeURIComponent('groups/alpha/skills/tagger/SKILL.md')}`;
|
||||
const body = await (await fetch(url)).json();
|
||||
assert.equal(body.ok, true);
|
||||
assert.equal(body.lang, 'markdown');
|
||||
assert.match(body.content, /# tagger/);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/doc: a denied file is not readable even though it sits under root', async () => {
|
||||
await withServer(docsConfig(), async (base) => {
|
||||
// .env is excluded by the deny-list and not in any collection pattern
|
||||
const coll = docsConfig();
|
||||
coll.docs.collections.push({ name: 'all', label: 'All', lang: 'text', patterns: ['groups/*/*'] });
|
||||
await withServer(coll, async (base2) => {
|
||||
const res = await fetch(`${base2}/api/doc?c=all&p=${encodeURIComponent('groups/alpha/.env')}`);
|
||||
assert.equal(res.status, 404);
|
||||
assert.equal((await res.json()).ok, false);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/doc: path traversal is rejected', async () => {
|
||||
await withServer(docsConfig(), async (base) => {
|
||||
const res = await fetch(`${base}/api/doc?c=skills&p=${encodeURIComponent('../../../../etc/passwd')}`);
|
||||
assert.equal(res.status, 404);
|
||||
assert.equal((await res.json()).ok, false);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/doc: unknown collection → 404', async () => {
|
||||
await withServer(docsConfig(), async (base) => {
|
||||
const res = await fetch(`${base}/api/doc?c=nope&p=x`);
|
||||
assert.equal(res.status, 404);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/docs: absent docs config → empty collections, no crash', async () => {
|
||||
await withServer({ port: 0, bind: '127.0.0.1', clis: {} }, async (base) => {
|
||||
const body = await (await fetch(`${base}/api/docs`)).json();
|
||||
assert.deepEqual(body.collections, []);
|
||||
});
|
||||
});
|
||||
@@ -1,111 +0,0 @@
|
||||
import { test, before, after } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { globFiles, describeFile, resolveDoc } from '../docs.js';
|
||||
|
||||
let root;
|
||||
|
||||
before(() => {
|
||||
root = mkdtempSync(join(tmpdir(), 'clidash-docs-'));
|
||||
const w = (rel, body = 'x') => {
|
||||
const abs = join(root, rel);
|
||||
mkdirSync(join(abs, '..'), { recursive: true });
|
||||
writeFileSync(abs, body);
|
||||
};
|
||||
w('groups/alpha/skills/example-skill/SKILL.md', '# example-skill\nbody');
|
||||
w('groups/alpha/skills/tagger/SKILL.md');
|
||||
w('groups/alpha/CLAUDE.md', '# Alpha');
|
||||
w('groups/alpha/CLAUDE.local.md');
|
||||
w('groups/alpha/profile.json', '{"name":"Alpha"}');
|
||||
w('groups/alpha/conversations/2026-06-01.md');
|
||||
w('groups/bravo/skills/tagger/SKILL.md');
|
||||
w('groups/bravo/profile.json');
|
||||
w('container/skills/agent-browser/SKILL.md');
|
||||
w('container/skills/welcome/SKILL.md');
|
||||
// things that must NEVER be served
|
||||
w('groups/alpha/.env', 'SECRET=1');
|
||||
w('groups/alpha/skills/example-skill/node_modules/dep/SKILL.md');
|
||||
w('groups/alpha/notion-token.txt', 'ntn_xxx');
|
||||
});
|
||||
|
||||
after(() => rmSync(root, { recursive: true, force: true }));
|
||||
|
||||
const DENY = ['node_modules', '.env', '*token*', '*secret*', '*.pem', '*.key'];
|
||||
|
||||
// --------------------------------------------------------------- globFiles
|
||||
|
||||
test('globFiles: matches a nested *-segment pattern', () => {
|
||||
const files = globFiles(root, ['groups/*/skills/*/SKILL.md'], DENY);
|
||||
assert.deepEqual(files, [
|
||||
'groups/alpha/skills/example-skill/SKILL.md',
|
||||
'groups/alpha/skills/tagger/SKILL.md',
|
||||
'groups/bravo/skills/tagger/SKILL.md',
|
||||
]);
|
||||
});
|
||||
|
||||
test('globFiles: multiple patterns union, sorted', () => {
|
||||
const files = globFiles(root, ['groups/*/skills/*/SKILL.md', 'container/skills/*/SKILL.md'], DENY);
|
||||
assert.ok(files.includes('container/skills/agent-browser/SKILL.md'));
|
||||
assert.ok(files.includes('groups/alpha/skills/example-skill/SKILL.md'));
|
||||
});
|
||||
|
||||
test('globFiles: wildcard inside a filename segment', () => {
|
||||
const files = globFiles(root, ['groups/*/CLAUDE*.md'], DENY);
|
||||
assert.deepEqual(files, ['groups/alpha/CLAUDE.local.md', 'groups/alpha/CLAUDE.md']);
|
||||
});
|
||||
|
||||
test('globFiles: deny list excludes node_modules and secret-ish files', () => {
|
||||
const files = globFiles(root, ['groups/*/skills/*/**', 'groups/*/*'], DENY);
|
||||
assert.ok(!files.some((f) => f.includes('node_modules')));
|
||||
assert.ok(!files.some((f) => f.endsWith('.env')));
|
||||
assert.ok(!files.some((f) => f.includes('token')));
|
||||
});
|
||||
|
||||
test('globFiles: no match returns empty array', () => {
|
||||
assert.deepEqual(globFiles(root, ['nope/*/x.md'], DENY), []);
|
||||
});
|
||||
|
||||
// ------------------------------------------------------------- describeFile
|
||||
|
||||
test('describeFile: per-group skill → group + readable label', () => {
|
||||
const d = describeFile('groups/alpha/skills/tagger/SKILL.md');
|
||||
assert.equal(d.group, 'alpha');
|
||||
assert.match(d.label, /alpha/);
|
||||
assert.match(d.label, /tagger/);
|
||||
});
|
||||
|
||||
test('describeFile: container skill → shared', () => {
|
||||
const d = describeFile('container/skills/agent-browser/SKILL.md');
|
||||
assert.equal(d.group, 'shared');
|
||||
assert.match(d.label, /agent-browser/);
|
||||
});
|
||||
|
||||
// --------------------------------------------------------------- resolveDoc
|
||||
|
||||
const SKILLS = { name: 'skills', patterns: ['groups/*/skills/*/SKILL.md', 'container/skills/*/SKILL.md'] };
|
||||
|
||||
test('resolveDoc: returns an absolute path for an allowed file', () => {
|
||||
const abs = resolveDoc(root, SKILLS, 'groups/alpha/skills/example-skill/SKILL.md', DENY);
|
||||
assert.ok(abs.endsWith('/groups/alpha/skills/example-skill/SKILL.md'));
|
||||
assert.ok(abs.startsWith(root));
|
||||
});
|
||||
|
||||
test('resolveDoc: rejects a path not matching the collection patterns', () => {
|
||||
assert.throws(() => resolveDoc(root, SKILLS, 'groups/alpha/profile.json', DENY), /not allowed/i);
|
||||
});
|
||||
|
||||
test('resolveDoc: rejects path traversal', () => {
|
||||
assert.throws(() => resolveDoc(root, SKILLS, '../../etc/passwd', DENY), /not allowed/i);
|
||||
assert.throws(() => resolveDoc(root, SKILLS, 'groups/alpha/skills/../../../.env', DENY), /not allowed/i);
|
||||
});
|
||||
|
||||
test('resolveDoc: rejects an absolute path', () => {
|
||||
assert.throws(() => resolveDoc(root, SKILLS, '/etc/passwd', DENY), /not allowed/i);
|
||||
});
|
||||
|
||||
test('resolveDoc: a denied file is not resolvable even if pattern-shaped', () => {
|
||||
const coll = { name: 'all', patterns: ['groups/*/*'] };
|
||||
assert.throws(() => resolveDoc(root, coll, 'groups/alpha/.env', DENY), /not allowed/i);
|
||||
});
|
||||
@@ -1,28 +0,0 @@
|
||||
Resources:
|
||||
approvals Pending approval — in-flight approval cards waiting for an admin response. Created by requestApproval() (self-mod install_packages/add_mcp_server) and OneCLI credential approval flow. Rows are deleted after the admin approves/rejects or the request expires.
|
||||
verbs: list, get
|
||||
destinations Agent destination — per-agent routing entry and ACL. Each row authorizes an agent to send messages to a target (channel or another agent) and assigns a local name the agent uses to address it. Names are scoped to the source agent — two agents can have different local names for the same target. Created automatically when wiring channels or when agents create child agents.
|
||||
verbs: list, add, remove
|
||||
dropped-messages Dropped message log — tracks messages that were dropped by the router or access gate. Aggregates by (channel_type, platform_id) with a running count. Reasons include: no_agent_wired (no wiring exists), no_agent_engaged (wiring exists but engage rules didn't fire), unknown_sender_strict (sender not recognized, strict policy), unknown_sender_request_approval (sender not recognized, approval requested).
|
||||
verbs: list
|
||||
groups Agent group — a logical agent identity. Each group has its own workspace folder (CLAUDE.md, skills, container config), conversation history, and container image. Multiple messaging groups can be wired to one agent group.
|
||||
verbs: list, get, create, update, delete, restart, config get, config update, config add-mcp-server, config remove-mcp-server, config add-package, config remove-package
|
||||
members Agent group member — grants an unprivileged user permission to interact with an agent group. Users with admin or owner roles on the group are implicitly members and do not need a separate membership row. Membership is checked by the router when sender_scope is "known".
|
||||
verbs: list, add, remove
|
||||
messaging-groups Messaging group — one chat or channel on one platform (a Telegram DM, a Discord channel, a Slack thread root, an email address). Identity is the (channel_type, platform_id) pair, which must be unique.
|
||||
verbs: list, get, create, update, delete
|
||||
roles User role — privilege grant. "owner" is always global and has full control. "admin" can be global (agent_group_id null) or scoped to a specific agent group. Admin at a group implies membership. Approval routing prefers admins/owners reachable on the same messaging platform as the request origin (e.g. a Telegram request routes the approval card to an admin on Telegram when possible).
|
||||
verbs: list, grant, revoke
|
||||
sessions Session — the runtime unit. Maps one (agent_group, messaging_group, thread) combination to a container with its own inbound.db and outbound.db. Created automatically by the router when a message arrives.
|
||||
verbs: list, get
|
||||
user-dms User DM cache — maps (user, channel_type) to the messaging group used for DM delivery. Populated lazily by ensureUserDm() when the host needs to cold-DM a user (approvals, pairing). For direct-addressable channels (Telegram, WhatsApp) the handle IS the DM chat ID. For resolution-required channels (Discord, Slack) the adapter's openDM resolves it.
|
||||
verbs: list
|
||||
users User — a messaging-platform identity. Each row is one sender on one channel. A single human may have multiple user rows across channels (no cross-channel linking yet).
|
||||
verbs: list, get, create, update
|
||||
wirings Wiring — connects a messaging group to an agent group. Determines which agent handles messages from which chat. The same messaging group can be wired to multiple agents; the same agent can be wired to multiple messaging groups.
|
||||
verbs: list, get, create, update, delete
|
||||
|
||||
Commands:
|
||||
help List available resources and commands.
|
||||
|
||||
Run `ncl <resource> help` for detailed field information.
|
||||
@@ -1,57 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
// Stub CLI for clidash tests. Impersonates ncl (envelope json) or a
|
||||
// jsonlines CLI, with failure/slowness/garbage modes driven by env vars.
|
||||
import { readFileSync, appendFileSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const args = process.argv.slice(2);
|
||||
|
||||
if (process.env.STUB_COUNT_FILE) {
|
||||
appendFileSync(process.env.STUB_COUNT_FILE, args.join(' ') + '\n');
|
||||
}
|
||||
|
||||
const sleepMs = Number(process.env.STUB_SLEEP_MS || 0);
|
||||
|
||||
setTimeout(() => {
|
||||
if (process.env.STUB_FAIL) {
|
||||
process.stderr.write('boom: socket down\n');
|
||||
process.exit(2);
|
||||
}
|
||||
if (args[0] === 'help') {
|
||||
process.stdout.write(
|
||||
readFileSync(fileURLToPath(new URL('./ncl-help.txt', import.meta.url)), 'utf8'),
|
||||
);
|
||||
process.exit(0);
|
||||
}
|
||||
if (args[1] === 'help') { // `<resource> help` → raw per-resource help text
|
||||
process.stdout.write(`${args[0]}: help for ${args[0]}\n\nVerbs:\n list\n get <id>\n`);
|
||||
process.exit(0);
|
||||
}
|
||||
if (process.env.STUB_RAW) {
|
||||
process.stdout.write(process.env.STUB_RAW + '\n');
|
||||
process.exit(0);
|
||||
}
|
||||
const resource = args[0];
|
||||
// `get`/detail commands → single-object envelope
|
||||
if (args.includes('get') || args.includes('config')) {
|
||||
process.stdout.write(JSON.stringify({
|
||||
id: 'req-1', ok: true,
|
||||
data: { id: `${resource}-detail`, args: args.join(' '), extra: 'field' },
|
||||
}) + '\n');
|
||||
process.exit(0);
|
||||
}
|
||||
if (process.env.STUB_JSONLINES) {
|
||||
process.stdout.write(JSON.stringify({ id: `${resource}-1`, name: 'row one' }) + '\n');
|
||||
process.stdout.write(JSON.stringify({ id: `${resource}-2`, name: 'row two' }) + '\n');
|
||||
process.exit(0);
|
||||
}
|
||||
process.stdout.write(JSON.stringify({
|
||||
id: 'req-1',
|
||||
ok: true,
|
||||
data: [
|
||||
{ id: `${resource}-1`, name: 'row one' },
|
||||
{ id: `${resource}-2`, name: 'row two' },
|
||||
],
|
||||
}) + '\n');
|
||||
process.exit(0);
|
||||
}, sleepMs);
|
||||
@@ -1,61 +0,0 @@
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
const STUB = fileURLToPath(new URL('./fixtures/stub-cli.js', import.meta.url));
|
||||
|
||||
function cli(extra = {}) {
|
||||
return {
|
||||
bin: process.execPath,
|
||||
discover: { args: [STUB, 'help'], parser: 'ncl-help' },
|
||||
list: [STUB, '{resource}', 'list', '--json'],
|
||||
output: 'json', unwrap: 'data',
|
||||
help: [STUB, '{resource}', 'help'],
|
||||
...extra,
|
||||
};
|
||||
}
|
||||
|
||||
async function withServer(clis, fn) {
|
||||
const server = createApp({ port: 0, bind: '127.0.0.1', execTimeoutMs: 2000, clis });
|
||||
await new Promise((r) => server.listen(0, '127.0.0.1', r));
|
||||
const base = `http://127.0.0.1:${server.address().port}`;
|
||||
try { return await fn(base); } finally { await new Promise((r) => server.close(r)); }
|
||||
}
|
||||
|
||||
test('/api/help: returns raw per-resource help text', async () => {
|
||||
await withServer({ ncl: cli() }, async (base) => {
|
||||
const body = await (await fetch(`${base}/api/help/ncl/sessions`)).json();
|
||||
assert.equal(body.ok, true);
|
||||
assert.match(body.text, /sessions: help for sessions/);
|
||||
assert.match(body.text, /Verbs:/);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/help: undiscovered resource → 404', async () => {
|
||||
await withServer({ ncl: cli() }, async (base) => {
|
||||
assert.equal((await fetch(`${base}/api/help/ncl/evil`)).status, 404);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/help: a cli without a help template → 404', async () => {
|
||||
const c = cli(); delete c.help;
|
||||
await withServer({ ncl: c }, async (base) => {
|
||||
assert.equal((await fetch(`${base}/api/help/ncl/sessions`)).status, 404);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/help: unknown cli → 404', async () => {
|
||||
await withServer({ ncl: cli() }, async (base) => {
|
||||
assert.equal((await fetch(`${base}/api/help/nope/sessions`)).status, 404);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/clis: reports help availability per cli', async () => {
|
||||
const noHelp = cli(); delete noHelp.help;
|
||||
await withServer({ ncl: cli(), docker: noHelp }, async (base) => {
|
||||
const body = await (await fetch(`${base}/api/clis`)).json();
|
||||
assert.equal(body.clis.find((c) => c.name === 'ncl').help, true);
|
||||
assert.equal(body.clis.find((c) => c.name === 'docker').help, false);
|
||||
});
|
||||
});
|
||||
@@ -1,75 +0,0 @@
|
||||
import { test, before, after } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { tailFile } from '../logs.js';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
let dir;
|
||||
before(() => {
|
||||
dir = mkdtempSync(join(tmpdir(), 'clidash-logs-'));
|
||||
// 10 lines, some with ANSI color codes
|
||||
const lines = Array.from({ length: 10 }, (_, i) =>
|
||||
`[12:00:0${i}] \x1b[32mINFO\x1b[39m line ${i}`);
|
||||
writeFileSync(join(dir, 'app.log'), lines.join('\n') + '\n');
|
||||
writeFileSync(join(dir, 'error.log'), 'boom\n');
|
||||
});
|
||||
after(() => rmSync(dir, { recursive: true, force: true }));
|
||||
|
||||
test('tailFile: returns the last N lines, ANSI stripped, no trailing blank', async () => {
|
||||
const { lines, text } = await tailFile(join(dir, 'app.log'), 3);
|
||||
assert.equal(lines.length, 3);
|
||||
assert.deepEqual(lines, ['[12:00:07] INFO line 7', '[12:00:08] INFO line 8', '[12:00:09] INFO line 9']);
|
||||
assert.ok(!text.includes('\x1b'));
|
||||
});
|
||||
|
||||
test('tailFile: maxLines larger than file returns all lines', async () => {
|
||||
const { lines } = await tailFile(join(dir, 'app.log'), 100);
|
||||
assert.equal(lines.length, 10);
|
||||
});
|
||||
|
||||
// ---- server endpoints ----
|
||||
|
||||
function cfg() {
|
||||
return {
|
||||
port: 0, bind: '127.0.0.1', clis: {},
|
||||
logs: { dir, tailLines: 5, files: [{ name: 'app.log', label: 'app' }, { name: 'error.log', label: 'errors' }] },
|
||||
};
|
||||
}
|
||||
async function withServer(config, fn) {
|
||||
const server = createApp(config);
|
||||
await new Promise((r) => server.listen(0, '127.0.0.1', r));
|
||||
const base = `http://127.0.0.1:${server.address().port}`;
|
||||
try { return await fn(base); } finally { await new Promise((r) => server.close(r)); }
|
||||
}
|
||||
|
||||
test('/api/logs: lists the configured log files', async () => {
|
||||
await withServer(cfg(), async (base) => {
|
||||
const body = await (await fetch(`${base}/api/logs`)).json();
|
||||
assert.deepEqual(body.files.map((f) => f.name), ['app.log', 'error.log']);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/logs: absent logs config → empty list', async () => {
|
||||
await withServer({ port: 0, bind: '127.0.0.1', clis: {} }, async (base) => {
|
||||
assert.deepEqual((await (await fetch(`${base}/api/logs`)).json()).files, []);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/log: returns the tail text + a tail command', async () => {
|
||||
await withServer(cfg(), async (base) => {
|
||||
const body = await (await fetch(`${base}/api/log/app.log`)).json();
|
||||
assert.equal(body.ok, true);
|
||||
assert.match(body.text, /line 9$/);
|
||||
assert.equal(body.text.split('\n').length, 5); // tailLines
|
||||
assert.match(body.command, /tail -n 5 .*app\.log/);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/log: a name not in the allowlist is rejected (no traversal)', async () => {
|
||||
await withServer(cfg(), async (base) => {
|
||||
assert.equal((await fetch(`${base}/api/log/${encodeURIComponent('../../etc/passwd')}`)).status, 404);
|
||||
assert.equal((await fetch(`${base}/api/log/secrets.log`)).status, 404);
|
||||
});
|
||||
});
|
||||
@@ -1,63 +0,0 @@
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { escapeHtml, mdToHtml } from '../public/md.js';
|
||||
|
||||
// ---- escaping -------------------------------------------------------------
|
||||
|
||||
test('escapeHtml: neutralizes all HTML metacharacters', () => {
|
||||
assert.equal(escapeHtml(`<script>"&'`), '<script>"&'');
|
||||
});
|
||||
|
||||
test('mdToHtml: raw HTML in source is escaped, never passed through', () => {
|
||||
const html = mdToHtml('a <script>alert(1)</script> b');
|
||||
assert.ok(!html.includes('<script>'));
|
||||
assert.ok(html.includes('<script>'));
|
||||
});
|
||||
|
||||
// ---- the security-sensitive part: links -----------------------------------
|
||||
|
||||
test('mdToHtml: link href comes from the URL, label from the text', () => {
|
||||
const html = mdToHtml('see [the docs](https://example.com/x)');
|
||||
assert.match(html, /<a href="https:\/\/example\.com\/x" target="_blank" rel="noopener noreferrer">the docs<\/a>/);
|
||||
});
|
||||
|
||||
test('mdToHtml: javascript: smuggled in link TEXT stays inert (never an href)', () => {
|
||||
const html = mdToHtml('[javascript:alert(1)](https://safe.com)');
|
||||
// href is the safe URL; the js string is only visible label text
|
||||
assert.match(html, /href="https:\/\/safe\.com"/);
|
||||
assert.ok(!/href="javascript:/i.test(html));
|
||||
});
|
||||
|
||||
test('mdToHtml: a non-http(s) URL is not turned into a link', () => {
|
||||
// javascript:/data: never match the (https?:...) capture, so the literal
|
||||
// (escaped) markdown is left as-is — no anchor, no executable href.
|
||||
const html = mdToHtml('[click](javascript:alert(1))');
|
||||
assert.ok(!/<a /.test(html));
|
||||
assert.ok(!/href="javascript:/i.test(html));
|
||||
});
|
||||
|
||||
test('mdToHtml: an attribute-breakout attempt in the URL cannot escape the href', () => {
|
||||
// The double-quote is escaped to " before the regex runs, so it can never
|
||||
// close an attribute. (Here the URL also has a space, so no anchor even forms.)
|
||||
// The security property: no REAL attribute (with a literal quote) is injected.
|
||||
const html = mdToHtml('[x](https://a" onmouseover="alert(1))');
|
||||
assert.ok(!/<a/.test(html), 'malformed link must not produce an anchor');
|
||||
assert.ok(!/onmouseover="/.test(html), 'no real (unescaped-quote) attribute injected');
|
||||
});
|
||||
|
||||
test('mdToHtml: an escaped quote inside a matched URL stays inside the href, inert', () => {
|
||||
// Even when a URL matches, any " in it is already " (an entity), which
|
||||
// does not terminate an HTML attribute value — so no breakout.
|
||||
const html = mdToHtml('[x](https://a"onmouseover=alert)');
|
||||
assert.ok(!/onmouseover="/.test(html));
|
||||
if (/<a/.test(html)) assert.match(html, /href="https:\/\/a"onmouseover=alert"/);
|
||||
});
|
||||
|
||||
// ---- basic rendering sanity ----------------------------------------------
|
||||
|
||||
test('mdToHtml: headings, code fences, lists render', () => {
|
||||
const html = mdToHtml('# Title\n\n```\ncode\n```\n\n- a\n- b');
|
||||
assert.match(html, /<h1>Title<\/h1>/);
|
||||
assert.match(html, /<pre class="code"><code>code<\/code><\/pre>/);
|
||||
assert.match(html, /<ul><li>a<\/li><li>b<\/li><\/ul>/);
|
||||
});
|
||||
@@ -1,70 +0,0 @@
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import overview from '../views/ncl-overview.js';
|
||||
|
||||
const minutesAgo = (m) => new Date(Date.now() - m * 60_000).toISOString();
|
||||
|
||||
// Shapes mirror real `ncl <resource> list --json` output.
|
||||
function makeFixtures({ alphaLastActive, bravoLastActive }) {
|
||||
return {
|
||||
groups: [
|
||||
{ id: 'ag-1', name: 'Alpha', folder: 'alpha', created_at: '2026-05-31T11:14:48.793Z' },
|
||||
{ id: 'ag-2', name: 'Bravo Team', folder: 'bravo', created_at: '2026-05-31T11:14:48.796Z' },
|
||||
{ id: 'ag-3', name: 'Orphan', folder: 'orphan', created_at: '2026-05-31T11:14:48.799Z' },
|
||||
],
|
||||
sessions: [
|
||||
{ id: 'sess-1', agent_group_id: 'ag-1', messaging_group_id: 'mg-1', thread_id: null, status: 'active', container_status: 'stopped', last_active: alphaLastActive, created_at: '2026-05-31T11:14:51.911Z' },
|
||||
{ id: 'sess-2', agent_group_id: 'ag-2', messaging_group_id: 'mg-2', thread_id: null, status: 'active', container_status: 'running', last_active: bravoLastActive, created_at: '2026-05-31T11:14:51.973Z' },
|
||||
],
|
||||
'messaging-groups': [
|
||||
{ id: 'mg-1', channel_type: 'telegram', platform_id: 'telegram:1', name: 'Alpha', is_group: 0 },
|
||||
{ id: 'mg-2', channel_type: 'telegram', platform_id: 'telegram:2', name: 'Bravo Team', is_group: 0 },
|
||||
],
|
||||
wirings: [
|
||||
{ id: 'mga-1', messaging_group_id: 'mg-1', agent_group_id: 'ag-1', session_mode: 'shared' },
|
||||
{ id: 'mga-2', messaging_group_id: 'mg-2', agent_group_id: 'ag-2', session_mode: 'shared' },
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
function fetchFrom(fixtures) {
|
||||
return async (resource) => {
|
||||
if (!(resource in fixtures)) throw new Error(`unexpected fetch: ${resource}`);
|
||||
return fixtures[resource];
|
||||
};
|
||||
}
|
||||
|
||||
test('overview: one card per agent group with joined session + wiring data', async () => {
|
||||
const fixtures = makeFixtures({ alphaLastActive: minutesAgo(5), bravoLastActive: minutesAgo(30) });
|
||||
const result = await overview({ fetch: fetchFrom(fixtures) });
|
||||
assert.equal(result.cards.length, 3);
|
||||
|
||||
const alpha = result.cards.find((c) => c.title === 'Alpha');
|
||||
assert.equal(alpha.subtitle, 'alpha');
|
||||
assert.equal(alpha.fields.container, 'stopped');
|
||||
assert.equal(alpha.fields.sessions, 1);
|
||||
assert.deepEqual(alpha.badges, ['telegram: Alpha']);
|
||||
|
||||
const bravo = result.cards.find((c) => c.title === 'Bravo Team');
|
||||
assert.equal(bravo.fields.container, 'running');
|
||||
assert.deepEqual(bravo.badges, ['telegram: Bravo Team']);
|
||||
});
|
||||
|
||||
test('overview: staleness thresholds — green <15m, amber <2h, red older, gray never', async () => {
|
||||
const fixtures = makeFixtures({ alphaLastActive: minutesAgo(5), bravoLastActive: minutesAgo(30) });
|
||||
const result = await overview({ fetch: fetchFrom(fixtures) });
|
||||
assert.equal(result.cards.find((c) => c.title === 'Alpha').status, 'green');
|
||||
assert.equal(result.cards.find((c) => c.title === 'Bravo Team').status, 'amber');
|
||||
assert.equal(result.cards.find((c) => c.title === 'Orphan').status, 'gray');
|
||||
|
||||
const stale = makeFixtures({ alphaLastActive: minutesAgo(300), bravoLastActive: minutesAgo(30) });
|
||||
const result2 = await overview({ fetch: fetchFrom(stale) });
|
||||
assert.equal(result2.cards.find((c) => c.title === 'Alpha').status, 'red');
|
||||
});
|
||||
|
||||
test('overview: last_active is exposed for relative-time rendering', async () => {
|
||||
const ts = minutesAgo(5);
|
||||
const fixtures = makeFixtures({ alphaLastActive: ts, bravoLastActive: minutesAgo(30) });
|
||||
const result = await overview({ fetch: fetchFrom(fixtures) });
|
||||
assert.equal(result.cards.find((c) => c.title === 'Alpha').fields['last active'], ts);
|
||||
});
|
||||
@@ -1,111 +0,0 @@
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { discoveryParsers, parseOutput, unwrapPath } from '../parsers.js';
|
||||
|
||||
const fixture = readFileSync(
|
||||
fileURLToPath(new URL('./fixtures/ncl-help.txt', import.meta.url)),
|
||||
'utf8',
|
||||
);
|
||||
|
||||
// ---------------------------------------------------------------- ncl-help
|
||||
|
||||
test('ncl-help: parses all listable resources from real captured output', () => {
|
||||
const resources = discoveryParsers['ncl-help'](fixture);
|
||||
assert.deepEqual(
|
||||
resources.map((r) => r.name),
|
||||
[
|
||||
'approvals', 'destinations', 'dropped-messages', 'groups', 'members',
|
||||
'messaging-groups', 'roles', 'sessions', 'user-dms', 'users', 'wirings',
|
||||
],
|
||||
);
|
||||
});
|
||||
|
||||
test('ncl-help: every parsed resource has a non-empty description and a list verb', () => {
|
||||
const resources = discoveryParsers['ncl-help'](fixture);
|
||||
for (const r of resources) {
|
||||
assert.ok(r.description.length > 0, `${r.name} has empty description`);
|
||||
assert.ok(r.verbs.includes('list'), `${r.name} missing list verb`);
|
||||
}
|
||||
});
|
||||
|
||||
test('ncl-help: parses verbs correctly, including multi-word verbs', () => {
|
||||
const resources = discoveryParsers['ncl-help'](fixture);
|
||||
const groups = resources.find((r) => r.name === 'groups');
|
||||
assert.deepEqual(groups.verbs, [
|
||||
'list', 'get', 'create', 'update', 'delete', 'restart',
|
||||
'config get', 'config update', 'config add-mcp-server',
|
||||
'config remove-mcp-server', 'config add-package', 'config remove-package',
|
||||
]);
|
||||
});
|
||||
|
||||
test('ncl-help: excludes resources without a list verb', () => {
|
||||
const input = [
|
||||
'Resources:',
|
||||
' alpha Has list.',
|
||||
' verbs: list, get',
|
||||
' beta No list here.',
|
||||
' verbs: grant, revoke',
|
||||
'',
|
||||
].join('\n');
|
||||
const resources = discoveryParsers['ncl-help'](input);
|
||||
assert.deepEqual(resources.map((r) => r.name), ['alpha']);
|
||||
});
|
||||
|
||||
test('ncl-help: ignores the Commands section (help is not a resource)', () => {
|
||||
const resources = discoveryParsers['ncl-help'](fixture);
|
||||
assert.ok(!resources.some((r) => r.name === 'help'));
|
||||
});
|
||||
|
||||
test('ncl-help: throws loudly on unrecognized format', () => {
|
||||
assert.throws(() => discoveryParsers['ncl-help']('totally not help output'), /Resources/);
|
||||
assert.throws(() => discoveryParsers['ncl-help'](''), /Resources/);
|
||||
});
|
||||
|
||||
// ------------------------------------------------------------- parseOutput
|
||||
|
||||
test('parseOutput json: parses a single document', () => {
|
||||
assert.deepEqual(parseOutput('{"a": 1}', 'json'), { a: 1 });
|
||||
});
|
||||
|
||||
test('parseOutput json: throws on malformed input with raw output preserved', () => {
|
||||
assert.throws(() => parseOutput('not json', 'json'), (err) => {
|
||||
assert.match(err.message, /JSON/i);
|
||||
assert.equal(err.raw, 'not json');
|
||||
return true;
|
||||
});
|
||||
});
|
||||
|
||||
test('parseOutput jsonlines: one object per line, blank lines skipped', () => {
|
||||
const text = '{"id":1}\n\n{"id":2}\n{"id":3}\n';
|
||||
assert.deepEqual(parseOutput(text, 'jsonlines'), [{ id: 1 }, { id: 2 }, { id: 3 }]);
|
||||
});
|
||||
|
||||
test('parseOutput jsonlines: throws on a malformed line', () => {
|
||||
assert.throws(() => parseOutput('{"ok":1}\ngarbage\n', 'jsonlines'), /line 2/i);
|
||||
});
|
||||
|
||||
test('parseOutput: rejects unknown format', () => {
|
||||
assert.throws(() => parseOutput('{}', 'xml'), /format/i);
|
||||
});
|
||||
|
||||
// -------------------------------------------------------------- unwrapPath
|
||||
|
||||
test('unwrapPath: extracts the ncl {id, ok, data} envelope', () => {
|
||||
const doc = { id: 'x', ok: true, data: [{ id: 'sess-1' }] };
|
||||
assert.deepEqual(unwrapPath(doc, 'data'), [{ id: 'sess-1' }]);
|
||||
});
|
||||
|
||||
test('unwrapPath: supports nested dot paths', () => {
|
||||
assert.deepEqual(unwrapPath({ a: { b: [1, 2] } }, 'a.b'), [1, 2]);
|
||||
});
|
||||
|
||||
test('unwrapPath: throws when the path is missing', () => {
|
||||
assert.throws(() => unwrapPath({ ok: true }, 'data'), /data/);
|
||||
});
|
||||
|
||||
test('unwrapPath: no path returns the value unchanged', () => {
|
||||
const rows = [{ id: 1 }];
|
||||
assert.equal(unwrapPath(rows, undefined), rows);
|
||||
});
|
||||
@@ -1,240 +0,0 @@
|
||||
import { test, before, after } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
const STUB = fileURLToPath(new URL('./fixtures/stub-cli.js', import.meta.url));
|
||||
const tmp = mkdtempSync(join(tmpdir(), 'clidash-test-'));
|
||||
|
||||
function stubCli(extra = {}) {
|
||||
return {
|
||||
bin: process.execPath,
|
||||
discover: { args: [STUB, 'help'], parser: 'ncl-help' },
|
||||
list: [STUB, '{resource}', 'list', '--json'],
|
||||
output: 'json',
|
||||
unwrap: 'data',
|
||||
...extra,
|
||||
};
|
||||
}
|
||||
|
||||
function makeConfig(clis, extra = {}) {
|
||||
return { port: 0, bind: '127.0.0.1', execTimeoutMs: 2000, refreshSeconds: 10, clis, ...extra };
|
||||
}
|
||||
|
||||
async function withServer(config, fn) {
|
||||
const server = createApp(config);
|
||||
await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
|
||||
const base = `http://127.0.0.1:${server.address().port}`;
|
||||
try {
|
||||
return await fn(base);
|
||||
} finally {
|
||||
await new Promise((resolve) => server.close(resolve));
|
||||
}
|
||||
}
|
||||
|
||||
after(() => rmSync(tmp, { recursive: true, force: true }));
|
||||
|
||||
// ----------------------------------------------------------------- /api/clis
|
||||
|
||||
test('/api/clis: lists configured CLIs with discovered resources', async () => {
|
||||
await withServer(makeConfig({ stub: stubCli() }), async (base) => {
|
||||
const res = await fetch(`${base}/api/clis`);
|
||||
assert.equal(res.status, 200);
|
||||
const body = await res.json();
|
||||
assert.equal(body.clis.length, 1);
|
||||
assert.equal(body.clis[0].name, 'stub');
|
||||
assert.equal(body.clis[0].refreshSeconds, 10);
|
||||
const names = body.clis[0].resources.map((r) => r.name);
|
||||
assert.ok(names.includes('sessions'));
|
||||
assert.ok(names.includes('groups'));
|
||||
assert.equal(names.length, 11);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/clis: static resource list needs no discovery', async () => {
|
||||
const cli = stubCli({ resources: ['alpha', 'beta'] });
|
||||
delete cli.discover;
|
||||
await withServer(makeConfig({ stub: cli }), async (base) => {
|
||||
const body = await (await fetch(`${base}/api/clis`)).json();
|
||||
assert.deepEqual(body.clis[0].resources.map((r) => r.name), ['alpha', 'beta']);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/clis: discovery failure reports a loud error', async () => {
|
||||
const cli = stubCli();
|
||||
cli.env = { STUB_FAIL: '1' };
|
||||
await withServer(makeConfig({ stub: cli }), async (base) => {
|
||||
const body = await (await fetch(`${base}/api/clis`)).json();
|
||||
assert.equal(body.clis[0].resources.length, 0);
|
||||
assert.match(body.clis[0].error, /boom/);
|
||||
});
|
||||
});
|
||||
|
||||
// ------------------------------------------------------------ /api/r/cli/res
|
||||
|
||||
test('/api/r: returns unwrapped rows with fetchedAt', async () => {
|
||||
await withServer(makeConfig({ stub: stubCli() }), async (base) => {
|
||||
const res = await fetch(`${base}/api/r/stub/sessions`);
|
||||
assert.equal(res.status, 200);
|
||||
const body = await res.json();
|
||||
assert.equal(body.ok, true);
|
||||
assert.deepEqual(body.rows.map((r) => r.id), ['sessions-1', 'sessions-2']);
|
||||
assert.ok(body.fetchedAt);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/r: rejects a resource not in the discovered set without exec', async () => {
|
||||
const countFile = join(tmp, 'count-reject.txt');
|
||||
const cli = stubCli();
|
||||
cli.env = { STUB_COUNT_FILE: countFile };
|
||||
await withServer(makeConfig({ stub: cli }), async (base) => {
|
||||
const res = await fetch(`${base}/api/r/stub/evil%20--rm`);
|
||||
assert.equal(res.status, 404);
|
||||
const body = await res.json();
|
||||
assert.equal(body.ok, false);
|
||||
// only the discovery exec ran — never a list exec for the bogus resource
|
||||
const calls = readFileSync(countFile, 'utf8').trim().split('\n');
|
||||
assert.deepEqual(calls, ['help']);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/r: unknown cli → 404', async () => {
|
||||
await withServer(makeConfig({ stub: stubCli() }), async (base) => {
|
||||
const res = await fetch(`${base}/api/r/nope/sessions`);
|
||||
assert.equal(res.status, 404);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/r: jsonlines CLI with static resources works', async () => {
|
||||
const cli = {
|
||||
bin: process.execPath,
|
||||
resources: ['ps'],
|
||||
list: [STUB, '{resource}'],
|
||||
output: 'jsonlines',
|
||||
env: { STUB_JSONLINES: '1' },
|
||||
};
|
||||
await withServer(makeConfig({ docker: cli }), async (base) => {
|
||||
const body = await (await fetch(`${base}/api/r/docker/ps`)).json();
|
||||
assert.equal(body.ok, true);
|
||||
assert.deepEqual(body.rows.map((r) => r.id), ['ps-1', 'ps-2']);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/r: exec failure returns ok:false with stderr', async () => {
|
||||
const cli = stubCli({ resources: ['sessions'] });
|
||||
delete cli.discover;
|
||||
cli.env = { STUB_FAIL: '1' };
|
||||
await withServer(makeConfig({ stub: cli }), async (base) => {
|
||||
const res = await fetch(`${base}/api/r/stub/sessions`);
|
||||
assert.equal(res.status, 502);
|
||||
const body = await res.json();
|
||||
assert.equal(body.ok, false);
|
||||
assert.match(body.error, /boom: socket down/);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/r: exec timeout returns ok:false naming the resource', async () => {
|
||||
const cli = stubCli({ resources: ['sessions'] });
|
||||
delete cli.discover;
|
||||
cli.env = { STUB_SLEEP_MS: '5000' };
|
||||
await withServer(makeConfig({ stub: cli }, { execTimeoutMs: 200 }), async (base) => {
|
||||
const body = await (await fetch(`${base}/api/r/stub/sessions`)).json();
|
||||
assert.equal(body.ok, false);
|
||||
assert.match(body.error, /sessions/);
|
||||
assert.match(body.error, /timed out/i);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/r: malformed CLI output returns the raw output', async () => {
|
||||
const cli = stubCli({ resources: ['sessions'] });
|
||||
delete cli.discover;
|
||||
cli.env = { STUB_RAW: 'this is not json' };
|
||||
await withServer(makeConfig({ stub: cli }), async (base) => {
|
||||
const body = await (await fetch(`${base}/api/r/stub/sessions`)).json();
|
||||
assert.equal(body.ok, false);
|
||||
assert.match(body.raw, /this is not json/);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/r: concurrent requests for the same resource coalesce into one exec', async () => {
|
||||
const countFile = join(tmp, 'count-coalesce.txt');
|
||||
const cli = stubCli({ resources: ['sessions'] });
|
||||
delete cli.discover;
|
||||
cli.env = { STUB_COUNT_FILE: countFile, STUB_SLEEP_MS: '150' };
|
||||
await withServer(makeConfig({ stub: cli }), async (base) => {
|
||||
const bodies = await Promise.all(
|
||||
Array.from({ length: 5 }, () => fetch(`${base}/api/r/stub/sessions`).then((r) => r.json())),
|
||||
);
|
||||
for (const body of bodies) assert.equal(body.ok, true);
|
||||
const calls = readFileSync(countFile, 'utf8').trim().split('\n');
|
||||
assert.equal(calls.length, 1);
|
||||
});
|
||||
});
|
||||
|
||||
// ------------------------------------------------------------- /api/view
|
||||
|
||||
test('/api/view: runs a view plugin with a bound fetch helper', async () => {
|
||||
const viewsDir = join(tmp, 'views');
|
||||
writeFileSync(join(viewsDir, '..', 'placeholder'), ''); // ensure tmp exists
|
||||
const { mkdirSync } = await import('node:fs');
|
||||
mkdirSync(viewsDir, { recursive: true });
|
||||
writeFileSync(
|
||||
join(viewsDir, 'stub-overview.js'),
|
||||
'export default async function ({ fetch }) {\n' +
|
||||
' const rows = await fetch("sessions");\n' +
|
||||
' return { count: rows.length, first: rows[0].id };\n' +
|
||||
'}\n',
|
||||
);
|
||||
await withServer(makeConfig({ stub: stubCli() }, { viewsDir }), async (base) => {
|
||||
const res = await fetch(`${base}/api/view/stub/overview`);
|
||||
assert.equal(res.status, 200);
|
||||
const body = await res.json();
|
||||
assert.equal(body.ok, true);
|
||||
assert.deepEqual(body.result, { count: 2, first: 'sessions-1' });
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/view: missing view → 404; bad view name → 404', async () => {
|
||||
await withServer(makeConfig({ stub: stubCli() }, { viewsDir: join(tmp, 'views') }), async (base) => {
|
||||
assert.equal((await fetch(`${base}/api/view/stub/nope`)).status, 404);
|
||||
assert.equal((await fetch(`${base}/api/view/stub/..%2F..%2Fserver`)).status, 404);
|
||||
});
|
||||
});
|
||||
|
||||
// ------------------------------------------------------------- static files
|
||||
|
||||
test('GET /: serves the dashboard index.html', async () => {
|
||||
await withServer(makeConfig({ stub: stubCli() }), async (base) => {
|
||||
const res = await fetch(`${base}/`);
|
||||
assert.equal(res.status, 200);
|
||||
assert.match(res.headers.get('content-type'), /text\/html/);
|
||||
assert.match(await res.text(), /clidash/i);
|
||||
});
|
||||
});
|
||||
|
||||
test('static: path traversal outside public/ is rejected', async () => {
|
||||
await withServer(makeConfig({ stub: stubCli() }), async (base) => {
|
||||
const res = await fetch(`${base}/..%2Fserver.js`);
|
||||
assert.notEqual(res.status, 200);
|
||||
});
|
||||
});
|
||||
|
||||
test('/api/r: {resource} substitutes inside a larger argv string (ssh-remote pattern)', async () => {
|
||||
const cli = {
|
||||
bin: process.execPath,
|
||||
resources: ['sessions'],
|
||||
list: [STUB, 'wrapped-{resource}-arg', 'list'],
|
||||
output: 'json',
|
||||
unwrap: 'data',
|
||||
env: { STUB_COUNT_FILE: join(tmp, 'count-embed.txt') },
|
||||
};
|
||||
await withServer(makeConfig({ stub: cli }), async (base) => {
|
||||
const body = await (await fetch(`${base}/api/r/stub/sessions`)).json();
|
||||
assert.equal(body.ok, true);
|
||||
const calls = readFileSync(join(tmp, 'count-embed.txt'), 'utf8').trim();
|
||||
assert.equal(calls, 'wrapped-sessions-arg list');
|
||||
});
|
||||
});
|
||||
@@ -1,21 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Smoke test against a running clidash instance (run on the VM after deploy).
|
||||
# Usage: ./test/smoke.sh [base-url] (default http://127.0.0.1:4690)
|
||||
set -euo pipefail
|
||||
BASE="${1:-http://127.0.0.1:4690}"
|
||||
|
||||
check() {
|
||||
local label="$1" url="$2" pattern="$3"
|
||||
if curl -fsS --max-time 15 "$url" | grep -q "$pattern"; then
|
||||
echo "OK $label"
|
||||
else
|
||||
echo "FAIL $label ($url did not match $pattern)"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
check "/api/clis" "$BASE/api/clis" '"resources"'
|
||||
check "/api/r/ncl/sessions" "$BASE/api/r/ncl/sessions" '"ok":true'
|
||||
check "/api/view/ncl/overview" "$BASE/api/view/ncl/overview" '"ok":true'
|
||||
check "GET / (static UI)" "$BASE/" 'clidash'
|
||||
echo "smoke: all good"
|
||||
@@ -1,60 +0,0 @@
|
||||
// Curated "Agents overview" view for ncl: joins groups + sessions +
|
||||
// messaging-groups + wirings into per-agent cards. Returns the generic
|
||||
// card shape the frontend renders, so the UI itself stays CLI-agnostic:
|
||||
// { title, cards: [{ title, subtitle, status, fields, badges }] }
|
||||
// status: green <15m since last_active, amber <2h, red older, gray never.
|
||||
|
||||
const GREEN_MAX_MIN = 15;
|
||||
const AMBER_MAX_MIN = 120;
|
||||
|
||||
function staleness(lastActive) {
|
||||
if (!lastActive) return 'gray';
|
||||
const ageMin = (Date.now() - new Date(lastActive).getTime()) / 60_000;
|
||||
if (ageMin < GREEN_MAX_MIN) return 'green';
|
||||
if (ageMin < AMBER_MAX_MIN) return 'amber';
|
||||
return 'red';
|
||||
}
|
||||
|
||||
export default async function overview({ fetch }) {
|
||||
const [groups, sessions, messagingGroups, wirings] = await Promise.all([
|
||||
fetch('groups'),
|
||||
fetch('sessions'),
|
||||
fetch('messaging-groups'),
|
||||
fetch('wirings'),
|
||||
]);
|
||||
|
||||
const mgById = new Map(messagingGroups.map((mg) => [mg.id, mg]));
|
||||
|
||||
const cards = groups.map((group) => {
|
||||
const groupSessions = sessions.filter((s) => s.agent_group_id === group.id);
|
||||
const lastActive = groupSessions
|
||||
.map((s) => s.last_active)
|
||||
.filter(Boolean)
|
||||
.sort()
|
||||
.at(-1) ?? null;
|
||||
const container = groupSessions.some((s) => s.container_status === 'running')
|
||||
? 'running'
|
||||
: groupSessions[0]?.container_status ?? 'none';
|
||||
|
||||
const badges = wirings
|
||||
.filter((w) => w.agent_group_id === group.id)
|
||||
.map((w) => {
|
||||
const mg = mgById.get(w.messaging_group_id);
|
||||
return mg ? `${mg.channel_type}: ${mg.name ?? mg.platform_id}` : w.messaging_group_id;
|
||||
});
|
||||
|
||||
return {
|
||||
title: group.name,
|
||||
subtitle: group.folder,
|
||||
status: staleness(lastActive),
|
||||
fields: {
|
||||
container,
|
||||
sessions: groupSessions.length,
|
||||
'last active': lastActive,
|
||||
},
|
||||
badges,
|
||||
};
|
||||
});
|
||||
|
||||
return { title: 'Agents overview', cards };
|
||||
}
|
||||
@@ -11,8 +11,6 @@ NanoClaw selects each group's agent backend from `container_configs.provider` (d
|
||||
|
||||
The provider runs `codex app-server` as a child process speaking JSON-RPC over stdio: native streaming, MCP tools, server-side conversation history (the continuation is a thread id, no on-disk transcript). Credentials are **vault-only**: OneCLI serves a sentinel `auth.json` stub into the container and swaps the real ChatGPT token or API key on the wire — no key in `.env`, nothing readable in the container.
|
||||
|
||||
The mechanical steps under **Install** carry `nc:` directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
|
||||
## Install
|
||||
|
||||
### Pre-flight
|
||||
@@ -25,69 +23,92 @@ Check whether the payload is already wired (a prior apply, or a trunk that still
|
||||
- `import './codex.js';` in `src/providers/index.ts`, `container/agent-runner/src/providers/index.ts`, and `setup/providers/index.ts`
|
||||
- an `@openai/codex` entry in `container/cli-tools.json`
|
||||
|
||||
### 1. Fetch and copy the payload
|
||||
### Fetch and copy
|
||||
|
||||
Fetch the `providers` branch and copy the Codex payload into all three trees (additive — overwrite each file, never merge the branch). The host files are the provider contribution + AGENTS.md compose + their guards; the container files are the provider runtime (turn loop, JSON-RPC wrapper, per-exchange archiver) + their guards; the setup file is the picker entry + vault auth walk-through; `container/AGENTS.md` is the runtime-contract base the composed AGENTS.md embeds.
|
||||
|
||||
```nc:copy from-branch:providers
|
||||
src/providers/codex.ts
|
||||
src/providers/codex-agents-md.ts
|
||||
src/providers/codex-registration.test.ts
|
||||
src/providers/codex-host-contribution.test.ts
|
||||
src/providers/codex-agents-md.test.ts
|
||||
container/agent-runner/src/providers/codex.ts
|
||||
container/agent-runner/src/providers/codex-app-server.ts
|
||||
container/agent-runner/src/providers/exchange-archive.ts
|
||||
container/agent-runner/src/providers/exchange-archive.test.ts
|
||||
container/agent-runner/src/providers/codex-registration.test.ts
|
||||
container/agent-runner/src/providers/codex.factory.test.ts
|
||||
container/agent-runner/src/providers/codex.turns.test.ts
|
||||
container/agent-runner/src/providers/codex-app-server.test.ts
|
||||
container/agent-runner/src/providers/codex-cli-tools.test.ts
|
||||
setup/providers/codex.ts
|
||||
setup/providers/codex.test.ts
|
||||
setup/providers/codex-registration.test.ts
|
||||
container/AGENTS.md
|
||||
```bash
|
||||
git fetch origin providers
|
||||
```
|
||||
|
||||
### 2. Wire the barrels
|
||||
Copy each file with `git show origin/providers:<path> > <path>` (additive — never merge the branch):
|
||||
|
||||
Append the self-registration import to each of the three provider barrels (skipped if the line is already present). Each barrel-registration test imports its real barrel and asserts `codex` is registered — they go red the moment a barrel line is missing or drifts.
|
||||
Host (`src/providers/`):
|
||||
- `codex.ts` — provider contribution: per-group `.codex-shared` state dir, AGENTS.md compose, skill links
|
||||
- `codex-agents-md.ts` — AGENTS.md composition (32KB Codex cap: degrades by dropping the largest instruction sections, never blocks a spawn)
|
||||
- `codex-registration.test.ts` — barrel-driven host registration guard
|
||||
- `codex-host-contribution.test.ts` — drives the real contribution against a real test DB (the "consumes core" leg)
|
||||
- `codex-agents-md.test.ts` — cap-degradation behavior
|
||||
|
||||
```nc:append to:src/providers/index.ts
|
||||
import './codex.js';
|
||||
```
|
||||
```nc:append to:container/agent-runner/src/providers/index.ts
|
||||
import './codex.js';
|
||||
```
|
||||
```nc:append to:setup/providers/index.ts
|
||||
import './codex.js';
|
||||
Container (`container/agent-runner/src/providers/`):
|
||||
- `codex.ts` — the provider (turn loop, steering, memory scaffold + `onExchangeComplete` archiving)
|
||||
- `codex-app-server.ts` — JSON-RPC child-process wrapper
|
||||
- `exchange-archive.ts` — per-exchange markdown writer the `onExchangeComplete` hook uses (provider-owned, not runner code)
|
||||
- `exchange-archive.test.ts` — writer behavior
|
||||
- `codex-registration.test.ts` — barrel-driven container registration guard
|
||||
- `codex.factory.test.ts`, `codex.turns.test.ts`, `codex-app-server.test.ts` — provider behavior
|
||||
- `codex-cli-tools.test.ts` — structural guard for the Codex entry in `container/cli-tools.json`
|
||||
|
||||
Setup (`setup/providers/`):
|
||||
- `codex.ts` — picker entry self-registration + the vault auth walk-through + install check
|
||||
- `codex.test.ts` — install-check coverage
|
||||
- `codex-registration.test.ts` — barrel-driven setup registration guard
|
||||
|
||||
Shared base (skip if present):
|
||||
- `container/AGENTS.md` — the runtime-contract base the composed AGENTS.md embeds
|
||||
|
||||
### Wire the barrels
|
||||
|
||||
Append `import './codex.js';` to each of:
|
||||
- `src/providers/index.ts`
|
||||
- `container/agent-runner/src/providers/index.ts`
|
||||
- `setup/providers/index.ts`
|
||||
|
||||
### CLI manifest
|
||||
|
||||
The agent's global Node CLIs install from `container/cli-tools.json` (a json-merge seam), not hand-edited Dockerfile layers. Add Codex by appending one entry — `@openai/codex` has no native postinstall, so no `onlyBuilt`:
|
||||
|
||||
```bash
|
||||
node -e '
|
||||
const fs = require("fs");
|
||||
const file = "container/cli-tools.json";
|
||||
const tools = JSON.parse(fs.readFileSync(file, "utf8"));
|
||||
if (!tools.some((t) => t.name === "@openai/codex")) {
|
||||
tools.push({ name: "@openai/codex", version: "0.138.0" });
|
||||
const fmt = (t) => " { " + Object.entries(t).map(([k, v]) => JSON.stringify(k) + ": " + JSON.stringify(v)).join(", ") + " }";
|
||||
fs.writeFileSync(file, "[\n" + tools.map(fmt).join(",\n") + "\n]\n");
|
||||
}
|
||||
'
|
||||
```
|
||||
|
||||
### 3. CLI manifest
|
||||
The version (`0.138.0`) is the canonical pin — keep it in sync with `setup/add-codex.sh`. The Dockerfile already installs every manifest entry via pinned `pnpm install -g`; no Dockerfile edit is needed.
|
||||
|
||||
The agent's global Node CLIs install from `container/cli-tools.json` (a json-merge seam), not hand-edited Dockerfile layers. Add Codex by appending one entry — idempotent on `name`, so a re-run is a no-op. `@openai/codex` has no native postinstall, so no `onlyBuilt`. The Dockerfile already installs every manifest entry via pinned `pnpm install -g`; no Dockerfile edit is needed.
|
||||
### Build
|
||||
|
||||
```nc:json-merge into:container/cli-tools.json key:name
|
||||
{ "name": "@openai/codex", "version": "0.138.0" }
|
||||
```
|
||||
|
||||
The version (`0.138.0`) is the canonical pin — this SKILL.md is the source of truth.
|
||||
|
||||
### 4. Build
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit
|
||||
./container/build.sh
|
||||
```
|
||||
|
||||
### 5. Validate
|
||||
### Restart the host
|
||||
|
||||
```nc:run effect:test
|
||||
pnpm vitest run src/providers/codex-registration.test.ts src/providers/codex-host-contribution.test.ts src/providers/codex-agents-md.test.ts setup/providers/
|
||||
The image rebuild does not reload the **host**. Codex's host contribution
|
||||
(`src/providers/codex.ts`) registers the `/home/node/.codex` bind mount + env
|
||||
passthrough, and the running host only picks it up on restart. Skip this and the
|
||||
first Codex turn fails with `EACCES` writing `/home/node/.codex/config.toml` —
|
||||
with no mount, Docker auto-creates the dir root-owned and the non-root container
|
||||
user can't write to it.
|
||||
|
||||
```bash
|
||||
# macOS (launchd)
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw
|
||||
# Linux (systemd)
|
||||
systemctl --user restart nanoclaw
|
||||
```
|
||||
```nc:run effect:test
|
||||
|
||||
### Validate
|
||||
|
||||
```bash
|
||||
pnpm vitest run src/providers/codex-registration.test.ts src/providers/codex-host-contribution.test.ts src/providers/codex-agents-md.test.ts setup/providers/
|
||||
cd container/agent-runner && bun test src/providers/
|
||||
```
|
||||
|
||||
@@ -95,7 +116,9 @@ The registration tests import only the real barrels — they go red if a barrel
|
||||
|
||||
## Authenticate
|
||||
|
||||
```nc:run effect:external
|
||||
> **Run this in a separate, real terminal — it is interactive.** It prompts for ChatGPT-subscription vs OpenAI-API-key and then drives a browser/device login, so it needs a TTY to answer prompts.
|
||||
|
||||
```bash
|
||||
pnpm exec tsx setup/index.ts --step provider-auth codex
|
||||
```
|
||||
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
// Structural guard for the Codex CLI install in container/cli-tools.json.
|
||||
//
|
||||
// @openai/codex is a CLI *binary* installed from the global-CLI manifest (a
|
||||
// json-merge seam), not an importable package, so the barrel-driven
|
||||
// registration tests cannot see it. This test reads the real cli-tools.json
|
||||
// and asserts the @openai/codex entry is present and pinned to an exact
|
||||
// version. It goes red if the manifest entry is dropped or unpins.
|
||||
//
|
||||
// Runs under bun (same suite as the container registration test):
|
||||
// cd container/agent-runner && bun test src/providers/codex-cli-tools.test.ts
|
||||
|
||||
import { existsSync, readFileSync } from 'fs';
|
||||
import path from 'path';
|
||||
|
||||
import { describe, it, expect } from 'bun:test';
|
||||
|
||||
// container/agent-runner/src/providers/ -> container/cli-tools.json
|
||||
const MANIFEST = path.join(import.meta.dir, '..', '..', '..', 'cli-tools.json');
|
||||
const manifestPresent = existsSync(MANIFEST);
|
||||
|
||||
// Read lazily — `describe.skipIf` still runs the body to register tests, so the
|
||||
// read has to be guarded for the bare-branch (no manifest) case.
|
||||
const tools: Array<{ name: string; version: string }> = manifestPresent
|
||||
? JSON.parse(readFileSync(MANIFEST, 'utf8'))
|
||||
: [];
|
||||
const codex = tools.find((t) => t.name === '@openai/codex');
|
||||
|
||||
// cli-tools.json is a trunk file; on the bare providers branch it isn't present,
|
||||
// so skip there. In an installed tree (trunk + this payload) it must carry the
|
||||
// pinned @openai/codex entry.
|
||||
describe.skipIf(!manifestPresent)('container/cli-tools.json codex CLI install', () => {
|
||||
it('includes the @openai/codex entry', () => {
|
||||
expect(codex).toBeDefined();
|
||||
});
|
||||
|
||||
it('pins it to an exact semver (no latest, no ranges)', () => {
|
||||
expect(codex?.version).toMatch(/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/);
|
||||
});
|
||||
});
|
||||
@@ -89,6 +89,7 @@ DC_SMTP_SECURITY=2 # 2=STARTTLS (default), 1=SSL/TLS, 3=plain
|
||||
|
||||
Security settings are applied on every startup, so changing them in `.env` and restarting takes effect without wiping the account.
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Optional settings
|
||||
|
||||
|
||||
@@ -5,151 +5,98 @@ description: Add Discord bot channel integration via Chat SDK.
|
||||
|
||||
# Add Discord Channel
|
||||
|
||||
Adds Discord bot support via the Chat SDK bridge. NanoClaw doesn't ship channels
|
||||
in trunk — this skill copies the Discord adapter in from the `channels` branch.
|
||||
Adds Discord bot support via the Chat SDK bridge.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent
|
||||
reads the prose and applies them, and a parser can apply them deterministically
|
||||
from the same document. Every directive is idempotent, so the whole skill is
|
||||
safe to re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
## Apply
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the Discord adapter in from the `channels` branch.
|
||||
|
||||
### 1. Copy the adapter and its registration test
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the Discord adapter and its registration
|
||||
test into `src/channels/` (overwrite — the branch is canonical):
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/discord.ts
|
||||
src/channels/discord-registration.test.ts
|
||||
- `src/channels/discord.ts` exists
|
||||
- `src/channels/discord-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './discord.js';`
|
||||
- `@chat-adapter/discord` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/discord.ts > src/channels/discord.ts
|
||||
git show origin/channels:src/channels/discord-registration.test.ts > src/channels/discord-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './discord.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
@chat-adapter/discord@4.29.0
|
||||
```bash
|
||||
pnpm install @chat-adapter/discord@4.29.0
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Build and validate
|
||||
|
||||
Build first: it guards the typed `createChatSdkBridge(...)` core call and proves
|
||||
the dependency is installed. Then run the one integration test.
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/discord-registration.test.ts
|
||||
```
|
||||
|
||||
`discord-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `discord`. It goes red if the import line is deleted or drifts,
|
||||
if the barrel fails to evaluate, or if `@chat-adapter/discord` isn't installed
|
||||
(the import throws) — so it also covers the dependency from step 3. End-to-end
|
||||
delivery against a real server is verified manually once the service runs.
|
||||
Both must be clean before proceeding. `discord-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `discord`. It goes red if the `import './discord.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/discord` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
## Credentials
|
||||
|
||||
Discord app setup is human and interactive — no parser can click through the
|
||||
Discord Developer Portal. The adapter is installed and registered, but it can't
|
||||
receive a message until the bot exists, has Message Content Intent, and shares a
|
||||
server with you. Tell the user:
|
||||
### Create Discord Bot
|
||||
|
||||
```nc:operator
|
||||
Create the Discord bot:
|
||||
1. Go to https://discord.com/developers/applications → New Application. Name it (e.g. "NanoClaw Assistant").
|
||||
2. Bot tab → Add Bot if needed → Reset Token, then copy the Bot Token (it's shown only once).
|
||||
3. Bot tab → Privileged Gateway Intents → enable Message Content Intent.
|
||||
4. OAuth2 → URL Generator → Scopes: bot; Bot Permissions: Send Messages, Read Message History, Add Reactions, Attach Files, Use Slash Commands.
|
||||
5. Open the generated URL and invite the bot to a server you're also in (a personal server is fine) — the bot can only DM you once you share a server.
|
||||
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
|
||||
2. Click **New Application** and give it a name (e.g., "NanoClaw Assistant")
|
||||
3. From the **General Information** tab, copy the **Application ID** and **Public Key**
|
||||
4. Go to the **Bot** tab and click **Add Bot** if needed
|
||||
5. Copy the Bot Token (click **Reset Token** if you need a new one — you can only see it once)
|
||||
6. Under **Privileged Gateway Intents**, enable **Message Content Intent**
|
||||
7. Go to **OAuth2** > **URL Generator**:
|
||||
- Scopes: select `bot`
|
||||
- Bot Permissions: select `Send Messages`, `Read Message History`, `Add Reactions`, `Attach Files`, `Use Slash Commands`
|
||||
8. Copy the generated URL and open it in your browser to invite the bot to your server
|
||||
|
||||
### Configure environment
|
||||
|
||||
All three values are required — the adapter will fail to start without `DISCORD_PUBLIC_KEY` and `DISCORD_APPLICATION_ID`.
|
||||
|
||||
Add to `.env`:
|
||||
|
||||
```bash
|
||||
DISCORD_BOT_TOKEN=your-bot-token
|
||||
DISCORD_APPLICATION_ID=your-application-id
|
||||
DISCORD_PUBLIC_KEY=your-public-key
|
||||
```
|
||||
|
||||
Paste the Bot Token (it's shown only once). You don't paste the Application ID or
|
||||
the Public Key by hand — the bot's own application record carries both, so a
|
||||
single call derives them from the token:
|
||||
|
||||
```nc:prompt bot_token secret validate:^[A-Za-z0-9._-]{50,}$
|
||||
Paste the Bot Token — Bot tab. Click `Reset Token` if you need a new one.
|
||||
```
|
||||
|
||||
Read the application's own record. `GET /oauth2/applications/@me` returns the
|
||||
Application ID (`id`), the Public Key (`verify_key`), and your own account as the
|
||||
app's owner (`owner.id`) — so the App ID, the Public Key, and your Discord user ID
|
||||
all come from this one call instead of being copied by hand. A bad token fails
|
||||
here, before the restart, rather than silently later:
|
||||
|
||||
```nc:run capture:application_id=.id,public_key=.verify_key,owner_handle=.owner.id effect:fetch
|
||||
curl -sf https://discord.com/api/v10/oauth2/applications/@me -H "Authorization: Bot {{bot_token}}"
|
||||
```
|
||||
|
||||
Store the token and the two derived credentials — the adapter reads them from
|
||||
`.env` and fails to start without `DISCORD_PUBLIC_KEY` and `DISCORD_APPLICATION_ID`
|
||||
(set-if-absent, so a value you've already filled in is never overwritten):
|
||||
|
||||
```nc:env-set
|
||||
DISCORD_BOT_TOKEN={{bot_token}}
|
||||
DISCORD_APPLICATION_ID={{application_id}}
|
||||
DISCORD_PUBLIC_KEY={{public_key}}
|
||||
```
|
||||
## Restart
|
||||
|
||||
Restart the service so it loads the Discord adapter and the credentials you just
|
||||
stored, and wait for its CLI socket before resolving:
|
||||
|
||||
```nc:run effect:restart
|
||||
bash setup/lib/restart.sh
|
||||
```
|
||||
|
||||
## Invite the bot to a shared server
|
||||
|
||||
The bot can only DM you once it shares a server with you. If you didn't already
|
||||
invite it via the OAuth2 URL Generator while setting up the app, do it now: add
|
||||
the bot to a server you're also in (a personal server is fine). Tell the user:
|
||||
|
||||
```nc:operator
|
||||
Open the invite link — https://discord.com/oauth2/authorize?client_id={{application_id}}&scope=bot&permissions=2147584064 — and add the bot to a server you're also in (a personal server works fine); the bot can only DM you once you share a server. If you already invited it while setting up the app, you can skip this.
|
||||
```
|
||||
|
||||
## Resolve your DM channel
|
||||
|
||||
The agent talks to you in your direct-message channel with the bot. Your Discord
|
||||
user ID was already derived as the application's owner (`owner_handle`), so all
|
||||
that's left is to open the DM and read back its channel id.
|
||||
|
||||
Open the DM with `POST /users/@me/channels` and take the channel id it returns as
|
||||
the conversation address `discord:@me:<channelId>` (if Discord refuses, the bot
|
||||
doesn't share a server with you yet — invite it, then retry):
|
||||
|
||||
```nc:run capture:platform_id effect:fetch
|
||||
curl -s -X POST https://discord.com/api/v10/users/@me/channels -H "Authorization: Bot {{bot_token}}" -H "Content-Type: application/json" -d '{"recipient_id":"{{owner_handle}}"}' | jq -er '"discord:@me:" + .id'
|
||||
```
|
||||
|
||||
`owner_handle` and `platform_id` are what the owner-wiring step needs. The
|
||||
greeting goes out over the DM channel, which works as soon as the bot shares a
|
||||
server with you.
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now. Otherwise wire
|
||||
this channel with `/init-first-agent` (or `/manage-channels`).
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
- **type**: `discord`
|
||||
- **terminology**: Discord has "servers" (also called "guilds") containing "channels." Text channels start with #. The bot can also receive direct messages.
|
||||
- **platform-id-format**: `discord:@me:{dmChannelId}` for the owner DM (e.g. `discord:@me:1399...`), `discord:{guildId}:{channelId}` for server channels — both IDs required for channels.
|
||||
- **how-to-find-id**: Enable Developer Mode in Discord (Settings > App Settings > Advanced > Developer Mode). Then right-click a server and select "Copy Server ID" for the guild ID, and right-click the text channel and select "Copy Channel ID." The platform ID format used in registration is `discord:{guildId}:{channelId}` — both IDs are required.
|
||||
- **supports-threads**: yes
|
||||
- **typical-use**: Interactive chat — server channels or direct messages
|
||||
|
||||
@@ -54,8 +54,10 @@ Remove the NanoClaw block from your Emacs config (`config.el`, `~/.spacemacs`, o
|
||||
|
||||
Reload your config or restart Emacs.
|
||||
|
||||
## 5. Messaging group (left intact)
|
||||
## 5. Remove the messaging group (optional)
|
||||
|
||||
Your wired messaging group and conversation history are **not** removed — you
|
||||
created them at runtime, not this skill's install. To purge them deliberately,
|
||||
delete them yourself with `ncl messaging-groups delete <id>`.
|
||||
To clean up the wired messaging group:
|
||||
|
||||
```bash
|
||||
pnpm exec tsx scripts/q.ts data/v2.db "DELETE FROM messaging_group_agents WHERE messaging_group_id IN (SELECT id FROM messaging_groups WHERE channel_type='emacs'); DELETE FROM messaging_groups WHERE channel_type='emacs';"
|
||||
```
|
||||
|
||||
@@ -12,13 +12,14 @@ ncl groups config remove-mcp-server --id <group-id> --name calendar
|
||||
|
||||
## 2. Remove the `.calendar-mcp` mount from the DB (per group)
|
||||
|
||||
This is a **host-only / operator** verb — run it host-side. It's idempotent (a no-op if the mount is absent):
|
||||
There is no `ncl groups config remove-mount` verb yet (tracked in [#2395](https://github.com/nanocoai/nanoclaw/issues/2395)). Until it ships, drop the entry via the in-tree wrapper (`scripts/q.ts`):
|
||||
|
||||
```bash
|
||||
ncl groups config remove-mount \
|
||||
--id <group-id> \
|
||||
--host "$HOME/.calendar-mcp" \
|
||||
--container .calendar-mcp
|
||||
pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
|
||||
SET additional_mounts = (SELECT json_group_array(value) FROM json_each(additional_mounts) \
|
||||
WHERE json_extract(value, '\$.containerPath') != '.calendar-mcp'), \
|
||||
updated_at = datetime('now') \
|
||||
WHERE agent_group_id = '<group-id>';"
|
||||
```
|
||||
|
||||
## 3. Delete the copied test file
|
||||
|
||||
@@ -133,8 +133,6 @@ pnpm exec vitest run src/gcal-dockerfile.test.ts
|
||||
|
||||
`cp` overwrites in place, so re-running this skill is safe.
|
||||
|
||||
**This is the skill's only in-tree integration test.** The Phase 3 `ncl groups config add-mcp-server` and `add-mount` steps are runtime writes to the central DB — they leave no line in the source tree whose deletion a test could catch, so a registration test is structurally inapplicable. They're verified at runtime instead (Phase 5).
|
||||
|
||||
### Rebuild the container image
|
||||
|
||||
```bash
|
||||
@@ -162,22 +160,27 @@ Approval behaviour depends on where you run it: from inside an agent's container
|
||||
|
||||
### Add the `.calendar-mcp` mount
|
||||
|
||||
This is a **host-only / operator** verb — it's rejected from inside a container at any `cli_scope`, so run it host-side when you (the operator) apply this skill via `/setup`, `/customize`, or `/manage-mounts`. It's idempotent (skips if the mount is already present).
|
||||
There is no `ncl groups config add-mount` verb yet (tracked in [#2395](https://github.com/nanocoai/nanoclaw/issues/2395)). Until that ships, edit the DB directly via the in-tree wrapper (`scripts/q.ts` — `setup/verify.ts:5` codifies that NanoClaw avoids depending on the `sqlite3` CLI binary, so don't shell out to it):
|
||||
|
||||
```bash
|
||||
ncl groups config add-mount \
|
||||
--id <group-id> \
|
||||
--host "$HOME/.calendar-mcp" \
|
||||
--container .calendar-mcp
|
||||
GROUP_ID='<group-id>'
|
||||
HOST_PATH="$HOME/.calendar-mcp"
|
||||
MOUNT=$(jq -cn --arg h "$HOST_PATH" '{hostPath:$h, containerPath:".calendar-mcp", readonly:false}')
|
||||
pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
|
||||
SET additional_mounts = json_insert(additional_mounts, '\$[#]', json('$MOUNT')), \
|
||||
updated_at = datetime('now') \
|
||||
WHERE agent_group_id = '$GROUP_ID';"
|
||||
```
|
||||
|
||||
`--container` is relative (mount-security rejects absolute paths — additional mounts land at `/workspace/extra/<relative>`). No `--ro`: the MCP server may rewrite `credentials.json` on token refresh, so the mount must be read-write.
|
||||
Run from your NanoClaw project root (where `data/v2.db` lives). The `$[#]` placeholder is SQLite JSON1's append-to-end notation; it's `\$`-escaped so bash doesn't arithmetic-expand it before sqlite sees it. `updated_at` is ISO-string everywhere else in the schema, so use `datetime('now')` — not `strftime('%s','now')`, which would silently mix epoch ints into a column of YYYY-MM-DD HH:MM:SS strings.
|
||||
|
||||
The mount also needs to be in the external mount allowlist (`~/.config/nanoclaw/mount-allowlist.json`) to take effect at spawn — see the Phase 1 "Verify mount allowlist covers the path" step. A container restart (`ncl groups restart`) is needed for the mount to apply.
|
||||
**Switch to `ncl groups config add-mount` once #2395 lands.** Update this skill at that time.
|
||||
|
||||
`containerPath` is relative (mount-security rejects absolute paths — additional mounts land at `/workspace/extra/<relative>`).
|
||||
|
||||
**Why this can't be `groups/<folder>/container.json`:** post-migration `014-container-configs`, `materializeContainerJson` in `src/container-config.ts` rewrites that file from the DB on every spawn. Anything hand-edited there is silently overwritten on next restart.
|
||||
|
||||
**Same-group-as-gmail tip:** if this group already has the gmail MCP + `.gmail-mcp` mount, both coexist — `ncl groups config add-mcp-server` only updates the named entry, and `add-mount` appends to `additional_mounts` without disturbing existing entries.
|
||||
**Same-group-as-gmail tip:** if this group already has the gmail MCP + `.gmail-mcp` mount, both coexist — `ncl groups config add-mcp-server` only updates the named entry, and `json_insert` appends to `additional_mounts` without disturbing existing entries.
|
||||
|
||||
## Phase 4: Build and Restart
|
||||
|
||||
|
||||
@@ -5,70 +5,63 @@ description: Add Google Chat channel integration via Chat SDK.
|
||||
|
||||
# Add Google Chat Channel
|
||||
|
||||
Adds Google Chat support via the Chat SDK bridge. NanoClaw doesn't ship channels
|
||||
in trunk — this skill copies the Google Chat adapter in from the `channels`
|
||||
branch.
|
||||
Adds Google Chat support via the Chat SDK bridge.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent
|
||||
reads the prose and applies them, and a parser can apply them deterministically
|
||||
from the same document. Every directive is idempotent, so the whole skill is
|
||||
safe to re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
## Apply
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the Google Chat adapter in from the `channels` branch.
|
||||
|
||||
### 1. Copy the adapter and its registration test
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the Google Chat adapter and its
|
||||
registration test into `src/channels/` (overwrite — the branch is canonical):
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/gchat.ts
|
||||
src/channels/gchat-registration.test.ts
|
||||
- `src/channels/gchat.ts` exists
|
||||
- `src/channels/gchat-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './gchat.js';`
|
||||
- `@chat-adapter/gchat` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/gchat.ts > src/channels/gchat.ts
|
||||
git show origin/channels:src/channels/gchat-registration.test.ts > src/channels/gchat-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './gchat.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
@chat-adapter/gchat@4.29.0
|
||||
```bash
|
||||
pnpm install @chat-adapter/gchat@4.29.0
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Build and validate
|
||||
|
||||
Build first: it guards the typed `createChatSdkBridge(...)` core call and proves
|
||||
the dependency is installed. Then run the one integration test.
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/gchat-registration.test.ts
|
||||
```
|
||||
|
||||
`gchat-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `gchat`. It goes red if the import line is deleted or drifts,
|
||||
if the barrel fails to evaluate, or if `@chat-adapter/gchat` isn't installed (the
|
||||
import throws) — so it also covers the dependency from step 3. End-to-end
|
||||
delivery against a real Google Chat space is verified manually once the service
|
||||
runs — see Credentials and Next Steps.
|
||||
Both must be clean before proceeding. `gchat-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `gchat`. It goes red if the `import './gchat.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/gchat` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
End-to-end message delivery against a real Google Chat space is verified manually once the service is running — see Next Steps and the webhook setup above.
|
||||
|
||||
## Credentials
|
||||
|
||||
Google Cloud setup is human and interactive — these steps are prose, not
|
||||
directives (no parser can click through the Google Cloud Console). A recipe
|
||||
rebuild produces a compiling, registered adapter that cannot receive a message
|
||||
until they're done.
|
||||
|
||||
> 1. Go to [Google Cloud Console](https://console.cloud.google.com)
|
||||
> 2. Create or select a project
|
||||
> 3. Enable the **Google Chat API**
|
||||
@@ -80,32 +73,21 @@ until they're done.
|
||||
> - Grant the Chat Bot role
|
||||
> - Create a JSON key and download it
|
||||
|
||||
### Store the credentials
|
||||
### Configure environment
|
||||
|
||||
Capture the service account JSON, then write it. `prompt` only *asks* and binds
|
||||
the answer to a name; a separate directive consumes it — so the same prompt
|
||||
could feed `ncl` or the OneCLI vault instead of `.env` by swapping only the
|
||||
consumer. Here it goes to `.env` (set-if-absent — a value you've already filled
|
||||
in is never overwritten) as a single-line string:
|
||||
Add the service account JSON as a single-line string to `.env`:
|
||||
|
||||
```nc:prompt gchat_credentials secret
|
||||
Paste the service account JSON as a single line — the key file you downloaded, e.g. `{"type":"service_account","project_id":"...","private_key":"...","client_email":"..."}`.
|
||||
```bash
|
||||
GCHAT_CREDENTIALS={"type":"service_account","project_id":"...","private_key":"...","client_email":"..."}
|
||||
```
|
||||
```nc:env-set
|
||||
GCHAT_CREDENTIALS={{gchat_credentials}}
|
||||
```
|
||||
### Webhook server
|
||||
|
||||
The Chat SDK bridge automatically starts a shared webhook server on port 3000
|
||||
(`WEBHOOK_PORT` to change it), handling `/webhook/gchat`. This port must be
|
||||
publicly reachable for Google Chat to deliver events — it's the HTTP endpoint
|
||||
URL you set in the Connection settings above. Running locally, expose it with
|
||||
ngrok (`ngrok http 3000`), a Cloudflare Tunnel, or a reverse proxy on a VPS.
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now. Otherwise run
|
||||
`/manage-channels` to wire this channel to an agent group.
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
@@ -115,5 +97,3 @@ If you're in the middle of `/setup`, return to the setup flow now. Otherwise run
|
||||
- **supports-threads**: yes
|
||||
- **typical-use**: Interactive chat — team spaces or direct messages
|
||||
- **default-isolation**: Same agent group for spaces where you're the primary user. Separate agent group for spaces with different teams or sensitive contexts.
|
||||
</content>
|
||||
</invoke>
|
||||
|
||||
@@ -5,68 +5,64 @@ description: Add GitHub channel integration via Chat SDK. PR and issue comment t
|
||||
|
||||
# Add GitHub Channel
|
||||
|
||||
Adds GitHub support via the Chat SDK bridge. The agent participates in PR and
|
||||
issue comment threads. NanoClaw doesn't ship channels in trunk — this skill
|
||||
copies the GitHub adapter in from the `channels` branch.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent
|
||||
reads the prose and applies them, and a parser can apply them deterministically
|
||||
from the same document. Every directive is idempotent, so the whole skill is
|
||||
safe to re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
Adds GitHub support via the Chat SDK bridge. The agent participates in PR and issue comment threads.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You need a **dedicated GitHub bot account** (not your personal account). The adapter uses this account to post replies and filters out its own messages to avoid loops. Create a free GitHub account for your bot (e.g. `my-org-bot`), then invite it as a collaborator with write access to the repos you want monitored.
|
||||
|
||||
## Apply
|
||||
## Install
|
||||
|
||||
### 1. Copy the adapter
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the GitHub adapter in from the `channels` branch.
|
||||
|
||||
Fetch the `channels` branch and copy the GitHub adapter into `src/channels/`
|
||||
(overwrite — the branch is canonical):
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/github.ts
|
||||
src/channels/github-registration.test.ts
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
- `src/channels/github.ts` exists
|
||||
- `src/channels/github-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './github.js';`
|
||||
- `@chat-adapter/github` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/github.ts > src/channels/github.ts
|
||||
git show origin/channels:src/channels/github-registration.test.ts > src/channels/github-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './github.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
@chat-adapter/github@4.29.0
|
||||
```bash
|
||||
pnpm install @chat-adapter/github@4.29.0
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Build and validate
|
||||
|
||||
The build guards the typed `createChatSdkBridge(...)` core call and proves the
|
||||
dependency is installed (the adapter import throws if `@chat-adapter/github`
|
||||
isn't present):
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/github-registration.test.ts
|
||||
```
|
||||
|
||||
`github-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `github`. It goes red if the import line is deleted or drifts,
|
||||
if the barrel fails to evaluate, or if `@chat-adapter/github` isn't installed
|
||||
(the import throws) — so it also covers the dependency from step 3.
|
||||
Both must be clean before proceeding. `github-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `github`. It goes red if the `import './github.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/github` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
End-to-end message delivery against a real GitHub repo is verified manually once
|
||||
the service is running — see Next Steps and the webhook setup below.
|
||||
End-to-end message delivery against a real GitHub repo is verified manually once the service is running — see Next Steps and the webhook setup above.
|
||||
|
||||
## Credentials
|
||||
|
||||
@@ -92,28 +88,18 @@ On each repo (logged in as the repo owner/admin):
|
||||
|
||||
### 3. Configure environment
|
||||
|
||||
Capture the three values, then write them. `prompt` only *asks* and binds the
|
||||
answer to a name; a separate directive consumes it — so the same prompts could
|
||||
feed `ncl` or the OneCLI vault instead of `.env` by swapping only the consumer.
|
||||
Here they go to `.env` (set-if-absent — a value you've already filled in is
|
||||
never overwritten):
|
||||
Add to `.env`:
|
||||
|
||||
```nc:prompt github_token secret
|
||||
Paste the Fine-grained Personal Access Token for the bot account — starts with `github_pat_`.
|
||||
```
|
||||
```nc:prompt webhook_secret secret
|
||||
Paste the webhook secret you generated for the repo webhook(s).
|
||||
```
|
||||
```nc:prompt bot_username
|
||||
Enter the bot account's GitHub username exactly (used for @-mention detection).
|
||||
```
|
||||
```nc:env-set
|
||||
GITHUB_TOKEN={{github_token}}
|
||||
GITHUB_WEBHOOK_SECRET={{webhook_secret}}
|
||||
GITHUB_BOT_USERNAME={{bot_username}}
|
||||
```bash
|
||||
GITHUB_TOKEN=github_pat_...
|
||||
GITHUB_WEBHOOK_SECRET=your-webhook-secret
|
||||
GITHUB_BOT_USERNAME=your-bot-username
|
||||
```
|
||||
|
||||
`GITHUB_BOT_USERNAME` must match the bot account's GitHub username exactly. This is used for @-mention detection — the agent responds when someone writes `@your-bot-username` in a PR or issue comment.
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
## Wiring
|
||||
|
||||
Ask the user: **Is this a private or public repo?**
|
||||
|
||||
@@ -19,17 +19,17 @@ ncl groups config remove-mcp-server --id <group-id> --name gmail
|
||||
|
||||
## 3. Remove the `.gmail-mcp` mount (per group)
|
||||
|
||||
Remove the mount with the host-only `ncl groups config remove-mount` verb (operator-only; rejected from inside a container). For each group that had Gmail wired:
|
||||
There is no `ncl groups config remove-mount` verb yet ([#2395](https://github.com/nanocoai/nanoclaw/issues/2395)). Edit the central DB via the in-tree wrapper (`scripts/q.ts` — NanoClaw avoids depending on the `sqlite3` CLI, `setup/verify.ts:5`). Run from your NanoClaw project root (where `data/v2.db` lives):
|
||||
|
||||
```bash
|
||||
ncl groups config remove-mount \
|
||||
--id <group-id> \
|
||||
--host "$HOME/.gmail-mcp" \
|
||||
--container .gmail-mcp
|
||||
GROUP_ID='<group-id>'
|
||||
pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
|
||||
SET additional_mounts = (SELECT json_group_array(value) FROM json_each(additional_mounts) \
|
||||
WHERE json_extract(value, '\$.containerPath') != '.gmail-mcp'), \
|
||||
updated_at = datetime('now') \
|
||||
WHERE agent_group_id = '$GROUP_ID';"
|
||||
```
|
||||
|
||||
The verb is idempotent — a no-op if the mount is already absent.
|
||||
|
||||
## 4. Remove the Dockerfile install
|
||||
|
||||
In `container/Dockerfile`, delete the `ARG GMAIL_MCP_VERSION=...` line and the `pnpm install -g` `RUN` block that installs `@gongrzhe/server-gmail-autoauth-mcp` and `zod-to-json-schema`.
|
||||
|
||||
@@ -181,16 +181,21 @@ Approval behaviour depends on where you run it: from inside an agent's container
|
||||
|
||||
### Add the `.gmail-mcp` mount
|
||||
|
||||
Register the mount with the host-only `ncl groups config add-mount` verb. For each chosen `<group-id>`:
|
||||
There is no `ncl groups config add-mount` verb yet (tracked in [#2395](https://github.com/nanocoai/nanoclaw/issues/2395)). Until that ships, edit the DB directly via the in-tree wrapper (`scripts/q.ts` — `setup/verify.ts:5` codifies that NanoClaw avoids depending on the `sqlite3` CLI binary, so don't shell out to it):
|
||||
|
||||
```bash
|
||||
ncl groups config add-mount \
|
||||
--id <group-id> \
|
||||
--host "$HOME/.gmail-mcp" \
|
||||
--container .gmail-mcp
|
||||
GROUP_ID='<group-id>'
|
||||
HOST_PATH="$HOME/.gmail-mcp"
|
||||
MOUNT=$(jq -cn --arg h "$HOST_PATH" '{hostPath:$h, containerPath:".gmail-mcp", readonly:false}')
|
||||
pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
|
||||
SET additional_mounts = json_insert(additional_mounts, '\$[#]', json('$MOUNT')), \
|
||||
updated_at = datetime('now') \
|
||||
WHERE agent_group_id = '$GROUP_ID';"
|
||||
```
|
||||
|
||||
`--host` is the host path, `--container` is the in-container path (relative, lands at `/workspace/extra/.gmail-mcp`). No `--ro` — the MCP server writes refreshed token state back into the mount. The verb is idempotent (a re-run skips if the mount is already present) and operator-only (host-side; rejected from inside a container), so run it from a host operator shell when applying this skill.
|
||||
Run from your NanoClaw project root (where `data/v2.db` lives). The `$[#]` placeholder is SQLite JSON1's append-to-end notation; it's `\$`-escaped so bash doesn't arithmetic-expand it before sqlite sees it. `updated_at` is ISO-string everywhere else in the schema, so use `datetime('now')` — not `strftime('%s','now')`, which would silently mix epoch ints into a column of YYYY-MM-DD HH:MM:SS strings.
|
||||
|
||||
**Switch to `ncl groups config add-mount` once #2395 lands.** Update this skill at that time.
|
||||
|
||||
**Why the container path is relative:** `mount-security` rejects absolute `containerPath` values. Additional mounts are prefixed with `/workspace/extra/`, so `containerPath: ".gmail-mcp"` lands at `/workspace/extra/.gmail-mcp`. The MCP server's `GMAIL_OAUTH_PATH` / `GMAIL_CREDENTIALS_PATH` env vars point at that absolute location inside the container.
|
||||
|
||||
|
||||
@@ -8,9 +8,10 @@
|
||||
* allowedTools: [ ...TOOL_ALLOWLIST, ...Object.keys(this.mcpServers).map(mcpAllowPattern) ]
|
||||
*
|
||||
* `mcpAllowPattern` is not exported and the call site lives inside the SDK query options,
|
||||
* so the derivation is non-invocable from a test — we guard it structurally. Delete or
|
||||
* rename either half (the function or the spread into allowedTools) and this goes red,
|
||||
* surfacing that `gmail` tools would silently be filtered out despite being registered.
|
||||
* so we assert the derivation structurally. Delete or rename the derivation and this goes
|
||||
* red — surfacing that `gmail` tools would silently be filtered out despite being registered.
|
||||
*
|
||||
* `mcpAllowPattern` itself is exercised directly to prove `gmail` -> `mcp__gmail__*`.
|
||||
*/
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
@@ -24,6 +25,11 @@ function source(): { sf: ts.SourceFile; text: string } {
|
||||
return { sf: ts.createSourceFile(p, text, ts.ScriptTarget.Latest, true), text };
|
||||
}
|
||||
|
||||
/** Reimplement the sanitizer the provider applies, to assert the gmail name maps cleanly. */
|
||||
function expectedPattern(name: string): string {
|
||||
return `mcp__${name.replace(/[^a-zA-Z0-9_-]/g, '_')}__*`;
|
||||
}
|
||||
|
||||
describe('claude.ts derives MCP allow-patterns from the registered servers', () => {
|
||||
const { sf, text } = source();
|
||||
|
||||
@@ -42,4 +48,8 @@ describe('claude.ts derives MCP allow-patterns from the registered servers', ()
|
||||
const flat = text.replace(/\s+/g, ' ');
|
||||
expect(flat).toContain('Object.keys(this.mcpServers).map(mcpAllowPattern)');
|
||||
});
|
||||
|
||||
it('maps a gmail server name to mcp__gmail__*', () => {
|
||||
expect(expectedPattern('gmail')).toBe('mcp__gmail__*');
|
||||
});
|
||||
});
|
||||
|
||||
@@ -5,196 +5,110 @@ description: Add iMessage channel integration via Chat SDK. Local (macOS) or rem
|
||||
|
||||
# Add iMessage Channel
|
||||
|
||||
Adds iMessage support via the Chat SDK bridge. Two modes: local (macOS with Full
|
||||
Disk Access) or remote (Photon API). NanoClaw doesn't ship channels in trunk —
|
||||
this skill copies the iMessage adapter in from the `channels` branch.
|
||||
Adds iMessage support via the Chat SDK bridge. Two modes: local (macOS with Full Disk Access) or remote (Photon API).
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent reads
|
||||
the prose and applies them, and a parser can apply them deterministically from
|
||||
the same document. Every directive is idempotent, so the whole skill is safe to
|
||||
re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
## Apply
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the iMessage adapter in from the `channels` branch.
|
||||
|
||||
### 1. Copy the adapter
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the iMessage adapter into `src/channels/`
|
||||
(overwrite — the branch is canonical):
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/imessage.ts
|
||||
src/channels/imessage-registration.test.ts
|
||||
- `src/channels/imessage.ts` exists
|
||||
- `src/channels/imessage-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './imessage.js';`
|
||||
- `chat-adapter-imessage` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/imessage.ts > src/channels/imessage.ts
|
||||
git show origin/channels:src/channels/imessage-registration.test.ts > src/channels/imessage-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './imessage.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
chat-adapter-imessage@0.1.1
|
||||
```bash
|
||||
pnpm install chat-adapter-imessage@0.1.1
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Build and validate
|
||||
|
||||
Build guards the typed `createChatSdkBridge(...)` core call and proves the
|
||||
dependency is installed (the adapter's top-level `import` from
|
||||
`chat-adapter-imessage` throws if it isn't):
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/imessage-registration.test.ts
|
||||
```
|
||||
|
||||
`imessage-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `imessage` — it goes red if the import line is deleted or
|
||||
drifts, if the barrel fails to evaluate, or if `chat-adapter-imessage` isn't
|
||||
installed (the import throws), so it also covers the dependency from step 3.
|
||||
Both must be clean before proceeding. `imessage-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `imessage`. It goes red if the `import './imessage.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `chat-adapter-imessage` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
End-to-end message delivery against a real iMessage account is verified manually
|
||||
once the service is running — see Next Steps.
|
||||
End-to-end message delivery against a real iMessage account is verified manually once the service is running — see Next Steps.
|
||||
|
||||
## Credentials
|
||||
|
||||
iMessage runs in one of two modes:
|
||||
|
||||
- **Local (macOS)** — the bot runs on this Mac and talks via the signed-in
|
||||
iMessage account. Reading `chat.db` needs Full Disk Access granted to the
|
||||
Node binary the host runs under.
|
||||
- **Remote (Photon API)** — the bot talks to a separate Photon server that owns
|
||||
an iMessage account on another Mac. Use this off macOS, or to keep this Mac's
|
||||
chat history out of the loop.
|
||||
|
||||
Mode choice and the Full Disk Access / Photon walkthroughs are human and
|
||||
interactive. Pick the mode first (local is the macOS default; remote is the only
|
||||
option off macOS), then walk only that mode's setup — the other mode's steps are
|
||||
skipped:
|
||||
|
||||
```nc:prompt mode validate:^(local|remote)$
|
||||
How should iMessage run — `local` (this Mac, needs Full Disk Access) or `remote` (a Photon server)?
|
||||
```
|
||||
|
||||
### Local Mode (macOS)
|
||||
|
||||
Requirements: macOS, with Full Disk Access granted to the Node binary. Without
|
||||
it the adapter can't read `chat.db` and inbound messages never arrive.
|
||||
Requirements: macOS with Full Disk Access granted to the Node.js binary.
|
||||
|
||||
Local mode only works on a Mac — it reads this machine's iMessage `chat.db`
|
||||
directly, and there is no such database off macOS. On any other OS, stop here and
|
||||
use remote (Photon) mode instead; otherwise you'd write a local config that can
|
||||
never receive a message:
|
||||
The Node binary path is buried deep (e.g. `~/.nvm/versions/node/v22.x.x/bin/node`). To make it easy, open the folder in Finder so the user can drag the file into System Settings:
|
||||
|
||||
```nc:run effect:check when:mode=local
|
||||
[ "$(uname)" = Darwin ]
|
||||
```
|
||||
|
||||
The Node binary path is buried deep (e.g. `~/.nvm/versions/node/v22.x.x/bin/node`),
|
||||
so open its folder in Finder to make the drag-and-drop target obvious. Harmless
|
||||
off a desktop (SSH/headless) — it just no-ops:
|
||||
|
||||
```nc:run effect:external when:mode=local
|
||||
open "$(dirname "$(which node)")" 2>/dev/null || true
|
||||
```bash
|
||||
open "$(dirname "$(which node)")"
|
||||
```
|
||||
|
||||
Then tell the user:
|
||||
|
||||
```nc:operator when:mode=local
|
||||
Grant Full Disk Access to Node so iMessage can read your chat history:
|
||||
1. Open System Settings > Privacy & Security > Full Disk Access.
|
||||
2. Click +, then drag the "node" file from the Finder window that just opened.
|
||||
3. Toggle it on, then come back here.
|
||||
```
|
||||
1. Open **System Settings** > **Privacy & Security** > **Full Disk Access**
|
||||
2. Click **+**, then drag the `node` file from the Finder window that just opened
|
||||
3. Toggle it on
|
||||
|
||||
Stop and wait for the user to confirm Full Disk Access is granted before
|
||||
continuing.
|
||||
Stop and wait for the user to confirm before continuing.
|
||||
|
||||
### Remote Mode (Photon API)
|
||||
|
||||
Photon is a separate service that owns an iMessage account and exposes it over
|
||||
HTTP; NanoClaw talks to it via its API. Tell the user:
|
||||
|
||||
```nc:operator when:mode=remote
|
||||
Set up remote iMessage via Photon:
|
||||
1. Create a Photon server: https://photon.codes
|
||||
2. Copy the server URL and API key from your Photon dashboard.
|
||||
```
|
||||
|
||||
Then collect the two values:
|
||||
|
||||
```nc:prompt server_url when:mode=remote validate:^https?:// flags:i reuse:IMESSAGE_SERVER_URL
|
||||
Your Photon server URL — starts with http:// or https:// (e.g. https://photon.example.com).
|
||||
```
|
||||
```nc:prompt api_key secret when:mode=remote reuse:IMESSAGE_API_KEY
|
||||
Your Photon API key — from the Photon dashboard.
|
||||
```
|
||||
1. Set up a [Photon](https://photon.codes) account
|
||||
2. Get your server URL and API key
|
||||
|
||||
### Configure environment
|
||||
|
||||
The two modes use different `.env` keys. Write only the keys for the chosen
|
||||
mode, and strip the opposite mode's keys so a stale value can't confuse the
|
||||
adapter's factory. The configure script owns this upsert-and-remove (a plain
|
||||
set-if-absent env write can neither replace a stale value nor delete a key):
|
||||
**Local mode** -- add to `.env`:
|
||||
|
||||
**Local mode** — writes `IMESSAGE_LOCAL=true` and `IMESSAGE_ENABLED=true`, and
|
||||
removes `IMESSAGE_SERVER_URL` / `IMESSAGE_API_KEY` if present:
|
||||
|
||||
```nc:run effect:external when:mode=local
|
||||
bash setup/channels/imessage-configure.sh local
|
||||
```bash
|
||||
IMESSAGE_ENABLED=true
|
||||
IMESSAGE_LOCAL=true
|
||||
```
|
||||
|
||||
**Remote mode** — writes `IMESSAGE_LOCAL=false`, `IMESSAGE_SERVER_URL`, and
|
||||
`IMESSAGE_API_KEY`, and removes `IMESSAGE_ENABLED` if present:
|
||||
**Remote mode** -- add to `.env`:
|
||||
|
||||
```nc:run effect:external when:mode=remote
|
||||
bash setup/channels/imessage-configure.sh remote "{{server_url}}" "{{api_key}}"
|
||||
```bash
|
||||
IMESSAGE_LOCAL=false
|
||||
IMESSAGE_SERVER_URL=https://your-photon-server.com
|
||||
IMESSAGE_API_KEY=your-api-key
|
||||
```
|
||||
|
||||
## Restart
|
||||
|
||||
Restart the service so it loads the iMessage adapter and the credentials you
|
||||
just stored, and wait for its CLI socket before wiring:
|
||||
|
||||
```nc:run effect:restart
|
||||
bash setup/lib/restart.sh
|
||||
```
|
||||
|
||||
## Resolve your iMessage handle
|
||||
|
||||
The agent greets you in the iMessage conversation tied to the phone number or
|
||||
Apple ID email you message from — that handle is both your identity and the
|
||||
conversation address. Resolve it so the owner-wiring step can target it.
|
||||
|
||||
```nc:prompt owner_handle validate:^(\+\d{8,15}|[^\s@]+@[^\s@]+\.[^\s@]+)$
|
||||
The phone number or email you iMessage from — a +E.164 number (e.g. +14155551234) or an email / Apple ID (e.g. you@icloud.com).
|
||||
```
|
||||
|
||||
iMessage is a native adapter: it sends the raw handle as the conversation
|
||||
address, with no channel prefix — so the messaging-group platform id is that
|
||||
handle as-is.
|
||||
|
||||
```nc:run capture:platform_id
|
||||
echo "{{owner_handle}}"
|
||||
```
|
||||
|
||||
`owner_handle` and `platform_id` are what the owner-wiring step needs. The
|
||||
welcome iMessage goes out through the adapter once the service is running — in
|
||||
local mode that needs Full Disk Access granted (above); in remote mode it goes
|
||||
via your Photon server.
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now. Otherwise wire
|
||||
this channel with `/init-first-agent` (or `/manage-channels`).
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
|
||||
@@ -18,7 +18,16 @@ rm -f src/channels/linear.ts src/channels/linear-registration.test.ts
|
||||
|
||||
## 2. Remove credentials
|
||||
|
||||
Remove `LINEAR_CLIENT_ID`, `LINEAR_CLIENT_SECRET`, `LINEAR_API_KEY`, `LINEAR_WEBHOOK_SECRET`, `LINEAR_BOT_USERNAME`, and `LINEAR_TEAM_KEY` from `.env`, then re-sync to the container:
|
||||
Remove the Linear env vars from `.env`, then re-sync to the container:
|
||||
|
||||
```bash
|
||||
LINEAR_CLIENT_ID
|
||||
LINEAR_CLIENT_SECRET
|
||||
LINEAR_API_KEY
|
||||
LINEAR_WEBHOOK_SECRET
|
||||
LINEAR_BOT_USERNAME
|
||||
LINEAR_TEAM_KEY
|
||||
```
|
||||
|
||||
```bash
|
||||
mkdir -p data/env && cp .env data/env/env
|
||||
|
||||
@@ -5,15 +5,7 @@ description: Add Linear channel integration via Chat SDK. Issue comment threads
|
||||
|
||||
# Add Linear Channel
|
||||
|
||||
Adds Linear support via the Chat SDK bridge. The agent participates in issue
|
||||
comment threads. Every comment on a Linear issue triggers the agent — no
|
||||
@-mention needed. NanoClaw doesn't ship channels in trunk — this skill copies the
|
||||
Linear adapter in from the `channels` branch.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent reads
|
||||
the prose and applies them, and a parser can apply them deterministically from
|
||||
the same document. Every directive is idempotent, so the whole skill is safe to
|
||||
re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
Adds Linear support via the Chat SDK bridge. The agent participates in issue comment threads. Every comment on a Linear issue triggers the agent — no @-mention needed.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -28,65 +20,61 @@ re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
|
||||
**Alternative:** Use a Personal API Key (`LINEAR_API_KEY`) for simpler setup. The agent will post as you, and your own comments will be filtered (other team members' comments still work).
|
||||
|
||||
## Apply
|
||||
## Install
|
||||
|
||||
Linear OAuth apps post and read comments under an app identity that can't be
|
||||
@-mentioned, so when you wire the channel in `/manage-channels`, pick an engage
|
||||
mode that responds to plain comments rather than mention-only.
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the Linear adapter in from the `channels` branch and wires it into the channel registry. Linear OAuth apps post and read comments under an app identity that can't be @-mentioned, so when you wire the channel in `/manage-channels`, pick an engage mode that responds to plain comments rather than mention-only.
|
||||
|
||||
### 1. Copy the adapter and its registration test
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the Linear adapter and its registration
|
||||
test into `src/channels/` (overwrite — the branch is canonical):
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/linear.ts
|
||||
src/channels/linear-registration.test.ts
|
||||
- `src/channels/linear.ts` exists
|
||||
- `src/channels/linear-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './linear.js';`
|
||||
- `@chat-adapter/linear` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into the channel
|
||||
registry:
|
||||
```bash
|
||||
git show origin/channels:src/channels/linear.ts > src/channels/linear.ts
|
||||
git show origin/channels:src/channels/linear-registration.test.ts > src/channels/linear-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './linear.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
@chat-adapter/linear@4.29.0
|
||||
```bash
|
||||
pnpm install @chat-adapter/linear@4.29.0
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Build and validate
|
||||
|
||||
Build first: it guards the typed `createChatSdkBridge(...)` core call and proves
|
||||
the dependency is installed. Then run the one integration test.
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/linear-registration.test.ts
|
||||
```
|
||||
|
||||
Both must be clean before proceeding. `linear-registration.test.ts` imports the
|
||||
real channel barrel and asserts the registry contains `linear`. It goes red if
|
||||
the `import './linear.js';` line is deleted or drifts, if the barrel fails to
|
||||
evaluate, or if `@chat-adapter/linear` isn't installed (the import throws) — so
|
||||
it also covers the dependency from step 3. End-to-end message delivery against a
|
||||
real Linear workspace is verified manually once the service is running — see
|
||||
Wiring and Next Steps.
|
||||
Both must be clean before proceeding. `linear-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `linear`. It goes red if the `import './linear.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/linear` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
End-to-end message delivery against a real Linear workspace is verified manually once the service is running — see Wiring and Next Steps.
|
||||
|
||||
## Credentials
|
||||
|
||||
Linear app and webhook setup is human and interactive — these steps are prose
|
||||
(no parser can click through the Linear UI), except the final env write.
|
||||
|
||||
### 1. Set up a webhook
|
||||
|
||||
1. Go to **Linear Settings** > **API** > **Webhooks** > **New webhook**
|
||||
@@ -98,68 +86,48 @@ Linear app and webhook setup is human and interactive — these steps are prose
|
||||
|
||||
Note: Linear webhook delivery may be delayed 1-5 minutes for new webhooks. This is normal.
|
||||
|
||||
### 2. Store the credentials
|
||||
### 2. Configure environment
|
||||
|
||||
Capture the values, then write them. `prompt` only *asks* and binds the answer
|
||||
to a name; a separate directive consumes it. Here they go to `.env`
|
||||
(set-if-absent — a value you've already filled in is never overwritten) and sync
|
||||
to the container.
|
||||
|
||||
Use **either** the OAuth app credentials (recommended) **or** a Personal API key.
|
||||
For the API-key path, paste `none` at the OAuth prompts and set `LINEAR_API_KEY`
|
||||
in `.env` by hand (commented in the template below). `LINEAR_BOT_USERNAME` is the
|
||||
display name for the bot, used for self-message detection when using a Personal
|
||||
API Key. `LINEAR_TEAM_KEY` is the Linear team key (e.g. `ENG`, `NAN`) — find it
|
||||
in Linear under Settings > Teams; all issues in this team route to one messaging
|
||||
group.
|
||||
|
||||
```nc:prompt linear_client_id secret
|
||||
Paste the OAuth Client ID — Linear Settings > API > OAuth Applications. Paste `none` if using a Personal API key instead.
|
||||
```
|
||||
```nc:prompt linear_client_secret secret
|
||||
Paste the OAuth Client Secret. Paste `none` if using a Personal API key instead.
|
||||
```
|
||||
```nc:prompt linear_webhook_secret secret
|
||||
Paste the webhook signing secret from the webhook you just created.
|
||||
```
|
||||
```nc:prompt linear_team_key
|
||||
Enter the Linear team key (e.g. `ENG`, `NAN`) — Settings > Teams.
|
||||
```
|
||||
```nc:prompt linear_bot_username
|
||||
Enter the bot display name (e.g. `NanoClaw Bot`).
|
||||
```
|
||||
```nc:env-set
|
||||
LINEAR_CLIENT_ID={{linear_client_id}}
|
||||
LINEAR_CLIENT_SECRET={{linear_client_secret}}
|
||||
LINEAR_WEBHOOK_SECRET={{linear_webhook_secret}}
|
||||
LINEAR_TEAM_KEY={{linear_team_key}}
|
||||
LINEAR_BOT_USERNAME={{linear_bot_username}}
|
||||
```
|
||||
If you went the Personal API key route, add this line to `.env` instead of the
|
||||
OAuth pair (agent posts as you, your own comments are filtered):
|
||||
Add to `.env`:
|
||||
|
||||
```bash
|
||||
LINEAR_API_KEY=lin_api_...
|
||||
# OAuth app (recommended)
|
||||
LINEAR_CLIENT_ID=your-client-id
|
||||
LINEAR_CLIENT_SECRET=your-client-secret
|
||||
|
||||
# OR Personal API key (simpler, but agent posts as you)
|
||||
# LINEAR_API_KEY=lin_api_...
|
||||
|
||||
LINEAR_WEBHOOK_SECRET=your-webhook-signing-secret
|
||||
LINEAR_BOT_USERNAME=NanoClaw Bot
|
||||
LINEAR_TEAM_KEY=ENG
|
||||
```
|
||||
|
||||
- `LINEAR_BOT_USERNAME`: display name for the bot (used for self-message detection when using a Personal API Key)
|
||||
- `LINEAR_TEAM_KEY`: the Linear team key (e.g. `ENG`, `NAN`). Find it in Linear under Settings > Teams. All issues in this team route to one messaging group.
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
## Wiring
|
||||
|
||||
Linear is team-routed: the assistant watches one team and answers *every* comment
|
||||
on its issues (it can't be @-mentioned). Wire the team you set up to an agent —
|
||||
pick which one should answer (`ncl groups list` shows their folders):
|
||||
Ask the user: **Is this a private or public Linear workspace?**
|
||||
|
||||
```nc:prompt agent_folder
|
||||
Which agent should answer Linear comments? Enter its folder (run `ncl groups list`).
|
||||
```
|
||||
```nc:run effect:wire
|
||||
ncl messaging-groups create --channel-type linear --platform-id linear:{{linear_team_key}} --is-group 1 --unknown-sender-policy public --name {{linear_team_key}}
|
||||
ncl wirings create --channel-type linear --platform-id linear:{{linear_team_key}} --agent-group {{agent_folder}} --engage-mode pattern --engage-pattern . --session-mode per-thread
|
||||
- **Private workspace** — use `unknown_sender_policy: 'public'`. Only workspace members can comment.
|
||||
- **Public workspace** — use `unknown_sender_policy: 'strict'` and add trusted members (see GitHub skill for member registration example).
|
||||
|
||||
Run `/manage-channels` to wire the Linear channel to an agent group, or insert manually:
|
||||
|
||||
```sql
|
||||
-- Create messaging group (one per team)
|
||||
INSERT INTO messaging_groups (id, channel_type, platform_id, instance, name, is_group, unknown_sender_policy, created_at)
|
||||
VALUES ('mg-linear-eng', 'linear', 'linear:ENG', 'linear', 'Engineering', 1, 'public', datetime('now'));
|
||||
|
||||
-- Wire to agent group
|
||||
INSERT INTO messaging_group_agents (id, messaging_group_id, agent_group_id, trigger_rules, response_scope, session_mode, priority, created_at)
|
||||
VALUES ('mga-linear-eng', 'mg-linear-eng', '<your-agent-group-id>', '', 'all', 'per-thread', 10, datetime('now'));
|
||||
```
|
||||
|
||||
Each issue thread becomes its own conversation. There's no welcome — Linear has
|
||||
no direct message, so the assistant greets people when it first answers a comment.
|
||||
For a public-internet workspace, restrict it to people you've registered with
|
||||
`--unknown-sender-policy strict` (see the GitHub skill for adding members).
|
||||
The `platform_id` must be `linear:<TEAM_KEY>` matching the `LINEAR_TEAM_KEY` env var. Use `per-thread` session mode so each issue comment thread gets its own agent session.
|
||||
|
||||
## Next Steps
|
||||
|
||||
|
||||
@@ -18,7 +18,22 @@ rm -f src/channels/matrix.ts src/channels/matrix-registration.test.ts
|
||||
|
||||
## 2. Remove credentials
|
||||
|
||||
Remove the Matrix env vars apply set — `MATRIX_BASE_URL`, `MATRIX_USER_ID`, `MATRIX_BOT_USERNAME`, and whichever auth path you chose (`MATRIX_USERNAME` + `MATRIX_PASSWORD`, or `MATRIX_ACCESS_TOKEN`) — from `.env`, then re-sync to the container:
|
||||
Remove the `MATRIX_*` lines from `.env`:
|
||||
|
||||
```bash
|
||||
MATRIX_BASE_URL
|
||||
MATRIX_USERNAME
|
||||
MATRIX_PASSWORD
|
||||
MATRIX_USER_ID
|
||||
MATRIX_BOT_USERNAME
|
||||
MATRIX_ACCESS_TOKEN
|
||||
MATRIX_INVITE_AUTOJOIN
|
||||
MATRIX_INVITE_AUTOJOIN_ALLOWLIST
|
||||
MATRIX_RECOVERY_KEY
|
||||
MATRIX_DEVICE_ID
|
||||
```
|
||||
|
||||
Then re-sync to the container:
|
||||
|
||||
```bash
|
||||
mkdir -p data/env && cp .env data/env/env
|
||||
|
||||
@@ -5,53 +5,57 @@ description: Add Matrix channel integration via Chat SDK. Works with any Matrix
|
||||
|
||||
# Add Matrix Channel
|
||||
|
||||
Adds Matrix support via the Chat SDK bridge. NanoClaw doesn't ship channels in
|
||||
trunk — this skill copies the Matrix adapter in from the `channels` branch.
|
||||
Adds Matrix support via the Chat SDK bridge.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent
|
||||
reads the prose and applies them, and a parser can apply them deterministically
|
||||
from the same document. Every directive is idempotent, so the whole skill is
|
||||
safe to re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
## Apply
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the Matrix adapter in from the `channels` branch.
|
||||
|
||||
### 1. Copy the adapter
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the Matrix adapter into `src/channels/`
|
||||
(overwrite — the branch is canonical):
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/matrix.ts
|
||||
src/channels/matrix-registration.test.ts
|
||||
- `src/channels/matrix.ts` exists
|
||||
- `src/channels/matrix-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './matrix.js';`
|
||||
- `@beeper/chat-adapter-matrix` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/matrix.ts > src/channels/matrix.ts
|
||||
git show origin/channels:src/channels/matrix-registration.test.ts > src/channels/matrix-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './matrix.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`.
|
||||
The Matrix adapter lives in the `@beeper/` namespace and versions on its own
|
||||
track (not the `@chat-adapter/*` family), so it carries its own pin:
|
||||
|
||||
```nc:dep
|
||||
@beeper/chat-adapter-matrix@0.2.0
|
||||
```bash
|
||||
pnpm install @beeper/chat-adapter-matrix@0.2.0
|
||||
```
|
||||
|
||||
### 4. Patch matrix-js-sdk ESM imports
|
||||
### 5. Patch matrix-js-sdk ESM imports
|
||||
|
||||
The adapter's published dist references `matrix-js-sdk/lib/...` without `.js`
|
||||
extensions, which fails under Node 22 strict ESM resolution. Add the missing
|
||||
extensions (idempotent — safe to re-run). Re-run this after every `pnpm install`
|
||||
that touches the adapter:
|
||||
extensions (idempotent — safe to re-run):
|
||||
|
||||
```nc:run effect:external
|
||||
```bash
|
||||
node -e '
|
||||
const fs = require("fs"), path = require("path");
|
||||
const root = "node_modules/.pnpm";
|
||||
@@ -65,32 +69,22 @@ node -e '
|
||||
'
|
||||
```
|
||||
|
||||
### 5. Build
|
||||
Re-run this after every `pnpm install` that touches the adapter.
|
||||
|
||||
Build guards the typed `createChatSdkBridge(...)` core call the adapter makes
|
||||
and proves the dependency is installed and the ESM patch took. It also fails if
|
||||
the `import './matrix.js';` line is missing or the barrel can't evaluate.
|
||||
### 6. Build and validate
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/matrix-registration.test.ts
|
||||
```
|
||||
|
||||
`matrix-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `matrix`. It goes red if the import line is deleted or drifts,
|
||||
if the barrel fails to evaluate, or if `@beeper/chat-adapter-matrix` isn't
|
||||
installed (the import throws) — so it also covers the dependency from step 3.
|
||||
Both must be clean before proceeding. `matrix-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `matrix`. It goes red if the `import './matrix.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@beeper/chat-adapter-matrix` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
End-to-end message delivery against a real Matrix homeserver is verified
|
||||
manually once the service is running — see Next Steps.
|
||||
End-to-end message delivery against a real Matrix homeserver is verified manually once the service is running — see Next Steps.
|
||||
|
||||
## Credentials
|
||||
|
||||
The bot needs its own Matrix account — separate from the user's account. This is
|
||||
required because Matrix cannot send DMs to yourself. These steps are human and
|
||||
interactive (no parser can click through Element), so they stay prose.
|
||||
The bot needs its own Matrix account — separate from the user's account. This is required because Matrix cannot send DMs to yourself.
|
||||
|
||||
### Create a bot account
|
||||
|
||||
@@ -137,47 +131,12 @@ MATRIX_RECOVERY_KEY=your-recovery-key # Enable E2EE cross-signing
|
||||
MATRIX_DEVICE_ID=NANOCLAW01 # Stable device ID across restarts
|
||||
```
|
||||
|
||||
### Store the credentials
|
||||
### Configure environment
|
||||
|
||||
Capture the values for the auth method you chose, then write them. `prompt` only
|
||||
*asks* and binds the answer to a name; a separate directive consumes it — so the
|
||||
same prompts could feed `ncl` or the OneCLI vault instead of `.env` by swapping
|
||||
only the consumer. The homeserver URL, the bot's user ID, and a display name are
|
||||
shared across both auth methods:
|
||||
Add the chosen env vars to `.env`, then sync:
|
||||
|
||||
```nc:prompt base_url
|
||||
Paste the homeserver base URL, e.g. `https://matrix.org`.
|
||||
```
|
||||
```nc:prompt user_id
|
||||
Paste the bot's full Matrix user ID, e.g. `@andybot:matrix.org`.
|
||||
```
|
||||
```nc:prompt bot_username
|
||||
Paste a display name for the bot, e.g. `Andy`.
|
||||
```
|
||||
```nc:env-set
|
||||
MATRIX_BASE_URL={{base_url}}
|
||||
MATRIX_USER_ID={{user_id}}
|
||||
MATRIX_BOT_USERNAME={{bot_username}}
|
||||
```
|
||||
|
||||
For **Option A** capture the bot login, for **Option B** capture the access
|
||||
token — set only the block matching your chosen method:
|
||||
|
||||
```nc:prompt username
|
||||
Option A only — the bot's login username (the localpart, e.g. `andybot`).
|
||||
```
|
||||
```nc:prompt password secret
|
||||
Option A only — the bot account's password.
|
||||
```
|
||||
```nc:env-set
|
||||
MATRIX_USERNAME={{username}}
|
||||
MATRIX_PASSWORD={{password}}
|
||||
```
|
||||
```nc:prompt access_token secret
|
||||
Option B only — the access token from Element Settings > Help & About, or from the login API.
|
||||
```
|
||||
```nc:env-set
|
||||
MATRIX_ACCESS_TOKEN={{access_token}}
|
||||
```bash
|
||||
mkdir -p data/env && cp .env data/env/env
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
@@ -9,13 +9,13 @@ Installs [mnemon](https://github.com/mnemon-dev/mnemon) in the agent container i
|
||||
|
||||
## Provider Compatibility
|
||||
|
||||
mnemon hooks fire only under `--target claude-code`. Use this skill on agent groups that run the default Claude provider. The provider is the materialized `provider` key in each group's `container.json` (absent or `claude` = default Claude provider). Confirm it before applying:
|
||||
mnemon hooks fire only under `--target claude-code`. Use this skill on agent groups that run the default Claude provider (`AGENT_PROVIDER=claude`). Confirm the provider before applying:
|
||||
|
||||
```bash
|
||||
grep -H '"provider"' groups/*/container.json 2>/dev/null # no match, or "provider": "claude" = Claude
|
||||
grep AGENT_PROVIDER .env groups/*/container.json 2>/dev/null
|
||||
```
|
||||
|
||||
If a group sets a different provider (e.g. `"provider": "opencode"`), it spawns its own process and never invokes the `claude` CLI, so the hooks registered by `mnemon setup` do not run for that group.
|
||||
If a group uses a different provider (e.g. `AGENT_PROVIDER=opencode`), it spawns its own process and never invokes the `claude` CLI, so the hooks registered by `mnemon setup` do not run for that group.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: add-opencode
|
||||
description: Use OpenCode as an agent provider. OpenRouter, OpenAI, Google, DeepSeek, etc. via OpenCode config — not the Anthropic Agent SDK. Per group via `ncl groups config update --provider opencode`; host passes OPENCODE_* and XDG mount when spawning containers.
|
||||
description: Use OpenCode as an agent provider (AGENT_PROVIDER=opencode). OpenRouter, OpenAI, Google, DeepSeek, etc. via OpenCode config — not the Anthropic Agent SDK. Per-session and per-group via agent_provider; host passes OPENCODE_* and XDG mount when spawning containers.
|
||||
---
|
||||
|
||||
# OpenCode agent provider
|
||||
|
||||
NanoClaw runs agents in a long-lived **poll loop** inside the container. The backend is selected per agent group by the **`provider`** key in that group's `container.json` (materialized from the `container_configs` table) — set it with `ncl groups config update --provider opencode`. Default is `claude`.
|
||||
NanoClaw runs agents in a long-lived **poll loop** inside the container. The backend is selected with **`AGENT_PROVIDER`** (`claude` | `opencode` | `mock`).
|
||||
|
||||
Trunk ships with only the `claude` provider baked in. This skill copies the OpenCode provider files in from the `providers` branch, wires them into the host and container barrels, installs dependencies, and rebuilds the image.
|
||||
|
||||
@@ -148,7 +148,7 @@ done
|
||||
|
||||
Set model/provider strings in the form OpenCode expects (often `provider/model-id`). **Put comments on their own lines** — a `#` inside a value is kept verbatim and breaks model IDs.
|
||||
|
||||
These variables are read **on the host** and passed into the container only when the effective provider is `opencode`. They do not switch the provider by themselves; the group still needs `provider` set to `opencode` (see [Select the provider](#select-the-provider) below).
|
||||
These variables are read **on the host** and passed into the container only when the effective provider is `opencode`. They do not switch the provider by themselves; the DB still needs `agent_provider` set (below).
|
||||
|
||||
- `OPENCODE_PROVIDER` — OpenCode provider id, e.g. `openrouter`, `anthropic`, `deepseek`.
|
||||
- `OPENCODE_MODEL` — full model id in `provider/model` form, e.g. `deepseek/deepseek-chat`.
|
||||
@@ -215,7 +215,7 @@ OPENCODE_SMALL_MODEL=anthropic/claude-haiku-4-5-20251001
|
||||
|
||||
Zen's HTTP API (e.g. `POST …/zen/v1/messages`) expects the key in the **`x-api-key`** header. If OneCLI injects **`Authorization: Bearer …`** only, Zen often returns **401 / "Missing API key"** even though the gateway is working.
|
||||
|
||||
**Naming:** NanoClaw's **`provider: opencode`** (the `container.json` key, set via `ncl groups config update --provider opencode`) means "run the **OpenCode agent provider**." Separately, **`OPENCODE_PROVIDER=opencode`** in `.env` is OpenCode's **Zen provider id** inside the OpenCode config (see [Zen docs](https://opencode.ai/docs/zen/)).
|
||||
**Naming:** NanoClaw **`AGENT_PROVIDER=opencode`** (DB `agent_provider`) means "run the **OpenCode agent provider**." Separately, **`OPENCODE_PROVIDER=opencode`** in `.env` is OpenCode's **Zen provider id** inside the OpenCode config (see [Zen docs](https://opencode.ai/docs/zen/)).
|
||||
|
||||
**Host `.env` (typical Zen shape):**
|
||||
|
||||
@@ -236,16 +236,9 @@ onecli secrets create --name "OpenCode Zen" --type generic \
|
||||
--header-name "x-api-key" --value-format "{value}"
|
||||
```
|
||||
|
||||
### Select the provider
|
||||
### Per group / per session
|
||||
|
||||
Per group, from the host:
|
||||
|
||||
```bash
|
||||
ncl groups config update --id <group-id> --provider opencode
|
||||
ncl groups restart --id <group-id>
|
||||
```
|
||||
|
||||
`ncl groups config update --provider` writes the `provider` value into the `container_configs` table; the host materializes it into `groups/<folder>/container.json` at spawn time and the in-container runner reads `provider` from there (defaulting to `claude`). The restart picks up the change. Switching is an operator action — run it from the host. Memory does NOT carry over automatically between providers — run `/migrate-memory` to carry it across.
|
||||
Set `"provider": "opencode"` in the group's **`container.json`** (`groups/<folder>/container.json`) — the in-container runner reads `provider` from there, not from the DB. The DB columns **`agent_groups.agent_provider`** and **`sessions.agent_provider`** (session overrides group) only drive host-side provider contribution — per-session XDG mount, `OPENCODE_*` env passthrough — and do not propagate into `container.json` at spawn time. Set both, or just edit `container.json`; if they disagree, the runner uses `container.json` and the host-side resolver falls back through session → group → `container.json` → `'claude'`.
|
||||
|
||||
Extra MCP servers still come from **`NANOCLAW_MCP_SERVERS`** / `container_config.mcpServers` on the host; the runner merges them into the same `mcpServers` object passed to **both** Claude and OpenCode providers.
|
||||
|
||||
@@ -257,6 +250,6 @@ Extra MCP servers still come from **`NANOCLAW_MCP_SERVERS`** / `container_config
|
||||
|
||||
## Next Steps
|
||||
|
||||
The registration and Dockerfile guards in step 7 verify the wiring. To confirm an end-to-end round-trip, switch a test group with `ncl groups config update --id <group-id> --provider opencode && ncl groups restart --id <group-id>`, register the matching provider key in OneCLI, and send a message. A clean exchange returns the model's reply with no `Unknown provider: opencode` error and no UUID/session warnings in the logs.
|
||||
The registration and Dockerfile guards in step 7 verify the wiring. To confirm an end-to-end round-trip, set `agent_provider = 'opencode'` (or `"provider": "opencode"` in the group's `container.json`) on a test group, register the matching provider key in OneCLI, and send a message. A clean exchange returns the model's reply with no `Unknown provider: opencode` error and no UUID/session warnings in the logs.
|
||||
|
||||
To remove this provider, see [REMOVE.md](REMOVE.md).
|
||||
|
||||
@@ -5,70 +5,61 @@ description: Add Resend (email) channel integration via Chat SDK.
|
||||
|
||||
# Add Resend Email Channel
|
||||
|
||||
Connect NanoClaw to email via Resend for async email conversations. NanoClaw
|
||||
doesn't ship channels in trunk — this skill copies the Resend adapter in from the
|
||||
`channels` branch.
|
||||
Connect NanoClaw to email via Resend for async email conversations.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent reads
|
||||
the prose and applies them, and a parser can apply them deterministically from
|
||||
the same document. Every directive is idempotent, so the whole skill is safe to
|
||||
re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
## Apply
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the Resend adapter in from the `channels` branch.
|
||||
|
||||
### 1. Copy the adapter
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the Resend adapter into `src/channels/`
|
||||
(overwrite — the branch is canonical):
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/resend.ts
|
||||
src/channels/resend-registration.test.ts
|
||||
- `src/channels/resend.ts` exists
|
||||
- `src/channels/resend-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './resend.js';`
|
||||
- `@resend/chat-sdk-adapter` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/resend.ts > src/channels/resend.ts
|
||||
git show origin/channels:src/channels/resend-registration.test.ts > src/channels/resend-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './resend.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
@resend/chat-sdk-adapter@0.1.1
|
||||
```bash
|
||||
pnpm install @resend/chat-sdk-adapter@0.1.1
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Build and validate
|
||||
|
||||
Build guards the typed `createChatSdkBridge(...)` core call and proves the
|
||||
dependency is installed (the adapter imports `@resend/chat-sdk-adapter`; if it
|
||||
isn't installed the barrel throws). End-to-end email delivery against a real
|
||||
domain is verified manually once the service runs.
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/resend-registration.test.ts
|
||||
```
|
||||
|
||||
`resend-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `resend`. It goes red if the import line is deleted or drifts,
|
||||
if the barrel fails to evaluate, or if `@resend/chat-sdk-adapter` isn't installed
|
||||
(the import throws) — so it also covers the dependency from step 3.
|
||||
Both must be clean before proceeding. `resend-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `resend`. It goes red if the `import './resend.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@resend/chat-sdk-adapter` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
## Credentials
|
||||
|
||||
Resend account and domain setup is human and interactive — these steps are
|
||||
prose, not directives (no parser can verify a sending domain or click through the
|
||||
Resend UI). A recipe rebuild produces a compiling, registered adapter that cannot
|
||||
receive a message until they're done.
|
||||
|
||||
1. Go to [resend.com](https://resend.com) and create an account.
|
||||
2. Add and verify your sending domain.
|
||||
3. Go to **API Keys** and create a new key.
|
||||
@@ -78,72 +69,30 @@ receive a message until they're done.
|
||||
- Events: select **email.received**.
|
||||
- Copy the signing secret.
|
||||
|
||||
### Store the credentials
|
||||
### Configure environment
|
||||
|
||||
Capture the secrets, then write them. `prompt` only *asks* and binds the answer
|
||||
to a name; a separate directive consumes it — so the same prompts could feed
|
||||
`ncl` or the OneCLI vault instead of `.env` by swapping only the consumer. Here
|
||||
they go to `.env` (set-if-absent — a value you've already filled in is never
|
||||
overwritten):
|
||||
Add to `.env`:
|
||||
|
||||
```nc:prompt api_key secret
|
||||
Paste the Resend API key — API Keys, starts with `re_`.
|
||||
```
|
||||
```nc:prompt webhook_secret secret
|
||||
Paste the webhook signing secret — Webhooks, the value you copied above.
|
||||
```
|
||||
```nc:prompt from_address
|
||||
The bot's sending email address on your verified domain (e.g. `bot@yourdomain.com`).
|
||||
```
|
||||
```nc:prompt from_name
|
||||
The display name to send as (e.g. `NanoClaw`).
|
||||
```
|
||||
```nc:env-set
|
||||
RESEND_API_KEY={{api_key}}
|
||||
RESEND_FROM_ADDRESS={{from_address}}
|
||||
RESEND_FROM_NAME={{from_name}}
|
||||
RESEND_WEBHOOK_SECRET={{webhook_secret}}
|
||||
```
|
||||
## Connect yourself
|
||||
|
||||
Because email is direct-addressable, the bot can write to you first — so wire
|
||||
your own address as the owner and have it email you a hello. Tell it your address
|
||||
and which agent should answer your email (`ncl groups list` shows their folders):
|
||||
|
||||
```nc:prompt owner_email
|
||||
Your email address — I'll wire you as owner and email you a hello.
|
||||
```
|
||||
```nc:prompt agent_folder
|
||||
Which agent should answer your email? Enter its folder (run `ncl groups list`).
|
||||
```bash
|
||||
RESEND_API_KEY=re_...
|
||||
RESEND_FROM_ADDRESS=bot@yourdomain.com
|
||||
RESEND_FROM_NAME=NanoClaw
|
||||
RESEND_WEBHOOK_SECRET=your-webhook-secret
|
||||
```
|
||||
|
||||
Register yourself as the owner, wire your address so the agent answers your email,
|
||||
and send the hello:
|
||||
|
||||
```nc:run effect:wire
|
||||
ncl users create --id resend:{{owner_email}} --kind resend --display-name Owner
|
||||
ncl roles grant --user resend:{{owner_email}} --role owner
|
||||
ncl messaging-groups create --channel-type resend --platform-id resend:{{owner_email}} --is-group 0
|
||||
ncl wirings create --channel-type resend --platform-id resend:{{owner_email}} --agent-group {{agent_folder}} --engage-mode pattern --engage-pattern .
|
||||
ncl messaging-groups send --channel-type resend --platform-id resend:{{owner_email}} --sender-id resend:{{owner_email}} --sender Owner --text "Hi — I'm your NanoClaw assistant, reachable by email now. Reply to this thread anytime."
|
||||
```
|
||||
|
||||
The hello arrives as a fresh email thread; reply to keep the conversation going.
|
||||
Your own address is the conversation key (`resend:<your-address>`).
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now. (Answering an
|
||||
*open* inbox — anyone who emails in, not just you — is a separate, not-yet-wired
|
||||
case: email is plain-message, so the router never auto-creates a group for an
|
||||
unknown sender; each correspondent's `resend:<their-address>` must be wired
|
||||
explicitly.)
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
- **type**: `resend`
|
||||
- **terminology**: Resend handles email. The bot has one fixed sending identity (`RESEND_FROM_ADDRESS`, e.g. `bot@yourdomain.com`); every *external correspondent* the bot emails with is a separate conversation, keyed by *their* address.
|
||||
- **how-to-find-id**: The platform ID is the **correspondent's** email address, prefixed — `resend:<their-address>` (e.g. `resend:you@example.com`) — **not** the bot's from-address. The adapter derives it from the reply-to party (`channelIdFromThreadId` returns `resend:<address>`); each distinct email thread from that person (by root `Message-ID`) is a sub-conversation under it.
|
||||
- **supports-threads**: no (the adapter sets `supportsThreads: false`; replies still thread via email headers, but the router does not treat threads as the primary conversation unit)
|
||||
- **terminology**: Resend handles email. Each email thread (identified by subject/In-Reply-To headers) is a separate conversation. The "from address" is the bot's identity.
|
||||
- **how-to-find-id**: The platform ID is the from email address (e.g. `bot@yourdomain.com`). Each sender's email thread becomes its own conversation.
|
||||
- **supports-threads**: yes (via email threading headers -- replies to the same thread stay together)
|
||||
- **typical-use**: Async communication -- email conversations with longer response expectations
|
||||
- **default-isolation**: Same agent group if you want your agent to handle email alongside other channels. Separate agent group if email contains sensitive correspondence that shouldn't be accessible from other channels.
|
||||
|
||||
@@ -4,15 +4,21 @@ Idempotent — safe to run even if some steps were never applied. Run Steps 1–
|
||||
|
||||
## 1. Remove the mount from the container config
|
||||
|
||||
Remove the rtk mount with the host-only `remove-mount` verb. It is idempotent — a no-op if the mount isn't present:
|
||||
Read the current mounts, drop the entry whose `containerPath` is `/usr/local/bin/rtk`, and write the rest back.
|
||||
|
||||
```bash
|
||||
ncl groups config remove-mount --id <group-id> \
|
||||
--host ~/.local/bin/rtk \
|
||||
--container /usr/local/bin/rtk
|
||||
pnpm exec tsx scripts/q.ts data/v2.db \
|
||||
"SELECT additional_mounts FROM container_configs WHERE agent_group_id = '<group-id>'"
|
||||
```
|
||||
|
||||
This verb is operator-only and runs host-side; it is rejected from inside a container.
|
||||
Write the filtered array (omit any entry with `"containerPath":"/usr/local/bin/rtk"`):
|
||||
|
||||
```bash
|
||||
pnpm exec tsx scripts/q.ts data/v2.db \
|
||||
"UPDATE container_configs SET additional_mounts = '<filtered-json>' WHERE agent_group_id = '<group-id>'"
|
||||
```
|
||||
|
||||
If no rtk entry is present, leave the array as-is.
|
||||
|
||||
## 2. Remove the PreToolUse hook from settings.json
|
||||
|
||||
|
||||
@@ -13,10 +13,6 @@ Install [rtk](https://github.com/rtk-ai/rtk) — a CLI proxy delivering 60–90%
|
||||
- `~/.local/bin/rtk` mounted read-only at `/usr/local/bin/rtk` inside the target agent group's containers
|
||||
- `PreToolUse` hook in the agent group's `settings.json` so every Bash call is automatically filtered through rtk — no CLAUDE.md instructions needed
|
||||
|
||||
## Integration tests
|
||||
|
||||
This skill has **no in-tree integration test** by design. Its only functional reach-ins are runtime operator actions — the host-only `ncl groups config add-mount` (Step 3) and the `settings.json` `PreToolUse` hook write (Step 4) — neither of which leaves a line in the source tree whose deletion a test could catch. There are no package dependencies or Dockerfile edits to guard either. Conformance is idempotent apply + `REMOVE.md`; the mount and hook are verified at runtime (see Verify).
|
||||
|
||||
## Step 1 — Install rtk on the host
|
||||
|
||||
```bash
|
||||
@@ -47,24 +43,33 @@ Note the group ID (e.g. `ag-1776342942165-ptgddd`). Repeat Steps 3–5 for each
|
||||
|
||||
## Step 3 — Mount rtk into the container config
|
||||
|
||||
Mount the host rtk binary read-only into the container with the host-only `add-mount` verb. It is idempotent — re-running skips the entry if it is already present:
|
||||
`additional_mounts` is a JSON array column on `container_configs`. Read the current value, merge in the rtk entry, and write the merged array back.
|
||||
|
||||
Read current mounts first:
|
||||
|
||||
```bash
|
||||
ncl groups config add-mount --id <group-id> \
|
||||
--host ~/.local/bin/rtk \
|
||||
--container /usr/local/bin/rtk \
|
||||
--ro
|
||||
pnpm exec tsx scripts/q.ts data/v2.db \
|
||||
"SELECT additional_mounts FROM container_configs WHERE agent_group_id = '<group-id>'"
|
||||
```
|
||||
|
||||
This verb is operator-only and runs host-side (via `/setup`, `/customize`, or `/manage-mounts`); it is rejected from inside a container.
|
||||
Build the merged array: keep every existing entry, drop any entry whose `containerPath` is `/usr/local/bin/rtk` (so re-running replaces rather than duplicates), then add the rtk entry:
|
||||
|
||||
The host root (`~/.local/bin`) must also be in the external mount allowlist at `~/.config/nanoclaw/mount-allowlist.json` for the mount to take effect at spawn. Add it there if it isn't already.
|
||||
```json
|
||||
{"hostPath":"/home/<user>/.local/bin/rtk","containerPath":"/usr/local/bin/rtk","readonly":true}
|
||||
```
|
||||
|
||||
Write the merged array back:
|
||||
|
||||
```bash
|
||||
pnpm exec tsx scripts/q.ts data/v2.db \
|
||||
"UPDATE container_configs SET additional_mounts = '<merged-json>' WHERE agent_group_id = '<group-id>'"
|
||||
```
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
ncl groups config get --id <group-id>
|
||||
# Look for the /usr/local/bin/rtk mount
|
||||
pnpm exec tsx scripts/q.ts data/v2.db \
|
||||
"SELECT additional_mounts FROM container_configs WHERE agent_group_id = '<group-id>'"
|
||||
```
|
||||
|
||||
## Step 4 — Add the PreToolUse hook to settings.json
|
||||
@@ -115,8 +120,9 @@ Then ask the agent to run `git status` or any other supported command. rtk inter
|
||||
Mount wasn't applied or container wasn't restarted:
|
||||
|
||||
```bash
|
||||
ncl groups config get --id <group-id>
|
||||
# Look for the /usr/local/bin/rtk mount
|
||||
pnpm exec tsx scripts/q.ts data/v2.db \
|
||||
"SELECT additional_mounts FROM container_configs WHERE agent_group_id = '<group-id>'"
|
||||
# Look for entry with /usr/local/bin/rtk
|
||||
ncl groups restart --id <group-id>
|
||||
```
|
||||
|
||||
|
||||
+188
-154
@@ -1,168 +1,53 @@
|
||||
---
|
||||
name: add-signal
|
||||
description: Add Signal channel integration via signal-cli device-link. Native adapter — no Chat SDK bridge.
|
||||
description: Add Signal channel integration via signal-cli TCP daemon. Native adapter — no Chat SDK bridge.
|
||||
---
|
||||
|
||||
# Add Signal Channel
|
||||
|
||||
Adds Signal support via a native adapter that speaks JSON-RPC to a
|
||||
[signal-cli](https://github.com/AsamK/signal-cli) daemon — no Chat SDK bridge,
|
||||
only Node.js builtins. NanoClaw links to Signal as a *secondary device* on your
|
||||
existing phone: no new number, no bot API. Your assistant sends and receives as
|
||||
the number on the phone that scans the link.
|
||||
Adds Signal messaging support via a native adapter that speaks JSON-RPC to a [signal-cli](https://github.com/AsamK/signal-cli) TCP daemon. No Chat SDK bridge — only Node.js builtins (`node:net`, `node:child_process`, `node:fs`).
|
||||
|
||||
## Apply
|
||||
Unlike Telegram or Discord, Signal has no bot API. NanoClaw registers as a full Signal account on a dedicated phone number (recommended) or links as a secondary device on your existing number.
|
||||
|
||||
### 1. Install signal-cli
|
||||
## Prerequisites
|
||||
|
||||
NanoClaw talks to Signal through signal-cli, which has no bot API of its own.
|
||||
Install it if it isn't on PATH yet — Homebrew on macOS, the native release binary
|
||||
on Linux (neither needs Java). If it's already installed this is a no-op:
|
||||
### Java
|
||||
|
||||
```nc:run effect:external
|
||||
command -v signal-cli >/dev/null 2>&1 || bash setup/install-signal-cli.sh
|
||||
signal-cli requires Java 17+:
|
||||
|
||||
```bash
|
||||
java -version
|
||||
```
|
||||
|
||||
### 2. Copy the adapter and its registration test
|
||||
If missing:
|
||||
- **macOS:** `brew install --cask temurin@17`
|
||||
- **Debian/Ubuntu:** `sudo apt-get install -y default-jre`
|
||||
- **RHEL/Fedora:** `sudo dnf install -y java-17-openjdk`
|
||||
|
||||
Fetch the `channels` branch and copy the Signal adapter and its registration test
|
||||
into `src/channels/` (overwrite — the branch is canonical):
|
||||
Java 17–25 all work.
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/signal.ts
|
||||
src/channels/signal-registration.test.ts
|
||||
### signal-cli
|
||||
|
||||
- **macOS:** `brew install signal-cli`
|
||||
- **Linux:** download the native binary from [GitHub releases](https://github.com/AsamK/signal-cli/releases):
|
||||
|
||||
```bash
|
||||
SIGNAL_CLI_VERSION=$(curl -fsSL https://api.github.com/repos/AsamK/signal-cli/releases/latest | python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'][1:])")
|
||||
curl -fsSL "https://github.com/AsamK/signal-cli/releases/download/v${SIGNAL_CLI_VERSION}/signal-cli-${SIGNAL_CLI_VERSION}-Linux-native.tar.gz" \
|
||||
| tar -xz -C ~/.local
|
||||
ln -sf ~/.local/signal-cli ~/.local/bin/signal-cli
|
||||
signal-cli --version
|
||||
```
|
||||
|
||||
### 3. Register the adapter
|
||||
> The Linux native tarball extracts a single binary directly to `~/.local/signal-cli` (not into a subdirectory). The symlink above puts it on PATH.
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line is
|
||||
already present). This one line is the skill's only reach-in into core:
|
||||
## Registration
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
import './signal.js';
|
||||
```
|
||||
Two paths. The new-number path is recommended and battle-tested.
|
||||
|
||||
### 4. Install the QR-rendering dependency
|
||||
### Path A: Register a new number (recommended)
|
||||
|
||||
The device-link step renders the linking URL as a terminal QR via `qrcode`.
|
||||
Pinned to exact versions — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
qrcode@1.5.4
|
||||
@types/qrcode@1.5.6
|
||||
```
|
||||
|
||||
The adapter itself consumes only Node.js builtins, so there is no adapter package
|
||||
to install — `qrcode` is purely for rendering the link during setup.
|
||||
|
||||
### 5. Build and validate
|
||||
|
||||
Build first: it guards the adapter's typed core-API consumption. Then run the one
|
||||
integration test.
|
||||
|
||||
```nc:run effect:build
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/signal-registration.test.ts
|
||||
```
|
||||
|
||||
`signal-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `signal`. It goes red if the `import './signal.js';` line is
|
||||
deleted or drifts, or if the barrel fails to evaluate — so the channel genuinely
|
||||
would not register. The adapter has no npm dependency to guard; its typed
|
||||
core-API consumption is covered by the build. End-to-end delivery against a real
|
||||
Signal account is verified manually once the service runs.
|
||||
|
||||
## Link your Signal account
|
||||
|
||||
This is the whole credential step. signal-cli opens a device-link handshake,
|
||||
prints a `sgnl://linkdevice…` URL, and renders it as a scannable QR. You scan it
|
||||
once from the phone that already runs Signal; that phone's number becomes the
|
||||
account NanoClaw sends and receives as — no number is registered.
|
||||
|
||||
The device-link runs signal-cli, so it must be reachable first — on `PATH`, or at
|
||||
`$SIGNAL_CLI_PATH`. If step 1's install didn't land, the link step has nothing to
|
||||
drive; confirm it's present before linking (re-run step 1 if this fails):
|
||||
|
||||
```nc:run effect:check
|
||||
command -v signal-cli >/dev/null 2>&1 || [ -x "$SIGNAL_CLI_PATH" ]
|
||||
```
|
||||
|
||||
Tell the user:
|
||||
|
||||
```nc:operator
|
||||
Link NanoClaw to your Signal account:
|
||||
1. On the phone that runs Signal, open Signal → Settings → Linked Devices → Link New Device.
|
||||
2. Scan the QR code shown below — or open the `sgnl://linkdevice…` link printed under it on that phone.
|
||||
3. Wait for confirmation. The linking URL expires after ~3 minutes; re-run this step for a fresh one.
|
||||
```
|
||||
|
||||
Run the device-link. It blocks until you scan, then reports the linked phone
|
||||
number back as the account — that number is both your owner handle and the
|
||||
conversation address the wiring step needs:
|
||||
|
||||
```nc:run effect:step capture:platform_id=ACCOUNT,owner_handle=ACCOUNT
|
||||
pnpm exec tsx setup/index.ts --step signal-auth
|
||||
```
|
||||
|
||||
`owner_handle` and `platform_id` both come back as the bare phone number (e.g.
|
||||
`+15551234567`). Your assistant reaches you through Signal's Note to Self, so the
|
||||
owner conversation is addressed by your own number — not a per-contact UUID.
|
||||
|
||||
## Persist the account
|
||||
|
||||
Store the linked number so the adapter binds the right account on start, then sync
|
||||
it into the container env:
|
||||
|
||||
```nc:env-set
|
||||
SIGNAL_ACCOUNT={{platform_id}}
|
||||
```
|
||||
## Restart
|
||||
|
||||
Restart the service so it loads the Signal adapter and binds the account you just
|
||||
linked, and wait for its CLI socket before wiring:
|
||||
|
||||
```nc:run effect:restart
|
||||
bash setup/lib/restart.sh
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now. Otherwise wire
|
||||
this channel with `/init-first-agent` (or `/manage-channels`).
|
||||
|
||||
## Channel Info
|
||||
|
||||
- **type**: `signal`
|
||||
- **terminology**: Signal has "chats" (1:1 DMs) and "groups." The owner reaches their own assistant through Note to Self.
|
||||
- **platform-id-format**:
|
||||
- Owner DM (Note to Self): the bare phone number `+<number>` (e.g. `+15551234567`) — your own messages route back as inbound with `isFromMe`, addressed by your number.
|
||||
- Third-party DM: `signal:{UUID}` — the sender's Signal ACI, **not** their phone number.
|
||||
- Group: `signal:{base64GroupId}` — base64-encoded GroupV2 ID.
|
||||
- **how-to-find-id**: The owner number comes back from the device-link step above. For third parties or groups, send a message to the bot, then query `messaging_groups`.
|
||||
- **supports-threads**: no
|
||||
- **typical-use**: Personal assistant via Signal DMs or small group chats
|
||||
- **default-isolation**: One agent per Signal account. Multiple chats with the same operator can share an agent group; groups with other people should typically use `isolated` session mode.
|
||||
|
||||
### Features
|
||||
|
||||
- Markdown formatting — `**bold**`, `*italic*` / `_italic_`, `` `code` ``, ` ```code fence``` `, `~~strike~~`, `||spoiler||` (converted to Signal's offset-based text styles).
|
||||
- Quoted replies — `replyTo*` fields populated from Signal quotes.
|
||||
- Typing indicators — DMs only (Signal doesn't support group typing).
|
||||
- Note to Self — messages you send to your own account from another device route to the agent as inbound with `isFromMe: true`.
|
||||
- Voice attachments — detected but not transcribed by default; the agent receives a `[Voice Message]` placeholder. Run `/add-voice-transcription` for local transcription.
|
||||
|
||||
Not supported yet: outbound file attachments (logged and dropped), edit/delete messages, reactions.
|
||||
|
||||
## Alternatives
|
||||
|
||||
### Register a dedicated number instead of linking
|
||||
|
||||
The device-link above joins Signal as a *secondary device* on an existing number.
|
||||
If you'd rather give the assistant its own number, register a dedicated SIM or
|
||||
VoIP number that NanoClaw owns entirely. This path takes a captcha, an SMS (or
|
||||
voice) verification, and an optional profile name.
|
||||
Use a dedicated SIM or VoIP number. NanoClaw owns it entirely.
|
||||
|
||||
> **VoIP numbers:** Signal requires SMS verification before voice. Some VoIP providers are blocked even for voice calls. If registration fails with an auth error, try a different provider or a physical SIM.
|
||||
|
||||
@@ -222,12 +107,69 @@ signal-cli -a +1YOURNUMBER updateProfile --name "YourBotName"
|
||||
systemctl --user start $(systemd_unit)
|
||||
```
|
||||
|
||||
Once registered, set `SIGNAL_ACCOUNT` to this number (as under **Persist the account** above) and restart the service.
|
||||
### Path B: Link as secondary device
|
||||
|
||||
## Optional configuration
|
||||
Joins an existing Signal account as a secondary device. Simpler, but NanoClaw shares your personal number.
|
||||
|
||||
These `.env` keys tune how NanoClaw talks to the signal-cli daemon. All are
|
||||
optional — the defaults work for the device-link flow above.
|
||||
```bash
|
||||
signal-cli -a +1YOURNUMBER link --name "NanoClaw"
|
||||
```
|
||||
|
||||
This prints a `tsdevice:` URI. Scan it as a QR code on your phone: **Settings → Linked Devices → Link New Device**. QR codes expire in ~30 seconds — re-run if it expires.
|
||||
|
||||
## Install
|
||||
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
- `src/channels/signal.ts` exists
|
||||
- `src/channels/signal.test.ts` exists
|
||||
- `src/channels/signal-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './signal.js';`
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Copy the adapter and tests
|
||||
|
||||
```bash
|
||||
git show origin/channels:src/channels/signal.ts > src/channels/signal.ts
|
||||
git show origin/channels:src/channels/signal.test.ts > src/channels/signal.test.ts
|
||||
git show origin/channels:src/channels/signal-registration.test.ts > src/channels/signal-registration.test.ts
|
||||
```
|
||||
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './signal.js';
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
pnpm exec vitest run src/channels/signal-registration.test.ts
|
||||
```
|
||||
|
||||
Both must be clean before proceeding. `signal-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `signal`. It goes red if the `import './signal.js';` line is deleted or drifts, or if the barrel fails to evaluate (so the channel genuinely would not register). The adapter consumes only Node.js builtins, so there is no npm dependency to guard for this channel. The adapter's typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
## Credentials
|
||||
|
||||
Add to `.env`:
|
||||
|
||||
```bash
|
||||
SIGNAL_ACCOUNT=+1YOURNUMBER
|
||||
```
|
||||
|
||||
### Optional settings
|
||||
|
||||
```bash
|
||||
# TCP daemon host and port (default: 127.0.0.1:7583)
|
||||
@@ -247,6 +189,94 @@ SIGNAL_DATA_DIR=~/.local/share/signal-cli
|
||||
|
||||
**Security note:** keep the TCP host on `127.0.0.1`. The daemon has no auth — binding it to a public interface would expose your full Signal account to the network.
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Restart
|
||||
|
||||
Run from your NanoClaw project root:
|
||||
|
||||
```bash
|
||||
source setup/lib/install-slug.sh
|
||||
|
||||
# macOS
|
||||
launchctl kickstart -k gui/$(id -u)/$(launchd_label)
|
||||
|
||||
# Linux
|
||||
systemctl --user restart $(systemd_unit)
|
||||
```
|
||||
|
||||
## Wiring
|
||||
|
||||
### DMs
|
||||
|
||||
After the service starts, send any message to the Signal number from your personal Signal app. The router auto-creates a `messaging_groups` row. Then:
|
||||
|
||||
```bash
|
||||
pnpm exec tsx scripts/q.ts data/v2.db \
|
||||
"SELECT id, platform_id FROM messaging_groups WHERE channel_type='signal' ORDER BY created_at DESC LIMIT 5"
|
||||
```
|
||||
|
||||
Pass the `id` to `/init-first-agent` or `/manage-channels` to wire it to an agent group.
|
||||
|
||||
### Groups
|
||||
|
||||
Add the Signal number to a group from your phone, send any message, then wire the resulting row the same way. For isolated per-group sessions:
|
||||
|
||||
```bash
|
||||
NOW=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
|
||||
pnpm exec tsx scripts/q.ts data/v2.db "
|
||||
INSERT OR IGNORE INTO messaging_group_agents
|
||||
(id, messaging_group_id, agent_group_id, session_mode, priority, created_at)
|
||||
VALUES
|
||||
('mga-'||hex(randomblob(8)), 'mg-GROUPID', 'ag-AGENTID', 'isolated', 0, '$NOW');
|
||||
"
|
||||
```
|
||||
|
||||
### Grant user access
|
||||
|
||||
New Signal users (including the owner's Signal identity) are silently dropped with `not_member` until granted access. After the user's first message appears in `messaging_groups`:
|
||||
|
||||
```bash
|
||||
NOW=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
|
||||
pnpm exec tsx scripts/q.ts data/v2.db "
|
||||
INSERT OR REPLACE INTO user_roles (user_id, role, agent_group_id, granted_by, granted_at)
|
||||
VALUES ('signal:UUID', 'owner', NULL, 'system', '$NOW');
|
||||
INSERT OR IGNORE INTO agent_group_members (user_id, agent_group_id, added_by, added_at)
|
||||
VALUES ('signal:UUID', 'ag-AGENTID', 'system', '$NOW');
|
||||
"
|
||||
```
|
||||
|
||||
Find the UUID from `messaging_groups.platform_id` or the `users` table.
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/init-first-agent` to create an agent and wire it to your Signal DM, or `/manage-channels` to wire this channel to an existing agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
- **type**: `signal`
|
||||
- **terminology**: Signal has "chats" (1:1 DMs) and "groups"
|
||||
- **supports-threads**: no
|
||||
- **platform-id-format**:
|
||||
- DM: `signal:{UUID}` — sender's Signal UUID (ACI), **not** their phone number
|
||||
- Group: `signal:{base64GroupId}` — base64-encoded GroupV2 ID
|
||||
- **how-to-find-id**: Send a message to the bot, then query `messaging_groups` as shown above
|
||||
- **typical-use**: Personal assistant via Signal DMs or small group chats
|
||||
- **default-isolation**: One agent per Signal account. Multiple chats with the same operator can share an agent group; groups with other people should typically use `isolated` session mode
|
||||
|
||||
### Features
|
||||
|
||||
- Markdown formatting — `**bold**`, `*italic*` / `_italic_`, `` `code` ``, ` ```code fence``` `, `~~strike~~`, `||spoiler||` (converted to Signal's offset-based text styles)
|
||||
- Quoted replies — `replyTo*` fields populated from Signal quotes
|
||||
- Typing indicators — DMs only (Signal doesn't support group typing)
|
||||
- Echo suppression — outbound messages matched on `(platformId, text)` within a 10 s TTL to avoid syncMessage loops
|
||||
- Note to Self — messages you send to your own account from another device route to the agent as inbound with `isFromMe: true`
|
||||
- Voice attachments — detected but not transcribed by default; the agent receives `[Voice Message]` placeholder text. Run `/add-voice-transcription` for local transcription via parakeet-mlx
|
||||
|
||||
Not supported yet: outbound file attachments (logged and dropped), edit/delete messages, reactions.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Daemon not reachable
|
||||
@@ -257,9 +287,9 @@ grep "Signal" logs/nanoclaw.log | tail
|
||||
|
||||
If you see `Signal daemon failed to start. Is signal-cli installed and your account linked?`:
|
||||
- Confirm `signal-cli` is on PATH (or set `SIGNAL_CLI_PATH`)
|
||||
- Confirm the account is linked: `signal-cli -a +YOURNUMBER listIdentities` should succeed without prompting
|
||||
- Confirm the account is linked: `signal-cli -a +1YOURNUMBER listIdentities` should succeed without prompting
|
||||
|
||||
If you see `Signal daemon not reachable at 127.0.0.1:7583` and `SIGNAL_MANAGE_DAEMON=false`, start the daemon yourself: `signal-cli -a +YOURNUMBER daemon --tcp 127.0.0.1:7583`.
|
||||
If you see `Signal daemon not reachable at 127.0.0.1:7583` and `SIGNAL_MANAGE_DAEMON=false`, start the daemon yourself: `signal-cli -a +1YOURNUMBER daemon --tcp 127.0.0.1:7583`.
|
||||
|
||||
### Bot not responding
|
||||
|
||||
@@ -278,7 +308,7 @@ If you see `Signal channel lost TCP connection to signal-cli daemon` in the logs
|
||||
|
||||
### Messages dropped with `not_member`
|
||||
|
||||
The Signal user hasn't been granted membership. New Signal senders — including the owner's Signal identity — are gated until granted access. `/init-first-agent` grants the owner automatically; for other users, wire access with `/manage-channels` after their first message appears in `messaging_groups`. This affects every new Signal user, since their Signal identity is a separate user record from their identity on other channels even if it's the same person.
|
||||
The Signal user hasn't been granted membership. See "Grant user access" above. This affects every new Signal user, including the owner's Signal identity — which is a separate user record from their identity on other channels even if it's the same person.
|
||||
|
||||
### Captcha required
|
||||
|
||||
@@ -296,6 +326,10 @@ signal-cli holds an exclusive lock on its data directory while the daemon is run
|
||||
|
||||
Modern Signal groups use GroupV2. The adapter must extract the group ID from `envelope?.dataMessage?.groupV2?.id` — not `groupInfo?.groupId`, which is GroupV1/legacy. If group messages are routing as DMs, check `src/channels/signal.ts` and confirm the groupId extraction falls through to `groupV2.id`.
|
||||
|
||||
### QR / linking URL expired
|
||||
### Java not found
|
||||
|
||||
The `sgnl://linkdevice…` URL (and the Path A registration captcha) expire after a few minutes. Re-run the device-link step to get a fresh QR.
|
||||
Install Java 17+ — see the Prerequisites section above.
|
||||
|
||||
### QR code expired (Path B)
|
||||
|
||||
QR codes expire in ~30 seconds. Re-run the link command to generate a new one.
|
||||
|
||||
@@ -5,179 +5,114 @@ description: Add Slack channel integration via Chat SDK.
|
||||
|
||||
# Add Slack Channel
|
||||
|
||||
Adds Slack support via the Chat SDK bridge. NanoClaw doesn't ship channels in
|
||||
trunk — this skill copies the Slack adapter in from the `channels` branch.
|
||||
Adds Slack support via the Chat SDK bridge.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent
|
||||
reads the prose and applies them, and a parser can apply them deterministically
|
||||
from the same document. Every directive is idempotent, so the whole skill is
|
||||
safe to re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
## Apply
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the Slack adapter in from the `channels` branch.
|
||||
|
||||
### 1. Copy the adapter and its registration test
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the Slack adapter and its registration test
|
||||
into `src/channels/` (overwrite — the branch is canonical):
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/slack.ts
|
||||
src/channels/slack-registration.test.ts
|
||||
- `src/channels/slack.ts` exists
|
||||
- `src/channels/slack-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './slack.js';`
|
||||
- `@chat-adapter/slack` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/slack.ts > src/channels/slack.ts
|
||||
git show origin/channels:src/channels/slack-registration.test.ts > src/channels/slack-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './slack.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
@chat-adapter/slack@4.29.0
|
||||
```bash
|
||||
pnpm install @chat-adapter/slack@4.29.0
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Build and validate
|
||||
|
||||
Build first: it guards the typed `createChatSdkBridge(...)` core call and proves
|
||||
the dependency is installed. Then run the one integration test.
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/slack-registration.test.ts
|
||||
```
|
||||
|
||||
`slack-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `slack`. It goes red if the import line is deleted or drifts,
|
||||
if the barrel fails to evaluate, or if `@chat-adapter/slack` isn't installed (the
|
||||
import throws) — so it also covers the dependency from step 3. End-to-end
|
||||
delivery against a real workspace is verified manually once the service runs.
|
||||
Both must be clean before proceeding. `slack-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `slack`. It goes red if the `import './slack.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/slack` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
End-to-end message delivery against a real Slack workspace is verified manually once the service is running — see Next Steps and the webhook setup above.
|
||||
|
||||
## Credentials
|
||||
|
||||
Slack can deliver events two ways. Socket Mode holds an outbound WebSocket open
|
||||
— no public URL, so it works on a laptop or behind NAT — and is the right
|
||||
default. Webhook delivery needs a public HTTPS Request URL but avoids the
|
||||
long-lived socket. The adapter picks Socket Mode automatically whenever
|
||||
`SLACK_APP_TOKEN` is set; otherwise it serves the webhook.
|
||||
### Create Slack App
|
||||
|
||||
```nc:prompt connection validate:^(socket|webhook)$
|
||||
How should Slack deliver events? `socket` (Socket Mode — no public URL, recommended for local or behind-NAT installs) or `webhook` (needs a public HTTPS Request URL).
|
||||
1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** > **From scratch**
|
||||
2. Name it (e.g., "NanoClaw") and select your workspace
|
||||
3. Go to **OAuth & Permissions** and add Bot Token Scopes:
|
||||
- `chat:write`, `im:write`, `channels:history`, `groups:history`, `im:history`, `channels:read`, `groups:read`, `users:read`, `reactions:write`, `files:read`, `files:write`
|
||||
4. Click **Install to Workspace** and copy the **Bot User OAuth Token** (`xoxb-...`)
|
||||
5. Go to **Basic Information** and copy the **Signing Secret**
|
||||
|
||||
### Enable DMs
|
||||
|
||||
6. Go to **App Home** and enable the **Messages Tab**
|
||||
7. Check **"Allow users to send Slash commands and messages from the messages tab"**
|
||||
|
||||
### Event Subscriptions
|
||||
|
||||
8. Go to **Event Subscriptions** and toggle **Enable Events**
|
||||
9. Set the **Request URL** to `https://your-domain/webhook/slack` — Slack will send a verification challenge; it must pass before you can save
|
||||
10. Under **Subscribe to bot events**, add:
|
||||
- `message.channels`, `message.groups`, `message.im`, `app_mention`
|
||||
11. Click **Save Changes**
|
||||
|
||||
### Interactivity
|
||||
|
||||
12. Go to **Interactivity & Shortcuts** and toggle **Interactivity** on
|
||||
13. Set the **Request URL** to the same `https://your-domain/webhook/slack`
|
||||
14. Click **Save Changes**
|
||||
15. Slack will show a banner asking you to **reinstall the app** — click it to apply the new settings
|
||||
|
||||
### Configure environment
|
||||
|
||||
Add to `.env`:
|
||||
|
||||
```bash
|
||||
SLACK_BOT_TOKEN=xoxb-your-bot-token
|
||||
SLACK_SIGNING_SECRET=your-signing-secret
|
||||
```
|
||||
|
||||
Walk the operator through creating the Slack app, then collect the secrets it
|
||||
hands back. The adapter is already installed and registered — it just can't
|
||||
receive a message until this is done. For Socket Mode, tell the user:
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
```nc:operator when:connection=socket
|
||||
Create the Slack app (Socket Mode):
|
||||
1. Go to api.slack.com/apps → Create New App → From scratch. Name it (e.g. "NanoClaw") and pick your workspace.
|
||||
2. OAuth & Permissions → add these Bot Token Scopes: chat:write, im:write, channels:history, groups:history, im:history, channels:read, groups:read, users:read, reactions:write, files:read, files:write.
|
||||
3. App Home → enable the Messages Tab, and check "Allow users to send Slash commands and messages from the messages tab."
|
||||
4. Basic Information → App-Level Tokens → "Generate Token and Scopes" → add the connections:write scope → copy the token (starts with xapp-).
|
||||
5. Socket Mode → toggle "Enable Socket Mode" on.
|
||||
6. Install to Workspace, then copy the Bot User OAuth Token (starts with xoxb-).
|
||||
```
|
||||
### Webhook server
|
||||
|
||||
For webhook delivery, tell the user:
|
||||
The Chat SDK bridge automatically starts a shared webhook server on port 3000 (configurable via `WEBHOOK_PORT` env var). The server handles `/webhook/slack` for Slack and other webhook-based adapters. This port must be publicly reachable from the internet for Slack to deliver events.
|
||||
|
||||
```nc:operator when:connection=webhook
|
||||
Create the Slack app (webhook delivery):
|
||||
1. Go to api.slack.com/apps → Create New App → From scratch. Name it (e.g. "NanoClaw") and pick your workspace.
|
||||
2. OAuth & Permissions → add these Bot Token Scopes: chat:write, im:write, channels:history, groups:history, im:history, channels:read, groups:read, users:read, reactions:write, files:read, files:write.
|
||||
3. App Home → enable the Messages Tab, and check "Allow users to send Slash commands and messages from the messages tab."
|
||||
4. Install to Workspace, then copy the Bot User OAuth Token (starts with xoxb-).
|
||||
5. Basic Information → copy the Signing Secret.
|
||||
```
|
||||
|
||||
Collect the secrets and store them (the bridge reads them from `.env`; the
|
||||
app-level token doubles as the Socket Mode switch, the signing secret
|
||||
authenticates webhook requests — each mode needs only its own):
|
||||
|
||||
```nc:prompt bot_token secret validate:^xoxb-
|
||||
Paste the Bot User OAuth Token — OAuth & Permissions, starts with `xoxb-`.
|
||||
```
|
||||
```nc:prompt app_token secret validate:^xapp- reuse:SLACK_APP_TOKEN when:connection=socket
|
||||
Paste the App-Level Token — Basic Information → App-Level Tokens, starts with `xapp-`.
|
||||
```
|
||||
```nc:prompt signing_secret secret validate:^[a-fA-F0-9]{16,}$ when:connection=webhook
|
||||
Paste the Signing Secret — Basic Information.
|
||||
```
|
||||
```nc:env-set
|
||||
SLACK_BOT_TOKEN={{bot_token}}
|
||||
```
|
||||
```nc:env-set when:connection=socket
|
||||
SLACK_APP_TOKEN={{app_token}}
|
||||
```
|
||||
```nc:env-set when:connection=webhook
|
||||
SLACK_SIGNING_SECRET={{signing_secret}}
|
||||
```
|
||||
|
||||
With webhook delivery, the bridge serves port 3000 at `/webhook/slack`
|
||||
automatically; to receive replies, that port must be reachable from the internet
|
||||
and registered with Slack (Socket Mode skips all of this — events arrive over
|
||||
the socket as soon as the service restarts). Tell the user:
|
||||
|
||||
```nc:operator when:connection=webhook
|
||||
Set up event delivery (needs a public HTTPS URL for port 3000 — ngrok, a Cloudflare Tunnel, or a reverse proxy on a VPS):
|
||||
1. Event Subscriptions → Enable Events. Set the Request URL to https://<your-public-host>/webhook/slack and wait for the challenge to pass.
|
||||
2. Subscribe to bot events: message.channels, message.groups, message.im, app_mention. Save Changes.
|
||||
3. Interactivity & Shortcuts → toggle Interactivity on, set the same Request URL, Save Changes, then reinstall the app when Slack prompts.
|
||||
```
|
||||
|
||||
## Resolve your DM channel
|
||||
|
||||
The agent talks to you in your direct-message channel with the bot. Resolve its
|
||||
address so the owner-wiring step can target it. Validating the token here, before
|
||||
the restart, fast-fails a bad credential while it's still cheap to fix. You'll
|
||||
need your Slack member ID: open your profile (your avatar, bottom-left), then
|
||||
**⋮** → **Copy member ID** — it starts with `U`.
|
||||
|
||||
```nc:prompt owner_handle validate:^U[A-Z0-9]{8,}$
|
||||
Your Slack member ID (Profile → ⋮ → "Copy member ID"; starts with U).
|
||||
```
|
||||
|
||||
Confirm the bot token works and capture the bot identity — `auth.test` returns the
|
||||
bot user and workspace, and fails here if the token is bad:
|
||||
|
||||
```nc:run capture:connected_as effect:fetch
|
||||
curl -sf -X POST https://slack.com/api/auth.test -H "Authorization: Bearer {{bot_token}}" | jq -er '"@" + .user + " in " + .team'
|
||||
```
|
||||
|
||||
Open the DM with `conversations.open` and take the channel id it returns as the
|
||||
conversation address `slack:<channelId>` (if Slack returns no channel, the bot is
|
||||
missing the `im:write` scope — add it and reinstall):
|
||||
|
||||
```nc:run capture:platform_id effect:fetch
|
||||
curl -s -X POST https://slack.com/api/conversations.open -H "Authorization: Bearer {{bot_token}}" -H "Content-Type: application/json" -d '{"users":"{{owner_handle}}"}' | jq -er '"slack:" + .channel.id'
|
||||
```
|
||||
|
||||
`owner_handle` and `platform_id` are what the owner-wiring step needs. The
|
||||
greeting goes out over `chat.postMessage`, which works right away. Receiving
|
||||
replies needs the event path live: with Socket Mode that happens as soon as the
|
||||
service restarts below; with webhook delivery, finish the Event Subscriptions
|
||||
and Interactivity steps above first.
|
||||
|
||||
## Restart
|
||||
|
||||
With the credential validated, restart the service so it loads the Slack adapter
|
||||
and the secrets you just stored, and wait for its CLI socket before wiring:
|
||||
|
||||
```nc:run effect:restart
|
||||
bash setup/lib/restart.sh
|
||||
```
|
||||
If running locally, discuss options for exposing the server — e.g. ngrok (`ngrok http 3000`), Cloudflare Tunnel, or a reverse proxy on a VPS. The resulting public URL becomes the base for `https://your-domain/webhook/slack`.
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now. Otherwise wire
|
||||
this channel with `/init-first-agent` (or `/manage-channels`).
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
|
||||
@@ -18,38 +18,26 @@ rm -f src/channels/teams.ts src/channels/teams-registration.test.ts
|
||||
|
||||
## 2. Remove credentials
|
||||
|
||||
Remove `TEAMS_APP_ID`, `TEAMS_APP_PASSWORD`, `TEAMS_APP_TENANT_ID`, and `TEAMS_APP_TYPE` from `.env`.
|
||||
|
||||
## 3. Sign out the Teams CLI, then remove the packages
|
||||
|
||||
`teams login` caches a Microsoft 365 session on disk that outlives the package —
|
||||
sign out first (skip if the CLI was never installed):
|
||||
Remove the `TEAMS_*` lines from `.env`, then re-sync to the container:
|
||||
|
||||
```bash
|
||||
TEAMS_APP_ID
|
||||
TEAMS_APP_PASSWORD
|
||||
TEAMS_APP_TENANT_ID
|
||||
TEAMS_APP_TYPE
|
||||
```
|
||||
|
||||
```bash
|
||||
mkdir -p data/env && cp .env data/env/env
|
||||
```
|
||||
|
||||
## 3. Remove the package
|
||||
|
||||
```bash
|
||||
teams logout
|
||||
npm uninstall -g @microsoft/teams.cli
|
||||
pnpm uninstall @chat-adapter/teams
|
||||
```
|
||||
|
||||
## 4. Remove local artifacts
|
||||
|
||||
```bash
|
||||
rm -rf data/teams
|
||||
```
|
||||
|
||||
## 5. Clean up cloud resources
|
||||
|
||||
Uninstall the app from Teams (Apps > Manage your apps). Then, on **both**
|
||||
paths, delete the Entra app registration in Azure Portal > App registrations —
|
||||
that is the step that actually revokes the client secret. Additionally:
|
||||
|
||||
- **Teams CLI path**: delete the app listing in the Teams Developer Portal
|
||||
(https://dev.teams.microsoft.com/apps) — removing it there alone does NOT
|
||||
revoke the secret.
|
||||
- **Manual Azure path**: delete the Azure Bot resource, and the `nanoclaw-rg`
|
||||
resource group if you created one (`az group delete --name nanoclaw-rg`).
|
||||
|
||||
## 6. Rebuild and restart
|
||||
## 4. Rebuild and restart
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
|
||||
+189
-518
@@ -5,580 +5,251 @@ description: Add Microsoft Teams channel integration via Chat SDK.
|
||||
|
||||
# Add Microsoft Teams Channel
|
||||
|
||||
Adds Microsoft Teams support via the Chat SDK bridge — interactive chat in team
|
||||
channels, group chats, and direct messages. NanoClaw doesn't ship channels in
|
||||
trunk — this skill copies the Teams adapter in from the `channels` branch.
|
||||
Connect NanoClaw to Microsoft Teams for interactive chat in team channels, group chats, and direct messages.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent
|
||||
reads the prose and applies them, and a parser can apply them deterministically
|
||||
from the same document. Every directive is idempotent, so the whole skill is
|
||||
safe to re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
Teams has no "paste a token" shortcut — a bot has to exist in Microsoft's cloud
|
||||
before it can receive a message. The Microsoft Teams CLI collapses that into
|
||||
one sign-in and one create command: it registers the Entra app, generates the
|
||||
client secret, registers a Teams-managed bot (through the Teams Developer
|
||||
Portal — **no Azure subscription needed**), uploads the app package, and hands
|
||||
back an install link. The old ~7-step Azure portal walk survives only as a
|
||||
fallback in [Alternatives](#alternatives) for tenants where the Developer
|
||||
Portal is blocked.
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the Teams adapter in from the `channels` branch.
|
||||
|
||||
## Apply
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
### 1. Copy the adapter and its registration test
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
Fetch the `channels` branch and copy the Teams adapter and its registration test
|
||||
into `src/channels/` (overwrite — the branch is canonical):
|
||||
- `src/channels/teams.ts` exists
|
||||
- `src/channels/teams-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './teams.js';`
|
||||
- `@chat-adapter/teams` is listed in `package.json` dependencies
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/teams.ts
|
||||
src/channels/teams-registration.test.ts
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/teams.ts > src/channels/teams.ts
|
||||
git show origin/channels:src/channels/teams-registration.test.ts > src/channels/teams-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './teams.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
@chat-adapter/teams@4.29.0
|
||||
```bash
|
||||
pnpm install @chat-adapter/teams@4.29.0
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Build and validate
|
||||
|
||||
Build first: it guards the typed `createChatSdkBridge(...)` core call and proves
|
||||
the dependency is installed. Then run the one integration test.
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/teams-registration.test.ts
|
||||
```
|
||||
|
||||
`teams-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `teams`. It goes red if the import line is deleted or drifts,
|
||||
if the barrel fails to evaluate, or if `@chat-adapter/teams` isn't installed (the
|
||||
import throws) — so it also covers the dependency from step 3. End-to-end
|
||||
delivery against a real Teams workspace is verified manually once the service
|
||||
runs.
|
||||
Both must be clean before proceeding. `teams-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `teams`. It goes red if the `import './teams.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/teams` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
End-to-end message delivery against a real Teams workspace is verified manually once the service is running — see Next Steps and the webhook setup above.
|
||||
|
||||
## Credentials
|
||||
|
||||
The adapter is installed and registered, but it can't receive a message until a
|
||||
bot exists, points at this machine, and is installed into Teams. The Teams CLI
|
||||
does all of that below.
|
||||
Two paths — manual (Azure Portal) or auto (Teams CLI).
|
||||
|
||||
### Check for existing credentials
|
||||
### Auto: Teams CLI
|
||||
|
||||
Re-running `teams app create` provisions a brand-new app registration and bot
|
||||
each time — it never reuses the first one. So the flow starts with a probe:
|
||||
when `.env` already carries a Teams credential — either key; a partial pair
|
||||
means a half-finished setup that creating ANOTHER app would only corrupt —
|
||||
every step below (prompts included) is skipped and the flow drops straight
|
||||
through to [Restart](#restart). To rotate credentials or finish a partial
|
||||
configuration, see [Troubleshooting](#troubleshooting); if your tunnel URL
|
||||
changed, the fix is `teams app update`, not a re-run (also in Troubleshooting).
|
||||
Requires Node.js 18+, a Microsoft 365 account with sideloading permissions, and a public HTTPS endpoint (ngrok, Cloudflare Tunnel, or similar).
|
||||
|
||||
```nc:run capture:have_creds
|
||||
( grep -q '^TEAMS_APP_ID=.' .env 2>/dev/null || grep -q '^TEAMS_APP_PASSWORD=.' .env 2>/dev/null ) && echo yes || echo no
|
||||
1. Install the CLI:
|
||||
|
||||
```bash
|
||||
npm install -g @microsoft/teams.cli@preview
|
||||
```
|
||||
|
||||
2. Sign in and verify:
|
||||
|
||||
```bash
|
||||
teams login
|
||||
teams status
|
||||
```
|
||||
|
||||
3. Create the Entra app, client secret, and bot registration:
|
||||
|
||||
```bash
|
||||
teams app create \
|
||||
--name "NanoClaw" \
|
||||
--endpoint "https://your-domain/api/webhooks/teams"
|
||||
```
|
||||
|
||||
The CLI prints the credentials as `CLIENT_ID`, `CLIENT_SECRET`, and `TENANT_ID`. Map them to NanoClaw's env keys:
|
||||
|
||||
- `CLIENT_ID` → `TEAMS_APP_ID`
|
||||
- `CLIENT_SECRET` → `TEAMS_APP_PASSWORD`
|
||||
- `TENANT_ID` → `TEAMS_APP_TENANT_ID`
|
||||
|
||||
4. Pick **Install in Teams** from the post-create menu and confirm in the Teams dialog.
|
||||
|
||||
Continue to [Configure environment](#configure-environment).
|
||||
|
||||
---
|
||||
|
||||
The steps below describe the **manual Azure Portal path**.
|
||||
|
||||
### Step 1: Create an Azure AD App Registration
|
||||
|
||||
1. Go to [Azure Portal](https://portal.azure.com) > **App registrations** > **New registration**
|
||||
2. Name it (e.g., "NanoClaw")
|
||||
3. Supported account types: **Single tenant** (your org only) or **Multi tenant** (any org)
|
||||
4. Click **Register**
|
||||
5. Copy the **Application (client) ID** and **Directory (tenant) ID** from the Overview page
|
||||
|
||||
### Step 2: Create a Client Secret
|
||||
|
||||
1. In the App Registration, go to **Certificates & secrets**
|
||||
2. Click **New client secret**, description "nanoclaw", expiry 180 days
|
||||
3. Click **Add** and **copy the Value immediately** (shown only once)
|
||||
|
||||
### Step 3: Create an Azure Bot
|
||||
|
||||
1. Go to Azure Portal > search **Azure Bot** > **Create**
|
||||
2. Fill in:
|
||||
- **Bot handle**: unique name (e.g., "nanoclaw-bot")
|
||||
- **Type of App**: match your app registration (Single or Multi Tenant)
|
||||
- **Creation type**: **Use existing app registration**
|
||||
- **App ID**: paste from Step 1
|
||||
- **App tenant ID**: paste from Step 1 (Single Tenant only)
|
||||
3. Click **Review + create** > **Create**
|
||||
|
||||
Or use Azure CLI:
|
||||
|
||||
```bash
|
||||
az group create --name nanoclaw-rg --location eastus
|
||||
az bot create \
|
||||
--resource-group nanoclaw-rg \
|
||||
--name nanoclaw-bot \
|
||||
--app-type SingleTenant \
|
||||
--appid YOUR_APP_ID \
|
||||
--tenant-id YOUR_TENANT_ID \
|
||||
--endpoint "https://your-domain/api/webhooks/teams"
|
||||
```
|
||||
|
||||
Before creating anything, tell the user:
|
||||
### Step 4: Configure Messaging Endpoint
|
||||
|
||||
```nc:operator when:have_creds=no
|
||||
Confirm you have everything Teams setup needs:
|
||||
1. A Microsoft 365 account that can create Entra app registrations and upload custom apps (sideloading) — free personal Teams does NOT qualify; you need a Microsoft 365 Business / EDU / developer tenant.
|
||||
2. A way to expose an HTTPS endpoint that forwards to this machine's webhook port 3000 (e.g. a Cloudflare Tunnel, or a reverse-proxied VPS). Start it now if it isn't running — e.g. `cloudflared tunnel --url http://localhost:3000` — the create step needs the URL up front. The next prompt asks for its public base URL: just the https:// origin, no trailing path.
|
||||
Note: the bot is created single-tenant (only your own Microsoft 365 tenant can install it) — the right default for a self-hosted assistant. If you need a bot other tenants can install, set it up manually via the Alternatives section of this skill instead.
|
||||
1. Go to your Azure Bot resource > **Configuration**
|
||||
2. Set **Messaging endpoint** to `https://your-domain/api/webhooks/teams`
|
||||
3. Click **Apply**
|
||||
|
||||
### Step 5: Enable Teams Channel
|
||||
|
||||
1. In the Azure Bot resource, go to **Channels**
|
||||
2. Click **Microsoft Teams** > Accept terms > **Apply**
|
||||
|
||||
Or via CLI:
|
||||
|
||||
```bash
|
||||
az bot msteams create --resource-group nanoclaw-rg --name nanoclaw-bot
|
||||
```
|
||||
|
||||
### Public URL
|
||||
### Step 6: Create and Sideload Teams App
|
||||
|
||||
Microsoft delivers bot messages to an HTTPS endpoint you control; it has to
|
||||
reach this machine's webhook server (port 3000, configurable via
|
||||
`WEBHOOK_PORT`) at `/webhook/teams`.
|
||||
Create a `manifest.json`:
|
||||
|
||||
```nc:prompt public_url when:have_creds=no validate:^https:// normalize:rstrip-slash
|
||||
Paste your tunnel's public https:// URL — e.g. https://your-tunnel.trycloudflare.com
|
||||
```json
|
||||
{
|
||||
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
|
||||
"manifestVersion": "1.16",
|
||||
"version": "1.0.0",
|
||||
"id": "YOUR_APP_ID",
|
||||
"packageName": "com.nanoclaw.bot",
|
||||
"developer": {
|
||||
"name": "NanoClaw",
|
||||
"websiteUrl": "https://your-domain",
|
||||
"privacyUrl": "https://your-domain",
|
||||
"termsOfUseUrl": "https://your-domain"
|
||||
},
|
||||
"name": { "short": "NanoClaw", "full": "NanoClaw Assistant" },
|
||||
"description": {
|
||||
"short": "NanoClaw assistant bot",
|
||||
"full": "NanoClaw personal assistant powered by Claude."
|
||||
},
|
||||
"icons": { "outline": "outline.png", "color": "color.png" },
|
||||
"accentColor": "#4A90D9",
|
||||
"bots": [{
|
||||
"botId": "YOUR_APP_ID",
|
||||
"scopes": ["personal", "team", "groupchat"],
|
||||
"supportsFiles": false,
|
||||
"isNotificationOnly": false
|
||||
}],
|
||||
"permissions": ["identity", "messageTeamMembers"],
|
||||
"validDomains": ["your-domain"]
|
||||
}
|
||||
```
|
||||
|
||||
### App name
|
||||
Create two icon PNGs (32x32 `outline.png`, 192x192 `color.png`), zip all three files together.
|
||||
|
||||
One more choice belongs to the human before anything is created. The name is
|
||||
used everywhere at once: the Entra app registration, the bot, and the Teams
|
||||
app are all created under it. There is no client-secret name to pick on this
|
||||
path — the CLI generates the secret itself (Entra displayName `default`,
|
||||
2-year expiry); rotating it later is in [Troubleshooting](#troubleshooting).
|
||||
**Sideload in Teams:**
|
||||
1. Open Teams > **Apps** > **Manage your apps**
|
||||
2. Click **Upload an app** > **Upload a custom app**
|
||||
3. Select the zip file
|
||||
|
||||
```nc:prompt app_name when:have_creds=no validate:^[\sA-Za-z0-9._-]{1,30}$ normalize:trim
|
||||
What should the bot be called? One name covers the Entra app registration, the bot, and the Teams app (letters, digits, spaces, . _ -; max 30 characters) — e.g. NanoClaw.
|
||||
Sideloading requires Teams admin access. Free personal Teams does NOT support sideloading. Use a Microsoft 365 Business account or developer tenant.
|
||||
|
||||
### Step 7: Receive All Messages (Optional)
|
||||
|
||||
By default, the bot only receives messages when @-mentioned. To receive all messages in a channel without @-mention, add RSC permissions to `manifest.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"authorization": {
|
||||
"permissions": {
|
||||
"resourceSpecific": [
|
||||
{ "name": "ChannelMessage.Read.Group", "type": "Application" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Install the Teams CLI
|
||||
### Configure environment
|
||||
|
||||
Installed globally with npm — not as a workspace dependency — deliberately:
|
||||
the CLI's credential store (keytar) is a native module whose install script
|
||||
must run to fetch its prebuilt binary, and pnpm's supply-chain policy blocks
|
||||
dependency build scripts — a workspace install leaves the sign-in unable to
|
||||
persist. The global install matches Microsoft's own instruction and keeps the
|
||||
workspace policy intact. Pinned; re-running is a no-op. (If npm reports
|
||||
EACCES here, your global prefix needs root — prefer a user-level Node like
|
||||
nvm, or `npm config set prefix ~/.npm-global`.) `--loglevel=error` because
|
||||
npm runs inside a pnpm script here and warns about every pnpm config var it
|
||||
inherits — pure noise; real errors still print.
|
||||
Add to `.env`:
|
||||
|
||||
```nc:run effect:external when:have_creds=no
|
||||
npm install -g @microsoft/teams.cli@3.0.2 --loglevel=error
|
||||
```
|
||||
|
||||
npm's global bin directory is not reliably on PATH (custom prefixes rarely
|
||||
are), so every step below calls the CLI by its absolute path,
|
||||
`$(npm prefix -g)/bin/teams` (stderr of the prefix lookup silenced — same
|
||||
pnpm-config noise as above). Where this document says to run `teams …` by
|
||||
hand, use that path too if plain `teams` isn't found.
|
||||
|
||||
### Sign in to Microsoft 365
|
||||
|
||||
Every `teams` command is a separate process, so the sign-in must survive into
|
||||
the next one via the CLI's on-disk token cache. A "libsecret not found —
|
||||
token cache will be stored unencrypted" warning here is safe to ignore: the
|
||||
CLI falls back to a plaintext cache file that persists fine, and setup signs
|
||||
the session out at the end anyway. The login output may
|
||||
also report "Azure CLI: not installed" — informational only; this flow
|
||||
creates a Teams-managed bot precisely so the Azure CLI is never needed (it
|
||||
only matters for `--azure` bots and the manual portal path). The
|
||||
step below verifies persistence by re-reading the session from a fresh
|
||||
process after login. In an interactive terminal the login opens a browser;
|
||||
on a headless box (SSH) it prints a device code — open
|
||||
microsoft.com/devicelogin on any machine and enter it. If this step fails,
|
||||
run `teams login` then `teams status` by hand: status must say logged in, or
|
||||
the cache is not persisting (see Troubleshooting).
|
||||
|
||||
```nc:run effect:step when:have_creds=no
|
||||
"$(npm prefix -g 2>/dev/null)/bin/teams" login && "$(npm prefix -g 2>/dev/null)/bin/teams" status --json 2>/dev/null | grep -q '"loggedIn": true' && printf '=== NANOCLAW SETUP: TEAMS-LOGIN ===\nSTATUS: success\n=== END ===\n'
|
||||
```
|
||||
|
||||
### Create the bot
|
||||
|
||||
One command registers the Entra app, generates a client secret (Graph can take
|
||||
~30s to see the new app — the CLI retries), registers a Teams-managed bot, and
|
||||
uploads the app package to the Teams Developer Portal. It needs the sign-in
|
||||
from the previous step (`AUTH_REQUIRED` means run that first). The bot is
|
||||
always created single-tenant (`--sign-in-audience myOrg`) — the right default
|
||||
for a self-hosted assistant, applied without asking; for a bot other
|
||||
Microsoft 365 tenants can install, set it up manually per
|
||||
[Alternatives](#alternatives).
|
||||
|
||||
```nc:run effect:external when:have_creds=no capture:app_id=.credentials.CLIENT_ID,app_password=.credentials.CLIENT_SECRET,app_tenant_id=.credentials.TENANT_ID,teams_app_id=.teamsAppId,install_link=.installLink validate:^.+$
|
||||
"$(npm prefix -g 2>/dev/null)/bin/teams" app create --name "{{app_name}}" --endpoint "{{public_url}}/webhook/teams" --sign-in-audience myOrg --json
|
||||
```
|
||||
|
||||
### Store the credentials
|
||||
|
||||
The adapter reads these from `.env` (set-if-absent — a value you've already
|
||||
filled in is never overwritten). The pairing matters: `SingleTenant` requires
|
||||
`TEAMS_APP_TENANT_ID`, and a multi-tenant app must instead set
|
||||
`TEAMS_APP_TYPE=MultiTenant` with **no** tenant ID — a mismatch makes the
|
||||
adapter authenticate against the wrong authority and every message fails with
|
||||
a 401 from Bot Framework.
|
||||
|
||||
```nc:env-set when:have_creds=no
|
||||
TEAMS_APP_ID={{app_id}}
|
||||
TEAMS_APP_PASSWORD={{app_password}}
|
||||
TEAMS_APP_TENANT_ID={{app_tenant_id}}
|
||||
```bash
|
||||
TEAMS_APP_ID=your-app-id
|
||||
TEAMS_APP_PASSWORD=your-client-secret
|
||||
# For Single Tenant only:
|
||||
TEAMS_APP_TENANT_ID=your-tenant-id
|
||||
TEAMS_APP_TYPE=SingleTenant
|
||||
```
|
||||
|
||||
### Set the app icons
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
The CLI-created app ships with placeholder icons; this swaps in the NanoClaw
|
||||
mascot (the same PNGs the manual-path package bakes into its zip), so the
|
||||
install dialog below already shows it. Cosmetic — a failure is logged and
|
||||
skipped, never blocking setup. Re-runnable any time while signed in to the
|
||||
Teams CLI:
|
||||
### Webhook server
|
||||
|
||||
```nc:run effect:external when:have_creds=no
|
||||
"$(npm prefix -g 2>/dev/null)/bin/teams" app update {{teams_app_id}} --color-icon setup/assets/teams/color.png --outline-icon setup/assets/teams/outline.png --json || echo "Icon update failed — cosmetic only, continuing."
|
||||
```
|
||||
The Chat SDK bridge automatically starts a shared webhook server on port 3000 (configurable via `WEBHOOK_PORT` env var). The server handles `/api/webhooks/teams` for Teams and other webhook-based adapters. This port must be publicly reachable from the internet for Azure Bot Service to deliver activities.
|
||||
|
||||
### Who owns this bot
|
||||
|
||||
The account signed into the Teams CLI is the account that just created the
|
||||
bot — that human is the wiring target this flow suggests. Its identity comes
|
||||
from the CLI session, so this runs before the sign-out step below:
|
||||
|
||||
```nc:run effect:fetch when:have_creds=no capture:owner_upn=.username,owner_aad_id=.userObjectId validate:^.+$
|
||||
"$(npm prefix -g 2>/dev/null)/bin/teams" status --json 2>/dev/null
|
||||
```
|
||||
|
||||
### Confirm the wiring target
|
||||
|
||||
Nothing is wired without a confirmed target, and someone is always wired —
|
||||
there is no skip. The account signed into the Teams CLI is often NOT the
|
||||
person setting up NanoClaw, so a no leads to a clarifying choice: wire the
|
||||
logged-in Teams user after all, or a different Teams user by Microsoft Entra
|
||||
object ID. Identities are shown by sign-in name, never a raw ID:
|
||||
|
||||
```nc:operator when:have_creds=no
|
||||
Detected the account that created the bot: {{owner_upn}}. Wiring the assistant to it means its first message arrives in that account's Teams DMs.
|
||||
```
|
||||
|
||||
```nc:prompt wire_owner when:have_creds=no validate:^(yes|no)$ normalize:lower
|
||||
Wire the assistant to this account?
|
||||
```
|
||||
|
||||
```nc:operator when:wire_owner=no
|
||||
You're currently logged in to Teams as {{owner_upn}}.
|
||||
- To wire the assistant to this logged-in Teams user, choose "logged-in-account".
|
||||
- To wire a different Teams user, get their Microsoft Entra object ID — found at entra.microsoft.com > Users > (person) > Overview > Object ID, or Teams admin center > Manage users — and choose "other-account". Once wired, the assistant messages them first.
|
||||
```
|
||||
|
||||
```nc:prompt wire_target when:wire_owner=no validate:^(logged-in-account|other-account)$ normalize:lower
|
||||
Which Teams user should the assistant be wired to?
|
||||
```
|
||||
|
||||
```nc:prompt target_aad_id when:wire_target=other-account validate:^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ normalize:trim
|
||||
Paste the Microsoft Entra object ID of the Teams user to wire (a GUID like 00000000-0000-0000-0000-000000000000).
|
||||
```
|
||||
|
||||
Either choice re-enters the exact same path as a yes above — rebind the
|
||||
wiring target and flip the branch, so the link chain below needs no second
|
||||
copy per branch:
|
||||
|
||||
```nc:run when:wire_target=other-account capture:owner_aad_id=.aad,wire_owner=.wire validate:^.+$
|
||||
printf '{"aad":"%s","wire":"yes"}' "{{target_aad_id}}"
|
||||
```
|
||||
|
||||
```nc:run when:wire_target=logged-in-account capture:wire_owner validate:^yes$
|
||||
echo yes
|
||||
```
|
||||
|
||||
### Install the app in Teams
|
||||
|
||||
The app package is already uploaded — no manifest zip, no manual sideload.
|
||||
Tell the user:
|
||||
|
||||
```nc:operator when:have_creds=no
|
||||
Install the bot into Teams:
|
||||
1. Open {{install_link}} — Teams opens with the app's install dialog. Click Add.
|
||||
2. If you need the link again later, run: teams app get {{teams_app_id}} --install-link
|
||||
3. If Teams refuses with a custom-app-upload error, a tenant admin must enable sideloading: Teams Admin Center > Teams apps > Setup policies > Global > "Upload custom apps" = On.
|
||||
Once the app shows up in your Teams sidebar (or app list), continue.
|
||||
```
|
||||
|
||||
### Link the bot to your account
|
||||
|
||||
Nothing to do in Teams yet — these are background API calls, and the whole
|
||||
chain runs only for a confirmed target from
|
||||
[Confirm the wiring target](#confirm-the-wiring-target) (the detected owner
|
||||
on a yes, or the provided Entra object ID). Same move as
|
||||
Slack's `conversations.open` and Discord's `users/@me/channels`:
|
||||
create the bot↔owner 1:1 conversation proactively with the bot's own
|
||||
credentials, so the assistant messages the human first — nobody has to DM the
|
||||
bot to bootstrap it. This only works now that the app is installed (the step
|
||||
above); if Microsoft hasn't finished propagating the install yet, the create
|
||||
below can fail once — re-running the skill is safe.
|
||||
|
||||
First a Bot Framework token from the app credentials:
|
||||
|
||||
```nc:run effect:fetch when:wire_owner=yes capture:bot_token validate:^eyJ
|
||||
curl -sf -X POST "https://login.microsoftonline.com/{{app_tenant_id}}/oauth2/v2.0/token" --data-urlencode "grant_type=client_credentials" --data-urlencode "client_id={{app_id}}" --data-urlencode "client_secret={{app_password}}" --data-urlencode "scope=https://api.botframework.com/.default" | jq -er '.access_token'
|
||||
```
|
||||
|
||||
Create the 1:1 conversation (the AAD object id from the CLI session is a
|
||||
valid member id; `smba.trafficmanager.net/teams` is the global service URL —
|
||||
the same default the adapter itself uses):
|
||||
|
||||
```nc:run effect:fetch when:wire_owner=yes capture:conversation_id validate:^.+$
|
||||
curl -sf -X POST "https://smba.trafficmanager.net/teams/v3/conversations" -H "Authorization: Bearer {{bot_token}}" -H "Content-Type: application/json" -d '{"bot":{"id":"28:{{app_id}}"},"members":[{"id":"{{owner_aad_id}}","name":"","role":"user"}],"tenantId":"{{app_tenant_id}}","channelData":{"tenant":{"id":"{{app_tenant_id}}"}},"isGroup":false}' | jq -er '.id'
|
||||
```
|
||||
|
||||
The adapter identifies inbound senders by their Bot Framework `29:` id, not
|
||||
the AAD id — the owner must be wired under that handle or their replies
|
||||
would not be recognized. The conversation was created with exactly one
|
||||
member (the owner), so its member list is the owner by construction; the
|
||||
filter only guards against channels that list the bot itself (`28:` ids).
|
||||
(Don't select by `.aadObjectId` here — the field is not reliably present in
|
||||
this response and its GUID casing varies.)
|
||||
|
||||
```nc:run effect:fetch when:wire_owner=yes capture:owner_handle=.id,owner_name=.name validate:^.+$
|
||||
curl -sf "https://smba.trafficmanager.net/teams/v3/conversations/{{conversation_id}}/members" -H "Authorization: Bearer {{bot_token}}" | jq -er '[.[] | select((.id // "") | startswith("28:") | not)][0] | {id, name: (.name // .givenName // "Teams user")}'
|
||||
```
|
||||
|
||||
Compose the platform id exactly as the adapter encodes thread ids
|
||||
(`teams:{b64url conversation}:{b64url service url}`):
|
||||
|
||||
```nc:run when:wire_owner=yes capture:platform_id validate:^teams:
|
||||
node -e 'const c=process.argv[1];const s="https://smba.trafficmanager.net/teams/";console.log("teams:"+Buffer.from(c).toString("base64url")+":"+Buffer.from(s).toString("base64url"))' "{{conversation_id}}"
|
||||
```
|
||||
|
||||
### Sign out of the Teams CLI
|
||||
|
||||
The Microsoft 365 session was only needed to create the bot and identify its
|
||||
owner — the running adapter authenticates with the app credentials in
|
||||
`.env`, never with your account. On a headless box that session is a
|
||||
plaintext token file, which is worth removing unless you plan more `teams …`
|
||||
commands (rotate secret, endpoint update, RSC — each just needs a fresh
|
||||
`teams login`, a ~30-second device code):
|
||||
|
||||
```nc:prompt signout when:have_creds=no validate:^(yes|no)$ normalize:lower
|
||||
Sign out of the Teams CLI now? The bot doesn't need this login to run — signing out is recommended on shared or headless boxes, and `teams login` gets you back any time.
|
||||
```
|
||||
|
||||
```nc:run effect:external when:signout=yes
|
||||
"$(npm prefix -g 2>/dev/null)/bin/teams" logout
|
||||
```
|
||||
|
||||
## Restart
|
||||
|
||||
Restart the service so it loads the Teams adapter and the credentials you just
|
||||
stored:
|
||||
|
||||
```nc:run effect:restart
|
||||
bash setup/lib/restart.sh
|
||||
```
|
||||
|
||||
## Finish wiring
|
||||
|
||||
On a fresh create, [Link the bot to your account](#link-the-bot-to-your-account) already resolved
|
||||
everything the wire needs — `owner_handle` (the owner's `29:` id) and
|
||||
`platform_id` (the bot↔owner DM). The setup wizard wires automatically from
|
||||
those and the welcome message lands in the owner's Teams DMs. Applying this
|
||||
skill outside the wizard? Run the same wire yourself:
|
||||
|
||||
```bash
|
||||
pnpm exec tsx scripts/init-first-agent.ts --channel teams --user-id "teams:<owner_handle>" --platform-id "<platform_id>" --display-name "<the human's name>" --agent-name "<assistant name>" --role owner
|
||||
```
|
||||
|
||||
**Fallback (re-runs, or the link step failed):** with credentials already in
|
||||
`.env` the resolve steps are skipped, so there is nothing new to wire — the
|
||||
first run's wiring still stands. If the install was never wired at all, the
|
||||
DM-first path always works: DM the bot once ("hi" is fine) — the router
|
||||
auto-creates the messaging group row in `data/v2.db` from that first inbound
|
||||
— then run `/init-first-agent` (or `/manage-channels`) with your coding
|
||||
agent.
|
||||
For local development without a public URL, use a tunnel (e.g., `ngrok http 3000`) and update the messaging endpoint in Azure Bot Configuration.
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now — it wires
|
||||
the owner automatically from the resolved values. Otherwise wire per
|
||||
[Finish wiring](#finish-wiring).
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
- **type**: `teams`
|
||||
- **terminology**: Teams has "teams" containing "channels." The bot can also receive DMs (personal scope) and group chat messages. Channels support threaded replies.
|
||||
- **platform-id-format**: `teams:{base64url-conversation-id}:{base64url-service-url}` — auto-generated by the adapter from the first inbound activity, not human-readable. Use the auto-created messaging group for wiring.
|
||||
- **how-to-find-id**: Send a message to the bot in the channel or a DM. NanoClaw auto-creates a messaging group and logs the platform ID. Use that messaging group for wiring.
|
||||
- **platform-id-format**: `teams:{base64-encoded-conversation-id}:{base64-encoded-service-url}` — auto-generated by the adapter, not human-readable. Use the auto-created messaging group ID for wiring.
|
||||
- **how-to-find-id**: Send a message to the bot in the channel. NanoClaw auto-creates a messaging group and logs the platform ID. Use that messaging group ID for wiring.
|
||||
- **supports-threads**: yes (channels only; DMs and group chats are flat)
|
||||
- **typical-use**: Team collaboration with the bot in channels; personal assistant via DMs
|
||||
- **default-isolation**: Separate agent group per team. DMs can share an agent group with your main channel for unified personal memory.
|
||||
|
||||
## Alternatives
|
||||
|
||||
### Multi-tenant bot
|
||||
|
||||
The Credentials flow above always creates a single-tenant bot (only your
|
||||
Microsoft 365 tenant can install it) — the right default for a self-hosted
|
||||
assistant, so the skill doesn't ask. For a bot any tenant can install, run
|
||||
the create by hand with `multipleOrgs` and store the matching env pairing —
|
||||
`MultiTenant` with **no** tenant ID (the same 401 pairing rule from the
|
||||
credentials step):
|
||||
|
||||
```bash
|
||||
"$(npm prefix -g)/bin/teams" app create --name "YourBot" --endpoint "https://your-domain/webhook/teams" --sign-in-audience multipleOrgs --json
|
||||
```
|
||||
|
||||
```bash
|
||||
TEAMS_APP_ID=<CLIENT_ID from the output>
|
||||
TEAMS_APP_PASSWORD=<CLIENT_SECRET from the output>
|
||||
TEAMS_APP_TYPE=MultiTenant
|
||||
```
|
||||
|
||||
Install via the `installLink` in the output, then continue from
|
||||
[Restart](#restart). If this skill already created a single-tenant app,
|
||||
start over first — see Rotate or recreate credentials in
|
||||
[Troubleshooting](#troubleshooting).
|
||||
|
||||
### Manual Azure portal path
|
||||
|
||||
For tenants where the Teams Developer Portal is blocked. Unlike the CLI path,
|
||||
the Azure Bot resource in step 3 requires an active **Azure subscription**.
|
||||
This is the classic walk; every value it produces maps onto the same `.env`
|
||||
keys. Ask the human before creating anything: the app registration name,
|
||||
single vs multi tenant, a client secret description, and (this path only) a
|
||||
separate Azure Bot handle.
|
||||
|
||||
1. **App registration**: in https://portal.azure.com, search "App registrations"
|
||||
→ "New registration". Name it (e.g. "NanoClaw"); Supported account types:
|
||||
Single tenant (most common for self-host) or Multi tenant. From the Overview
|
||||
page copy the **Application (client) ID** and — single tenant only — the
|
||||
**Directory (tenant) ID**.
|
||||
2. **Client secret**: in the app registration, "Certificates & secrets" → "New
|
||||
client secret" (expires 180 days or longer). **Copy the Value now** — Azure
|
||||
shows it once (the Value column, not the Secret ID).
|
||||
3. **Azure Bot resource**: search "Azure Bot" → Create. Bot handle: any unique
|
||||
name; Type of App: must match step 1; Creation type: "Use existing app
|
||||
registration" with the App ID from step 1. After creating, open the bot →
|
||||
Configuration and set **Messaging endpoint** to
|
||||
`https://your-domain/webhook/teams`, then Apply.
|
||||
4. **Enable the Teams channel**: Azure Bot resource → Channels → Microsoft
|
||||
Teams → Accept terms → Apply.
|
||||
5. **Store the credentials** in `.env` (the same 401 pairing rule applies —
|
||||
`SingleTenant` needs the tenant ID, `MultiTenant` must omit it):
|
||||
|
||||
```bash
|
||||
TEAMS_APP_ID=<Application (client) ID>
|
||||
TEAMS_APP_PASSWORD=<client secret Value>
|
||||
TEAMS_APP_TYPE=SingleTenant
|
||||
TEAMS_APP_TENANT_ID=<Directory (tenant) ID>
|
||||
```
|
||||
6. **Build the app package** (manifest + icons, written in-process to
|
||||
`data/teams/teams-app-package.zip` — no `zip` binary needed):
|
||||
|
||||
```bash
|
||||
pnpm exec tsx setup/channels/teams-manifest-build.ts --app-id YOUR_APP_ID --url https://your-domain
|
||||
```
|
||||
7. **Sideload**: Microsoft Teams → Apps → Manage your apps → Upload an app →
|
||||
"Upload a custom app" → select the zip → Add.
|
||||
8. Continue from [Restart](#restart).
|
||||
|
||||
Or create the bot resource with the Azure CLI instead of the portal:
|
||||
|
||||
```bash
|
||||
az group create --name nanoclaw-rg --location eastus
|
||||
az bot create --resource-group nanoclaw-rg --name nanoclaw-bot --app-type SingleTenant --appid YOUR_APP_ID --tenant-id YOUR_TENANT_ID --endpoint "https://your-domain/webhook/teams"
|
||||
az bot msteams create --resource-group nanoclaw-rg --name nanoclaw-bot
|
||||
```
|
||||
|
||||
## Optional configuration
|
||||
|
||||
### Receive all channel messages (without @-mention)
|
||||
|
||||
By default the bot only receives messages when @-mentioned. With a CLI-created
|
||||
bot, grant the resource-specific-consent (RSC) permissions directly — no
|
||||
manifest edit, no re-upload; the app version is bumped automatically:
|
||||
|
||||
```bash
|
||||
teams app rsc add <teams-app-id> ChannelMessage.Read.Group --type Application
|
||||
teams app rsc add <teams-app-id> ChatMessage.Read.Chat --type Application
|
||||
```
|
||||
|
||||
Then update/reinstall the app in the team so the new permissions get consented.
|
||||
(`<teams-app-id>` is the Teams App ID shown in the install step — recover it
|
||||
any time with `teams app list`, or find the app at
|
||||
https://dev.teams.microsoft.com/apps.)
|
||||
|
||||
On the manual path, regenerate the package with RSC baked in and sideload it
|
||||
again (the manifest version is bumped so the upload supersedes the original):
|
||||
|
||||
```bash
|
||||
pnpm exec tsx setup/channels/teams-manifest-build.ts --app-id YOUR_APP_ID --url https://your-domain --rsc
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Upload a custom app" is missing / sideloading blocked
|
||||
|
||||
`teams status` shows whether sideloading is enabled at both tenant
|
||||
and user level; the login output prints the same check.
|
||||
|
||||
- **Tenant level off**: Teams Admin Center → **Teams apps** → **Setup
|
||||
policies** → **Global** → **Upload custom apps** = On.
|
||||
- **"Enabled for the tenant, but your user policy blocks it"**: the per-user
|
||||
policy is the blocker — Teams Admin Center → **Users** → find the user →
|
||||
**Policies** → **App setup policy** → assign one with **Upload custom
|
||||
apps** = On. Policy changes can take a while to propagate.
|
||||
|
||||
Free personal Teams does not support sideloading at all — use a Microsoft 365
|
||||
Business / EDU / developer tenant.
|
||||
|
||||
The login step's sideloading probe is **advisory** — policy edits can take
|
||||
hours to propagate and the probe has been seen flapping between runs on the
|
||||
same account. The authoritative test is whether the install link's Add
|
||||
actually works; only act on the probe if the install itself refuses.
|
||||
|
||||
### `teams: command not found`
|
||||
|
||||
The CLI installed fine but npm's global bin directory isn't on your PATH — a
|
||||
common state with custom npm prefixes. Find it with `npm prefix -g` (the
|
||||
binary is at `<prefix>/bin/teams`), then either add that directory to PATH or
|
||||
symlink the binary somewhere already on it. The skill's own steps are immune —
|
||||
they invoke the absolute path.
|
||||
|
||||
### Create fails immediately with `AUTH_REQUIRED` after a successful sign-in
|
||||
|
||||
The sign-in didn't persist: each `teams` command is a separate process, and
|
||||
when the CLI's credential store can't load it silently falls back to an
|
||||
in-memory cache that dies with the login process. Symptom check:
|
||||
`teams status` says logged out right after a login succeeded. The known
|
||||
cause: the **CLI was installed as a pnpm workspace dependency** — pnpm's
|
||||
supply-chain policy skips dependency build scripts, so keytar (the CLI's
|
||||
native credential store) never gets its binary and the whole store fails to
|
||||
load. Use the global npm install this skill performs — and `pnpm uninstall
|
||||
@microsoft/teams.cli` if a workspace copy lingers, so `teams` resolves to
|
||||
the global one. (The "libsecret not found → stored unencrypted" warning is
|
||||
NOT this failure — that fallback persists fine and is safe to ignore.)
|
||||
|
||||
After fixing, sign in again and confirm `teams status` shows logged in, then
|
||||
re-run this skill.
|
||||
|
||||
### Bot never receives messages
|
||||
|
||||
1. The app is actually installed in Teams — if setup was interrupted before
|
||||
the install step, nothing got installed. Recover the install link:
|
||||
`teams app list` shows the Teams App ID, then
|
||||
`teams app get <teams-app-id> --install-link`.
|
||||
2. The tunnel is up and the messaging endpoint matches it — the endpoint must
|
||||
be `https://<your-domain>/webhook/teams`, and your tunnel (e.g.
|
||||
`cloudflared tunnel --url http://localhost:3000`) must be forwarding to
|
||||
this machine's port 3000. Check
|
||||
with `teams app doctor <teams-app-id>` (CLI-created bots) or Azure
|
||||
Bot → **Configuration** (manual path).
|
||||
3. The adapter started: `grep -i teams logs/nanoclaw.log | tail`.
|
||||
4. The credentials are in `.env` (`TEAMS_APP_ID`, `TEAMS_APP_PASSWORD`,
|
||||
`TEAMS_APP_TYPE`).
|
||||
|
||||
### Tunnel URL changed
|
||||
|
||||
Point the bot at the new endpoint:
|
||||
`teams app update <teams-app-id> --endpoint "https://new-domain/webhook/teams"`
|
||||
(manual path: Azure Bot → Configuration → Messaging endpoint).
|
||||
|
||||
### `Unauthorized` / 401 from Azure Bot Service
|
||||
|
||||
Either the credential pairing is wrong, or the secret is dead:
|
||||
|
||||
- **Pairing**: `TEAMS_APP_TYPE=SingleTenant` requires `TEAMS_APP_TENANT_ID`;
|
||||
`MultiTenant` must have **no** tenant ID set. A mismatch authenticates
|
||||
against the wrong authority and every send/receive 401s.
|
||||
- **Secret**: expired or mispasted. Rotate with
|
||||
`teams app auth secret create <teams-app-id>` (or Azure portal →
|
||||
Certificates & secrets), update `TEAMS_APP_PASSWORD` in `.env`, and restart.
|
||||
|
||||
### Rotate or recreate credentials
|
||||
|
||||
The credentials flow skips creation while `.env` has `TEAMS_APP_ID` **or**
|
||||
`TEAMS_APP_PASSWORD` — deleting just one line does not make the skill
|
||||
regenerate it (that would pair a new app with stale keys). To rotate only the
|
||||
secret, use the 401 section above. To start over completely: delete **all**
|
||||
`TEAMS_*` lines from `.env`, optionally delete the old app at
|
||||
https://dev.teams.microsoft.com/apps (CLI path) or in Azure Portal → App
|
||||
registrations (manual path), then re-run this skill. Re-running
|
||||
`teams app create` with old credentials still in `.env` would otherwise create
|
||||
a second, orphaned app.
|
||||
|
||||
### Replies land in the wrong place
|
||||
|
||||
A Teams bot's platform ID is derived from the first inbound activity, so wire
|
||||
the messaging group that the router auto-creates after you DM the bot — don't
|
||||
guess the platform ID. See **Finish wiring** above.
|
||||
|
||||
@@ -5,156 +5,111 @@ description: Add Telegram channel integration via Chat SDK.
|
||||
|
||||
# Add Telegram Channel
|
||||
|
||||
Adds Telegram bot support via the Chat SDK bridge. NanoClaw doesn't ship
|
||||
channels in trunk — this skill copies the Telegram adapter, its
|
||||
formatting/pairing helpers, and their tests in from the `channels` branch. The
|
||||
`pair-telegram` setup step is maintained in trunk, so it is not copied here.
|
||||
Adds Telegram bot support via the Chat SDK bridge.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent
|
||||
reads the prose and applies them, and a parser can apply them deterministically
|
||||
from the same document. Every directive is idempotent, so the whole skill is
|
||||
safe to re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
## Apply
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the Telegram adapter, its formatting/pairing helpers, their tests, and the `pair-telegram` setup step in from the `channels` branch.
|
||||
|
||||
### 1. Copy the adapter, helpers, and tests
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the Telegram adapter, its pairing and
|
||||
markdown-sanitize helpers (with their tests), and the registration test into
|
||||
place (overwrite — the branch is canonical):
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/telegram.ts
|
||||
src/channels/telegram-pairing.ts
|
||||
src/channels/telegram-pairing.test.ts
|
||||
src/channels/telegram-markdown-sanitize.ts
|
||||
src/channels/telegram-markdown-sanitize.test.ts
|
||||
src/channels/telegram-registration.test.ts
|
||||
- `src/channels/telegram.ts`, `telegram-pairing.ts`, `telegram-markdown-sanitize.ts` (and their `.test.ts` siblings) all exist
|
||||
- `src/channels/telegram-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './telegram.js';`
|
||||
- `setup/pair-telegram.ts` exists and `setup/index.ts`'s `STEPS` map contains `'pair-telegram':`
|
||||
- `@chat-adapter/telegram` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter, helpers, tests, registration test, and setup step
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/telegram.ts > src/channels/telegram.ts
|
||||
git show origin/channels:src/channels/telegram-registration.test.ts > src/channels/telegram-registration.test.ts
|
||||
git show origin/channels:src/channels/telegram-pairing.ts > src/channels/telegram-pairing.ts
|
||||
git show origin/channels:src/channels/telegram-pairing.test.ts > src/channels/telegram-pairing.test.ts
|
||||
git show origin/channels:src/channels/telegram-markdown-sanitize.ts > src/channels/telegram-markdown-sanitize.ts
|
||||
git show origin/channels:src/channels/telegram-markdown-sanitize.test.ts > src/channels/telegram-markdown-sanitize.test.ts
|
||||
git show origin/channels:setup/pair-telegram.ts > setup/pair-telegram.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if already present):
|
||||
|
||||
```typescript
|
||||
import './telegram.js';
|
||||
```
|
||||
|
||||
### 3. Register the pairing setup step
|
||||
### 4. Register the setup step
|
||||
|
||||
Add the `pair-telegram` loader to the `STEPS` map in `setup/index.ts`, inside the
|
||||
dormant marker region (skipped if already present — `pair-telegram` ships in core,
|
||||
so this idempotent-skips on a normal install, but is expressed for a
|
||||
clean-upstream rebuild). The pairing handshake below spawns this step:
|
||||
In `setup/index.ts`, add this entry to the `STEPS` map (right after the `register` line is fine; skip if already present):
|
||||
|
||||
```nc:append to:setup/index.ts at:nanoclaw:setup-steps
|
||||
```typescript
|
||||
'pair-telegram': () => import('./pair-telegram.js'),
|
||||
```
|
||||
|
||||
### 4. Install the adapter package
|
||||
### 5. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
@chat-adapter/telegram@4.29.0
|
||||
```bash
|
||||
pnpm install @chat-adapter/telegram@4.29.0
|
||||
```
|
||||
|
||||
### 5. Build and validate
|
||||
### 6. Build and validate
|
||||
|
||||
Build first: it guards the typed `createChatSdkBridge(...)` core call and proves
|
||||
the dependency is installed. Then run the one integration test.
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/telegram-registration.test.ts
|
||||
```
|
||||
|
||||
`telegram-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `telegram`. It goes red if the import line is deleted or drifts,
|
||||
if the barrel fails to evaluate, or if `@chat-adapter/telegram` isn't installed
|
||||
(the import throws) — so it also covers the dependency from step 4. End-to-end
|
||||
delivery against a real bot is verified manually once the service runs.
|
||||
Both must be clean before proceeding. `telegram-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `telegram`. It goes red if the `import './telegram.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/telegram` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 5. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
End-to-end message delivery against a real Telegram bot is verified manually once the service is running — see Next Steps and the pairing flow in Channel Info.
|
||||
|
||||
## Credentials
|
||||
|
||||
Bot creation in Telegram is human and interactive — no parser can click through
|
||||
BotFather. The adapter is installed and registered, but it can't receive a
|
||||
message until the bot exists. Tell the user:
|
||||
### Create Telegram Bot
|
||||
|
||||
```nc:operator
|
||||
Create the Telegram bot:
|
||||
1. Open Telegram and message @BotFather — Telegram's official bot for creating bots.
|
||||
2. Send /newbot and follow the prompts: a friendly name, then a username that must end in "bot".
|
||||
3. Copy the bot token it gives you (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).
|
||||
4. Planning to use the bot in group chats? Send /mybots → your bot → Bot Settings → Group Privacy → Turn off, so the bot can see all messages and not just @mentions.
|
||||
1. Open Telegram and search for `@BotFather`
|
||||
2. Send `/newbot` and follow the prompts:
|
||||
- Bot name: Something friendly (e.g., "NanoClaw Assistant")
|
||||
- Bot username: Must end with "bot" (e.g., "nanoclaw_bot")
|
||||
3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
|
||||
|
||||
**Important for group chats**: By default, Telegram bots only see @mentions and commands in groups. To let the bot see all messages:
|
||||
|
||||
1. Open `@BotFather` > `/mybots` > select your bot
|
||||
2. **Bot Settings** > **Group Privacy** > **Turn off**
|
||||
|
||||
### Configure environment
|
||||
|
||||
Add to `.env`:
|
||||
|
||||
```bash
|
||||
TELEGRAM_BOT_TOKEN=your-bot-token
|
||||
```
|
||||
|
||||
Collect the bot token and store it — the bridge reads it from `.env` (set-if-absent,
|
||||
so a value you've already filled in is never overwritten) and syncs it to the
|
||||
container:
|
||||
|
||||
```nc:prompt bot_token secret validate:^[0-9]+:[A-Za-z0-9_-]{35,}$
|
||||
Paste the bot token from BotFather (looks like `123456:ABC-DEF...`).
|
||||
```
|
||||
```nc:env-set
|
||||
TELEGRAM_BOT_TOKEN={{bot_token}}
|
||||
```
|
||||
Confirm the token works and capture the bot's handle — `getMe` returns the bot
|
||||
account and fails here if the token is bad. You'll use the handle to open the
|
||||
right chat just before pairing:
|
||||
|
||||
```nc:run capture:bot_username effect:fetch
|
||||
curl -sf https://api.telegram.org/bot{{bot_token}}/getMe | jq -er '.result.username'
|
||||
```
|
||||
|
||||
## Restart
|
||||
|
||||
Restart the service so it loads the Telegram adapter and the token you just
|
||||
stored, and wait for its CLI socket. The adapter must be live and polling before
|
||||
pairing — it's the thing that observes the code you send:
|
||||
|
||||
```nc:run effect:restart
|
||||
bash setup/lib/restart.sh
|
||||
```
|
||||
|
||||
## Pair your chat
|
||||
|
||||
Telegram tokens carry no user binding, so the agent proves you own the chat with
|
||||
a one-time pairing handshake: it issues a 4-digit code, you send those exact 4
|
||||
digits to the bot from the chat you want to register, and the live adapter
|
||||
matches them. Open the bot first so you're on the right screen when the code
|
||||
appears. Tell the user:
|
||||
|
||||
```nc:operator
|
||||
Open @{{bot_username}} (https://t.me/{{bot_username}}) in Telegram now and keep it on screen — a 4-digit pairing code is about to appear in this terminal. When it does, send just those 4 digits to the bot as a message (in a group chat with Group Privacy on, prefix them with @{{bot_username}}). A wrong guess is rejected and a fresh code is issued automatically.
|
||||
```
|
||||
|
||||
Run the pairing handshake. It prints the code, streams "waiting…" and wrong-code
|
||||
feedback while it watches for your message, and resolves your chat address
|
||||
`telegram:<chatId>` plus your Telegram user id once the code matches:
|
||||
|
||||
```nc:run effect:step capture:platform_id=PLATFORM_ID,owner_handle=ADMIN_USER_ID
|
||||
pnpm exec tsx setup/index.ts --step pair-telegram -- --intent main
|
||||
```
|
||||
|
||||
`owner_handle` (your Telegram user id) and `platform_id` (`telegram:<chatId>`)
|
||||
are what the owner-wiring step needs. The greeting goes out over the same chat as
|
||||
soon as pairing completes.
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now. Otherwise wire
|
||||
this channel with `/init-first-agent` (or `/manage-channels`).
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
- **type**: `telegram`
|
||||
- **terminology**: Telegram calls them "groups" and "chats." A "group" has multiple members; a "chat" is a 1:1 conversation with the bot.
|
||||
- **platform-id-format**: `telegram:{chatId}` (e.g. `telegram:123456789` for a DM, `telegram:-1001234567890` for a group — negative chat IDs are groups/channels).
|
||||
- **how-to-find-id**: Do NOT ask the user for a chat ID. Telegram registration uses pairing — run `pnpm exec tsx setup/index.ts --step pair-telegram -- --intent <main|wire-to:folder|new-agent:folder>`. The step prints a 4-digit code (and re-prints a fresh one if a wrong code invalidates it, up to 5 times); tell the user to send just those 4 digits from the chat they want to register (DM the bot for `main`, post in the group otherwise; with Group Privacy ON, prefix `@<botname> CODE`). Success emits a `PAIR_TELEGRAM` block with `STATUS=success`, `PLATFORM_ID`, `IS_GROUP`, `ADMIN_USER_ID` (the bare Telegram user id) and `PAIRED_USER_ID` (the `telegram:`-prefixed form). The service must be running — the polling adapter is what observes the code.
|
||||
- **how-to-find-id**: Do NOT ask the user for a chat ID. Telegram registration uses pairing — run `pnpm exec tsx setup/index.ts --step pair-telegram -- --intent <main|wire-to:folder|new-agent:folder>`, show the user the 4-digit `CODE` from the `PAIR_TELEGRAM_ISSUED` block (follow the `REMINDER_TO_ASSISTANT` line in that block), and tell them to send just the 4 digits as a message from the chat they want to register (DM the bot for `main`, post in the group otherwise). In groups with Group Privacy ON, prefix with the bot handle: `@<botname> CODE`. Wrong guesses invalidate the code — if a `PAIR_TELEGRAM_ATTEMPT` block arrives with a mismatched `RECEIVED_CODE`, a `PAIR_TELEGRAM_NEW_CODE` block will follow automatically (up to 5 regenerations); show the new code. On `PAIR_TELEGRAM STATUS=failed ERROR=max-regenerations-exceeded`, ask the user if they want to try again and re-invoke the step — each invocation starts a fresh 5-attempt batch. Success emits `PAIR_TELEGRAM STATUS=success` with `PLATFORM_ID`, `IS_GROUP`, and `ADMIN_USER_ID`. The service must be running for this to work (the polling adapter is what observes the code).
|
||||
- **supports-threads**: no
|
||||
- **typical-use**: Interactive chat — direct messages or small groups
|
||||
- **default-isolation**: Same agent group if you're the only participant across multiple chats. Separate agent group if different people are in different groups.
|
||||
|
||||
@@ -5,110 +5,85 @@ description: Add Webex channel integration via Chat SDK.
|
||||
|
||||
# Add Webex Channel
|
||||
|
||||
Adds Cisco Webex support via the Chat SDK bridge. NanoClaw doesn't ship channels
|
||||
in trunk — this skill copies the Webex adapter in from the `channels` branch.
|
||||
Adds Cisco Webex support via the Chat SDK bridge.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent
|
||||
reads the prose and applies them, and a parser can apply them deterministically
|
||||
from the same document. Every directive is idempotent, so the whole skill is
|
||||
safe to re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
## Apply
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the Webex adapter in from the `channels` branch.
|
||||
|
||||
### 1. Copy the adapter and its registration test
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the Webex adapter and its registration test
|
||||
into `src/channels/` (overwrite — the branch is canonical):
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/webex.ts
|
||||
src/channels/webex-registration.test.ts
|
||||
- `src/channels/webex.ts` exists
|
||||
- `src/channels/webex-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './webex.js';`
|
||||
- `@bitbasti/chat-adapter-webex` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/webex.ts > src/channels/webex.ts
|
||||
git show origin/channels:src/channels/webex-registration.test.ts > src/channels/webex-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './webex.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`.
|
||||
The Webex adapter ships under the third-party `@bitbasti/*` namespace, not
|
||||
`@chat-adapter/*`, so it carries its own version line (`0.1.0`) rather than
|
||||
tracking the chat core version:
|
||||
|
||||
```nc:dep
|
||||
@bitbasti/chat-adapter-webex@0.1.0
|
||||
```bash
|
||||
pnpm install @bitbasti/chat-adapter-webex@0.1.0
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Build and validate
|
||||
|
||||
Build first: it guards the typed `createChatSdkBridge(...)` core call and proves
|
||||
the dependency is installed. Then run the one integration test.
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/webex-registration.test.ts
|
||||
```
|
||||
|
||||
`webex-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `webex`. It goes red if the import line is deleted or drifts,
|
||||
if the barrel fails to evaluate, or if `@bitbasti/chat-adapter-webex` isn't
|
||||
installed (the import throws) — so it also covers the dependency from step 3.
|
||||
End-to-end delivery against a real Webex space is verified manually once the
|
||||
service runs — see the webhook setup below.
|
||||
Both must be clean before proceeding. `webex-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `webex`. It goes red if the `import './webex.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@bitbasti/chat-adapter-webex` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
End-to-end message delivery against a real Webex space is verified manually once the service is running — see Next Steps and the webhook setup above.
|
||||
|
||||
## Credentials
|
||||
|
||||
Webex bot setup is human and interactive — these steps are prose, not directives
|
||||
(no parser can click through the Webex Developer Portal). A recipe rebuild
|
||||
produces a compiling, registered adapter that cannot receive a message until
|
||||
they're done.
|
||||
|
||||
### Create the Webex bot
|
||||
|
||||
1. Go to [developer.webex.com](https://developer.webex.com/my-apps/new/bot) and create a new bot.
|
||||
2. Copy the **Bot Access Token**.
|
||||
1. Go to [developer.webex.com](https://developer.webex.com/my-apps/new/bot) and create a new bot
|
||||
2. Copy the **Bot Access Token**
|
||||
3. Set up a webhook:
|
||||
- Use the Webex API or Developer Portal to create a webhook pointing to `https://your-domain/webhook/webex`.
|
||||
- Set a webhook secret for signature verification.
|
||||
- Use the Webex API or Developer Portal to create a webhook pointing to `https://your-domain/webhook/webex`
|
||||
- Set a webhook secret for signature verification
|
||||
|
||||
### Store the credentials
|
||||
### Configure environment
|
||||
|
||||
Capture the two values, then write them. `prompt` only *asks* and binds the
|
||||
answer to a name; a separate directive consumes it — so the same prompts could
|
||||
feed `ncl` or the OneCLI vault instead of `.env` by swapping only the consumer.
|
||||
Here they go to `.env` (set-if-absent — a value you've already filled in is
|
||||
never overwritten):
|
||||
Add to `.env`:
|
||||
|
||||
```nc:prompt bot_token secret
|
||||
Paste the Bot Access Token — from the Webex bot you created.
|
||||
```bash
|
||||
WEBEX_BOT_TOKEN=your-bot-token
|
||||
WEBEX_WEBHOOK_SECRET=your-webhook-secret
|
||||
```
|
||||
```nc:prompt webhook_secret secret
|
||||
Paste the webhook secret you set for signature verification.
|
||||
```
|
||||
```nc:env-set
|
||||
WEBEX_BOT_TOKEN={{bot_token}}
|
||||
WEBEX_WEBHOOK_SECRET={{webhook_secret}}
|
||||
```
|
||||
### Webhook server
|
||||
|
||||
The Chat SDK bridge automatically starts a shared webhook server on port 3000
|
||||
(`WEBHOOK_PORT` to change it), handling `/webhook/webex`. This port must be
|
||||
publicly reachable for Webex to deliver events. Running locally, expose it with
|
||||
ngrok (`ngrok http 3000`), a Cloudflare Tunnel, or a reverse proxy on a VPS —
|
||||
the resulting public URL is the base for the webhook URL above.
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now. Otherwise run
|
||||
`/manage-channels` to wire this channel to an agent group.
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
|
||||
@@ -36,12 +36,16 @@ pnpm uninstall wechat-ilink-client
|
||||
rm -rf data/wechat
|
||||
```
|
||||
|
||||
The channel's messaging groups, wirings, and conversation history are **left
|
||||
intact** — you created those at runtime (wiring + use), not this skill's install,
|
||||
so removal doesn't touch them. To purge them deliberately, delete them yourself
|
||||
with `ncl messaging-groups delete <id>`.
|
||||
## 5. Remove DB wiring
|
||||
|
||||
## 5. Rebuild and restart
|
||||
```sql
|
||||
-- Remove any sessions first (foreign key)
|
||||
DELETE FROM sessions WHERE messaging_group_id IN (SELECT id FROM messaging_groups WHERE channel_type = 'wechat');
|
||||
DELETE FROM messaging_group_agents WHERE messaging_group_id IN (SELECT id FROM messaging_groups WHERE channel_type = 'wechat');
|
||||
DELETE FROM messaging_groups WHERE channel_type = 'wechat';
|
||||
```
|
||||
|
||||
## 6. Rebuild and restart
|
||||
|
||||
Run from your NanoClaw project root:
|
||||
|
||||
|
||||
@@ -85,6 +85,7 @@ Add to `.env`:
|
||||
WECHAT_ENABLED=true
|
||||
```
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### 2. Start the service and scan the QR
|
||||
|
||||
|
||||
@@ -6,71 +6,62 @@ description: Add WhatsApp Business Cloud API channel via Chat SDK. Official Meta
|
||||
# Add WhatsApp Cloud API Channel
|
||||
|
||||
Connect NanoClaw to WhatsApp via the official Meta WhatsApp Business Cloud API.
|
||||
NanoClaw doesn't ship channels in trunk — this skill copies the WhatsApp Cloud
|
||||
adapter in from the `channels` branch.
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent reads
|
||||
the prose and applies them, and a parser can apply them deterministically from
|
||||
the same document. Every directive is idempotent, so the whole skill is safe to
|
||||
re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
## Apply
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the WhatsApp Cloud adapter in from the `channels` branch.
|
||||
|
||||
### 1. Copy the adapter
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the WhatsApp Cloud adapter into
|
||||
`src/channels/` (overwrite — the branch is canonical):
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/whatsapp-cloud.ts
|
||||
src/channels/whatsapp-cloud-registration.test.ts
|
||||
- `src/channels/whatsapp-cloud.ts` exists
|
||||
- `src/channels/whatsapp-cloud-registration.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './whatsapp-cloud.js';`
|
||||
- `@chat-adapter/whatsapp` is listed in `package.json` dependencies
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and its registration test
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/whatsapp-cloud.ts > src/channels/whatsapp-cloud.ts
|
||||
git show origin/channels:src/channels/whatsapp-cloud-registration.test.ts > src/channels/whatsapp-cloud-registration.test.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if the line is already present):
|
||||
|
||||
```typescript
|
||||
import './whatsapp-cloud.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter package
|
||||
### 4. Install the adapter package (pinned)
|
||||
|
||||
Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
|
||||
|
||||
```nc:dep
|
||||
@chat-adapter/whatsapp@4.29.0
|
||||
```bash
|
||||
pnpm install @chat-adapter/whatsapp@4.29.0
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Build and validate
|
||||
|
||||
Build guards the typed `createChatSdkBridge(...)` core call and proves the
|
||||
dependency is installed — the import throws at evaluation if `@chat-adapter/whatsapp`
|
||||
is missing or the barrel drifts:
|
||||
|
||||
```nc:run effect:build
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/whatsapp-cloud-registration.test.ts
|
||||
```
|
||||
|
||||
`whatsapp-cloud-registration.test.ts` imports the real channel barrel and asserts
|
||||
the registry contains `whatsapp-cloud` — it goes red if the import line is deleted
|
||||
or drifts, if the barrel fails to evaluate, or if `@chat-adapter/whatsapp` isn't
|
||||
installed (the import throws), so it also covers the dependency from step 3.
|
||||
Both must be clean before proceeding. `whatsapp-cloud-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `whatsapp-cloud`. It goes red if the `import './whatsapp-cloud.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/whatsapp` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
|
||||
|
||||
End-to-end message delivery against a real WhatsApp Business number is verified
|
||||
manually once the service is running — see Next Steps and the webhook setup
|
||||
below.
|
||||
End-to-end message delivery against a real WhatsApp Business number is verified manually once the service is running — see Next Steps and the webhook setup above.
|
||||
|
||||
## Credentials
|
||||
|
||||
Meta app setup is human and interactive — these steps are prose, not directives
|
||||
(no parser can click through the Meta dashboard). A recipe rebuild produces a
|
||||
compiling, registered adapter that cannot receive a message until they're done.
|
||||
|
||||
1. Go to [Meta for Developers](https://developers.facebook.com/apps/) and create an app (type: Business).
|
||||
2. Add the **WhatsApp** product.
|
||||
3. Go to **WhatsApp** > **API Setup**:
|
||||
@@ -82,40 +73,18 @@ compiling, registered adapter that cannot receive a message until they're done.
|
||||
- Subscribe to webhook fields: `messages`.
|
||||
5. Copy the **App Secret** from **Settings** > **Basic**.
|
||||
|
||||
### Store the credentials
|
||||
### Configure environment
|
||||
|
||||
Capture the four values, then write them. `prompt` only *asks* and binds the
|
||||
answer to a name; a separate directive consumes it — so the same prompts could
|
||||
feed `ncl` or the OneCLI vault instead of `.env` by swapping only the consumer.
|
||||
Here they go to `.env` (set-if-absent — a value you've already filled in is
|
||||
never overwritten):
|
||||
Add to `.env`:
|
||||
|
||||
```nc:prompt access_token secret
|
||||
Paste the System User access token — WhatsApp > API Setup, with `whatsapp_business_messaging` permission.
|
||||
```bash
|
||||
WHATSAPP_ACCESS_TOKEN=your-system-user-access-token
|
||||
WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
|
||||
WHATSAPP_APP_SECRET=your-app-secret
|
||||
WHATSAPP_VERIFY_TOKEN=your-verify-token
|
||||
```
|
||||
```nc:prompt phone_number_id
|
||||
Paste the Phone Number ID — WhatsApp > API Setup (not the phone number itself).
|
||||
```
|
||||
```nc:prompt app_secret secret
|
||||
Paste the App Secret — Settings > Basic.
|
||||
```
|
||||
```nc:prompt verify_token secret
|
||||
Paste the Verify Token — the random string you set under WhatsApp > Configuration.
|
||||
```
|
||||
```nc:env-set
|
||||
WHATSAPP_ACCESS_TOKEN={{access_token}}
|
||||
WHATSAPP_PHONE_NUMBER_ID={{phone_number_id}}
|
||||
WHATSAPP_APP_SECRET={{app_secret}}
|
||||
WHATSAPP_VERIFY_TOKEN={{verify_token}}
|
||||
```
|
||||
### Webhook server
|
||||
|
||||
The Chat SDK bridge automatically starts a shared webhook server on port 3000
|
||||
(`WEBHOOK_PORT` to change it), handling `/webhook/whatsapp`. This port must be
|
||||
publicly reachable for Meta to deliver events. Running locally, expose it with
|
||||
ngrok (`ngrok http 3000`), a Cloudflare Tunnel, or a reverse proxy on a VPS —
|
||||
the resulting public URL is the base for the webhook URL set under WhatsApp >
|
||||
Configuration above.
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
## Next Steps
|
||||
|
||||
@@ -131,5 +100,3 @@ Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
- **supports-threads**: no
|
||||
- **typical-use**: Interactive 1:1 chat -- direct messages only
|
||||
- **default-isolation**: Same agent group if you're the only person messaging the bot. Each additional person who messages gets their own conversation automatically, but they share the agent's workspace and memory -- use a separate agent group if you need information isolation between different contacts.
|
||||
</content>
|
||||
</invoke>
|
||||
|
||||
@@ -5,202 +5,216 @@ description: Add WhatsApp channel via native Baileys adapter. Direct connection
|
||||
|
||||
# Add WhatsApp Channel
|
||||
|
||||
Adds WhatsApp support via the native Baileys adapter — a direct WhatsApp Web
|
||||
connection, no Chat SDK bridge. NanoClaw doesn't ship channels in trunk — this
|
||||
skill copies the WhatsApp adapter in from the `channels` branch.
|
||||
Adds WhatsApp support via the native Baileys adapter (no Chat SDK bridge).
|
||||
|
||||
The mechanical steps under **Apply** carry `nc:` directive fences: an agent
|
||||
reads the prose and applies them, and a parser can apply them deterministically
|
||||
from the same document. Every directive is idempotent, so the whole skill is
|
||||
safe to re-run; anything a parser can't apply falls back to the prose beside it.
|
||||
## Install
|
||||
|
||||
## Apply
|
||||
NanoClaw doesn't ship channels in trunk. This skill copies the native WhatsApp (Baileys) adapter and its `whatsapp-auth` setup step in from the `channels` branch. No Chat SDK bridge.
|
||||
|
||||
### 1. Copy the adapter and its registration test
|
||||
### Pre-flight (idempotent)
|
||||
|
||||
Fetch the `channels` branch and copy the WhatsApp adapter and its registration
|
||||
test into `src/channels/` (overwrite — the branch is canonical). The
|
||||
`whatsapp-auth` setup step is maintained in trunk, so it is not copied here:
|
||||
Skip to **Credentials** if all of these are already in place:
|
||||
|
||||
```nc:copy from-branch:channels
|
||||
src/channels/whatsapp.ts
|
||||
src/channels/whatsapp-registration.test.ts
|
||||
- `src/channels/whatsapp.ts` exists
|
||||
- `src/channels/whatsapp-registration.test.ts` exists
|
||||
- `src/channels/whatsapp.test.ts` exists
|
||||
- `src/channels/index.ts` contains `import './whatsapp.js';`
|
||||
- `setup/whatsapp-auth.ts` and `setup/groups.ts` both exist
|
||||
- `setup/index.ts`'s `STEPS` map contains both `'whatsapp-auth':` and `groups:`
|
||||
- `@whiskeysockets/baileys`, `qrcode`, `pino` are listed in `package.json` dependencies
|
||||
- `.claude/skills/add-whatsapp/scripts/wa-qr-browser.ts` exists (ships with this skill)
|
||||
|
||||
Otherwise continue. Every step below is safe to re-run.
|
||||
|
||||
### 1. Fetch the channels branch
|
||||
|
||||
```bash
|
||||
git fetch origin channels
|
||||
```
|
||||
|
||||
### 2. Register the adapter
|
||||
### 2. Copy the adapter and setup steps
|
||||
|
||||
Append the self-registration import to the channel barrel (skipped if the line
|
||||
is already present). This one line is the skill's only reach-in into core:
|
||||
```bash
|
||||
git show origin/channels:src/channels/whatsapp.ts > src/channels/whatsapp.ts
|
||||
git show origin/channels:src/channels/whatsapp-registration.test.ts > src/channels/whatsapp-registration.test.ts
|
||||
git show origin/channels:src/channels/whatsapp.test.ts > src/channels/whatsapp.test.ts
|
||||
git show origin/channels:setup/whatsapp-auth.ts > setup/whatsapp-auth.ts
|
||||
git show origin/channels:setup/groups.ts > setup/groups.ts
|
||||
```
|
||||
|
||||
```nc:append to:src/channels/index.ts
|
||||
### 3. Append the self-registration import
|
||||
|
||||
Append to `src/channels/index.ts` (skip if already present):
|
||||
|
||||
```typescript
|
||||
import './whatsapp.js';
|
||||
```
|
||||
|
||||
### 3. Install the adapter packages
|
||||
### 4. Register the setup steps
|
||||
|
||||
Pinned to exact versions — the supply-chain policy rejects ranges and `latest`.
|
||||
Baileys is the WhatsApp Web client; `qrcode` renders the device-link QR in the
|
||||
terminal; `pino` is Baileys' logger:
|
||||
In `setup/index.ts`, add these entries to the `STEPS` map (skip lines already present):
|
||||
|
||||
```nc:dep
|
||||
@whiskeysockets/baileys@7.0.0-rc.9
|
||||
qrcode@1.5.4
|
||||
@types/qrcode@1.5.6
|
||||
pino@9.6.0
|
||||
```typescript
|
||||
groups: () => import('./groups.js'),
|
||||
'whatsapp-auth': () => import('./whatsapp-auth.js'),
|
||||
```
|
||||
|
||||
### 4. Build and validate
|
||||
### 5. Install the adapter packages (pinned)
|
||||
|
||||
Build first: it typechecks the adapter against core and proves the dependencies
|
||||
are installed. Then run the one integration test.
|
||||
```bash
|
||||
pnpm install @whiskeysockets/baileys@7.0.0-rc.9 qrcode@1.5.4 @types/qrcode@1.5.6 pino@9.6.0
|
||||
```
|
||||
|
||||
```nc:run effect:build
|
||||
### 6. Build and validate
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
```nc:run effect:test
|
||||
pnpm exec vitest run src/channels/whatsapp-registration.test.ts
|
||||
```
|
||||
|
||||
`whatsapp-registration.test.ts` imports the real channel barrel and asserts the
|
||||
registry contains `whatsapp`. It goes red if the `import './whatsapp.js';` line
|
||||
is deleted or drifts, if the barrel fails to evaluate, or if
|
||||
`@whiskeysockets/baileys` isn't installed (the import throws) — so it also covers
|
||||
the dependency from step 3. End-to-end delivery against a real WhatsApp number is
|
||||
verified manually once the service runs.
|
||||
Both must be clean before proceeding. `whatsapp-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `whatsapp`. It goes red if the `import './whatsapp.js';` line is deleted or drifts, if the barrel fails to evaluate (so the channel genuinely would not register), or if `@whiskeysockets/baileys` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 5.
|
||||
|
||||
## Authenticate
|
||||
End-to-end message delivery against a real WhatsApp number is verified manually once the service is running — see Credentials, Wiring, and Troubleshooting.
|
||||
|
||||
WhatsApp uses linked-device authentication — no API key, just a one-time pairing
|
||||
from your phone. The adapter is installed and registered, but its factory returns
|
||||
`null` (and the channel stays dark) until `store/auth/creds.json` exists.
|
||||
## Credentials
|
||||
|
||||
Pick how to link the device. `qr` shows a rotating QR you scan with your phone's
|
||||
camera; `pairing-code` shows an 8-character code you type into WhatsApp (no camera
|
||||
needed, but it needs your phone number):
|
||||
WhatsApp uses linked-device authentication — no API key, just a one-time pairing from your phone.
|
||||
|
||||
```nc:prompt auth_method validate:^(qr|pairing-code)$
|
||||
How do you want to link WhatsApp? Type `qr` to scan a QR code in this terminal, or `pairing-code` to enter a code on your phone (no camera needed).
|
||||
### Check current state
|
||||
|
||||
Check if WhatsApp is already authenticated. If `store/auth/creds.json` exists, skip to "Shared vs dedicated number".
|
||||
|
||||
```bash
|
||||
test -f store/auth/creds.json && echo "WhatsApp auth exists" || echo "No WhatsApp auth"
|
||||
```
|
||||
|
||||
The pairing-code method needs the number you're linking, the way WhatsApp expects
|
||||
it — digits only, country code first, no `+`, spaces, or dashes (the QR method
|
||||
skips this entirely):
|
||||
### Detect environment
|
||||
|
||||
```nc:prompt phone validate:^\d{8,15}$ when:auth_method=pairing-code
|
||||
Your WhatsApp phone number — digits only, country code first (e.g. 14155551234 for +1 415-555-1234).
|
||||
Check whether the environment is headless (no display server):
|
||||
|
||||
```bash
|
||||
[[ -z "$DISPLAY" && -z "$WAYLAND_DISPLAY" && "$OSTYPE" != darwin* ]] && echo "IS_HEADLESS=true" || echo "IS_HEADLESS=false"
|
||||
```
|
||||
|
||||
Point the user at the right screen before the code appears. For the QR method,
|
||||
tell the user:
|
||||
### Ask the user
|
||||
|
||||
```nc:operator when:auth_method=qr
|
||||
Link WhatsApp by QR:
|
||||
1. On your phone, open WhatsApp → Settings → Linked Devices → Link a Device.
|
||||
2. A QR code will appear in this terminal below and refresh every ~20 seconds. Point your phone's camera at it to scan.
|
||||
Use `AskUserQuestion` to collect configuration. **Adapt auth options based on environment:**
|
||||
|
||||
If IS_HEADLESS=true AND not WSL → AskUserQuestion: How do you want to authenticate WhatsApp?
|
||||
- **Pairing code** (Recommended) - Enter a numeric code on your phone (no camera needed, requires phone number)
|
||||
- **QR code in terminal** - Displays QR code in the terminal (can be too small on some displays)
|
||||
|
||||
Otherwise (macOS, desktop Linux, or WSL) → AskUserQuestion: How do you want to authenticate WhatsApp?
|
||||
- **QR code in browser** (Recommended) - Runs a small local HTTP server that renders the rotating QR as a PNG and auto-opens your default browser
|
||||
- **Pairing code** - Enter a numeric code on your phone (no camera needed, requires phone number)
|
||||
- **QR code in terminal** - Displays QR code in the terminal (can be too small on some displays)
|
||||
|
||||
If they chose pairing code:
|
||||
|
||||
AskUserQuestion: What is your phone number? (Digits only — country code followed by your 10-digit number, no + prefix, spaces, or dashes. Example: 14155551234 where 1 is the US country code and 4155551234 is the phone number.)
|
||||
|
||||
### Clean previous auth state (if re-authenticating)
|
||||
|
||||
```bash
|
||||
rm -rf store/auth/
|
||||
```
|
||||
|
||||
For the pairing-code method, tell the user:
|
||||
### Run WhatsApp authentication
|
||||
|
||||
```nc:operator when:auth_method=pairing-code
|
||||
Link WhatsApp by pairing code:
|
||||
1. On your phone, open WhatsApp → Settings → Linked Devices → Link a Device → tap "Link with phone number instead".
|
||||
2. An 8-character code will appear in this terminal below. Enter it on your phone immediately — it expires in about 60 seconds.
|
||||
For QR code in browser (recommended):
|
||||
|
||||
```bash
|
||||
pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts
|
||||
```
|
||||
|
||||
Now run the linked-device handshake. It streams the live QR (or the pairing-code
|
||||
card) to this terminal and, on success, reports the linked WhatsApp number. Run
|
||||
the command for the method chosen above — `qr` or `pairing-code`:
|
||||
(Bash timeout: 150000ms)
|
||||
|
||||
```nc:run effect:step capture:bot_phone=PHONE when:auth_method=qr
|
||||
The wrapper spawns `setup/index.ts --step whatsapp-auth -- --method qr`, parses each rotating QR from its `WHATSAPP_AUTH_QR` status blocks, and serves the current QR as a PNG on a local HTTP server (default port `8765`, falls back to a free port). Flags: `--clean` (wipes `store/auth/` before spawning) and `--port N`.
|
||||
|
||||
Tell the user:
|
||||
|
||||
> A browser window will open with a QR code.
|
||||
>
|
||||
> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
|
||||
> 2. Scan the QR code in the browser
|
||||
> 3. The page will show "Authenticated!" when done
|
||||
|
||||
For QR code in terminal:
|
||||
|
||||
```bash
|
||||
pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr
|
||||
```
|
||||
```nc:run effect:step capture:bot_phone=PHONE when:auth_method=pairing-code
|
||||
pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone {{phone}}
|
||||
|
||||
(Bash timeout: 150000ms)
|
||||
|
||||
The setup driver emits each rotating QR as a `WHATSAPP_AUTH_QR` status block; when run directly (not through `setup:auto`) the raw QR string is printed and your terminal must render it as ASCII. If your terminal can't render it readably, use the browser method above.
|
||||
|
||||
Tell the user:
|
||||
|
||||
> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
|
||||
> 2. Scan the QR code displayed in the terminal
|
||||
|
||||
For pairing code:
|
||||
|
||||
Tell the user to have WhatsApp open on **Settings > Linked Devices > Link a Device**, ready to tap **"Link with phone number instead"** — the code expires in ~60 seconds and must be entered immediately.
|
||||
|
||||
Run the auth process in the background and poll `store/pairing-code.txt` for the code:
|
||||
|
||||
```bash
|
||||
rm -f store/pairing-code.txt && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number> > /tmp/wa-auth.log 2>&1 &
|
||||
```
|
||||
|
||||
If the handshake fails (`logged_out` or a timeout), the code expired — clear
|
||||
`store/auth/` and run the step again for a fresh one. See Troubleshooting.
|
||||
Then immediately poll for the code (do NOT wait for the background command to finish):
|
||||
|
||||
A successful link reports the number back as `bot_phone`. If it came back empty,
|
||||
the device never confirmed (an expired QR or pairing code), so don't restart or
|
||||
wire against a blank number — clear `store/auth/` and re-run the link step first:
|
||||
|
||||
```nc:run effect:check
|
||||
[ -n "{{bot_phone}}" ]
|
||||
```bash
|
||||
for i in $(seq 1 20); do [ -f store/pairing-code.txt ] && cat store/pairing-code.txt && break; sleep 1; done
|
||||
```
|
||||
|
||||
## Restart
|
||||
Display the code to the user the moment it appears. Tell them:
|
||||
|
||||
Restart the service so it loads the WhatsApp adapter and picks up the
|
||||
credentials you just linked, and wait for its CLI socket before resolving:
|
||||
> **Enter this code now** — it expires in ~60 seconds.
|
||||
>
|
||||
> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
|
||||
> 2. Tap **Link with phone number instead**
|
||||
> 3. Enter the code immediately
|
||||
|
||||
```nc:run effect:restart
|
||||
bash setup/lib/restart.sh
|
||||
After the user enters the code, poll for authentication to complete:
|
||||
|
||||
```bash
|
||||
for i in $(seq 1 60); do grep -q 'STATUS: authenticated' /tmp/wa-auth.log 2>/dev/null && echo "authenticated" && break; grep -q 'STATUS: failed' /tmp/wa-auth.log 2>/dev/null && echo "failed" && break; sleep 2; done
|
||||
```
|
||||
|
||||
## Resolve your DM channel
|
||||
**If failed:** logged_out → delete `store/auth/` and re-run. timeout → ask user, offer retry.
|
||||
|
||||
The agent talks to you in your WhatsApp chat. Tell the user which number that
|
||||
chat happens on — usually the same one they just linked:
|
||||
### Verify authentication succeeded
|
||||
|
||||
```nc:operator
|
||||
You're linked to WhatsApp as +{{bot_phone}}.
|
||||
|
||||
- "shared" — you'll message the assistant from this same (personal) WhatsApp number. Replies land in your own "You" / self-chat.
|
||||
- "dedicated" — the assistant has its own separate phone/SIM, and you'll message it from a different number.
|
||||
```bash
|
||||
test -f store/auth/creds.json && echo "Authentication successful" || echo "Authentication failed"
|
||||
```
|
||||
|
||||
Pick which it is. Most people use `shared`:
|
||||
### Shared vs dedicated number
|
||||
|
||||
```nc:prompt number_kind validate:^(shared|dedicated)$
|
||||
Is the assistant on a `shared` number (your personal WhatsApp) or a `dedicated` number (a separate line for the assistant)?
|
||||
```
|
||||
AskUserQuestion: Is this a shared phone number (personal WhatsApp) or a dedicated number?
|
||||
- **Shared number** — your personal WhatsApp (bot prefixes messages with its name)
|
||||
- **Dedicated number** — a separate phone/SIM for the assistant
|
||||
|
||||
For a dedicated number, collect the number you'll actually chat from (skipped
|
||||
entirely for a shared number):
|
||||
If dedicated, add to `.env`:
|
||||
|
||||
```nc:prompt chat_phone validate:^\d{8,15}$ when:number_kind=dedicated
|
||||
The phone number you'll message the assistant from — digits only, country code first (e.g. 14155551234).
|
||||
```
|
||||
|
||||
A dedicated number means the assistant owns its own line, so outbound replies
|
||||
shouldn't be prefixed with its name. Record that (skipped for a shared number):
|
||||
|
||||
```nc:env-set when:number_kind=dedicated
|
||||
```bash
|
||||
ASSISTANT_HAS_OWN_NUMBER=true
|
||||
```
|
||||
Resolve the conversation address as the WhatsApp JID for the number you chat
|
||||
from — the linked number for a shared account, or the dedicated number you just
|
||||
gave. Run the one matching the choice above:
|
||||
|
||||
```nc:run capture:platform_id effect:fetch when:number_kind=shared
|
||||
echo "{{bot_phone}}@s.whatsapp.net"
|
||||
```
|
||||
```nc:run capture:platform_id effect:fetch when:number_kind=dedicated
|
||||
echo "{{chat_phone}}@s.whatsapp.net"
|
||||
```
|
||||
|
||||
For WhatsApp, your owner handle is that same JID:
|
||||
|
||||
```nc:run capture:owner_handle effect:fetch
|
||||
echo "{{platform_id}}"
|
||||
```
|
||||
|
||||
`owner_handle` and `platform_id` are what the owner-wiring step needs. The
|
||||
greeting goes out over your WhatsApp chat as soon as the service reconnects with
|
||||
the linked credentials.
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now. Otherwise wire
|
||||
this channel with `/init-first-agent` (or `/manage-channels`).
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
- **type**: `whatsapp`
|
||||
- **terminology**: WhatsApp calls them "groups" and "chats." A "chat" is a 1:1 DM; a "group" has multiple members.
|
||||
- **platform-id-format**: DMs use `<phone>@s.whatsapp.net` (e.g. `14155551234@s.whatsapp.net`). Groups use `<id>@g.us`. Native adapter — the JID is the platform ID as-is, no `whatsapp:` prefix.
|
||||
- **how-to-find-id**: To find your linked number after auth: `node -e "const c=JSON.parse(require('fs').readFileSync('store/auth/creds.json','utf-8'));console.log(c.me?.id?.split(':')[0].split('@')[0]+'@s.whatsapp.net')"`. Groups are auto-discovered — check `pnpm exec tsx scripts/q.ts data/v2.db "SELECT platform_id, name FROM messaging_groups WHERE channel_type='whatsapp' AND is_group=1"`.
|
||||
- **how-to-find-id**: DMs use `<phone>@s.whatsapp.net` (e.g. `14155551234@s.whatsapp.net`). Groups use `<id>@g.us`. To find your number: `node -e "const c=JSON.parse(require('fs').readFileSync('store/auth/creds.json','utf-8'));console.log(c.me?.id?.split(':')[0]+'@s.whatsapp.net')"`. Groups are auto-discovered — check `pnpm exec tsx scripts/q.ts data/v2.db "SELECT platform_id, name FROM messaging_groups WHERE channel_type='whatsapp' AND is_group=1"`.
|
||||
- **supports-threads**: no
|
||||
- **typical-use**: Interactive chat — direct messages or small groups
|
||||
- **default-isolation**: Same agent group if you're the only participant across multiple chats. Separate agent group if different people are in different groups.
|
||||
@@ -214,74 +228,18 @@ this channel with `/init-first-agent` (or `/manage-channels`).
|
||||
- Typing indicators — composing presence updates
|
||||
- Credential requests — text fallback (WhatsApp has no modal support)
|
||||
|
||||
Not supported (WhatsApp linked-device limitation): edit messages, delete messages.
|
||||
|
||||
## Alternatives
|
||||
|
||||
### QR code in a browser
|
||||
|
||||
Besides the in-terminal QR and the pairing code the Apply flow uses, this skill
|
||||
ships a helper that renders the rotating QR as a PNG in your default browser —
|
||||
handy when the terminal QR is too small to scan reliably. It spawns the same
|
||||
`whatsapp-auth` step, parses each rotating QR from its `WHATSAPP_AUTH_QR` status
|
||||
blocks, and serves the current one on a local HTTP server (default port `8765`,
|
||||
falls back to a free port):
|
||||
|
||||
```bash
|
||||
pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts
|
||||
```
|
||||
|
||||
Flags: `--clean` wipes `store/auth/` before spawning, `--port N` pins the port.
|
||||
|
||||
A browser window opens with a QR code. On your phone, open WhatsApp →
|
||||
**Settings** → **Linked Devices** → **Link a Device**, scan the QR, and the page
|
||||
shows "Authenticated!" when done.
|
||||
|
||||
### Headless environments
|
||||
|
||||
On a headless host (no display server — no `$DISPLAY`/`$WAYLAND_DISPLAY`, not
|
||||
macOS), the browser method can't open a window. Detect it and fall back to the
|
||||
pairing-code method (no camera needed):
|
||||
|
||||
```bash
|
||||
[[ -z "$DISPLAY" && -z "$WAYLAND_DISPLAY" && "$OSTYPE" != darwin* ]] && echo "IS_HEADLESS=true" || echo "IS_HEADLESS=false"
|
||||
```
|
||||
|
||||
## Optional configuration
|
||||
|
||||
If the assistant runs on a dedicated number (its own phone/SIM, not your personal
|
||||
WhatsApp), tell the adapter so it doesn't prefix outbound replies with its name:
|
||||
|
||||
```bash
|
||||
ASSISTANT_HAS_OWN_NUMBER=true
|
||||
```
|
||||
|
||||
The Apply flow sets this for you when you pick a `dedicated` number; this is the
|
||||
key it writes, for reference. A shared (personal) number leaves it unset.
|
||||
Not supported (WhatsApp linked device limitation): edit messages, delete messages.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### QR code or pairing code expired
|
||||
### QR code expired
|
||||
|
||||
Codes expire after ~60 seconds. The QR rotates automatically while the auth step
|
||||
is running; if the step exited, clear the auth state and re-run it:
|
||||
QR codes expire after ~60 seconds. The browser wrapper rotates automatically as long as it's running; if it was stopped, re-run with `--clean`:
|
||||
|
||||
```bash
|
||||
rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr
|
||||
pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts --clean
|
||||
```
|
||||
|
||||
For pairing code, ensure digits only (no `+`), the phone has internet, and
|
||||
WhatsApp is updated:
|
||||
|
||||
```bash
|
||||
rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <phone>
|
||||
```
|
||||
|
||||
WhatsApp's pairing-code flow occasionally rejects valid codes with "Couldn't link
|
||||
device." This is a server-side rejection unrelated to the code itself. If you hit
|
||||
it more than once, switch to the QR method — it has a noticeably higher success
|
||||
rate.
|
||||
|
||||
### Pairing code not working
|
||||
|
||||
Codes expire in ~60 seconds. Delete auth and retry:
|
||||
@@ -292,11 +250,7 @@ rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --met
|
||||
|
||||
Ensure: digits only (no `+`), phone has internet, WhatsApp is updated.
|
||||
|
||||
WhatsApp's pairing-code flow occasionally rejects valid codes with "Couldn't link
|
||||
device — An error happened. Please try again." This is a server-side rejection
|
||||
unrelated to the code itself; we've seen it happen twice in a row on fresh
|
||||
dedicated numbers. If you hit it more than once, switch to QR-browser auth — it
|
||||
has a noticeably higher success rate:
|
||||
WhatsApp's pairing-code flow occasionally rejects valid codes with "Couldn't link device — An error happened. Please try again." This is a server-side rejection unrelated to the code itself; we've seen it happen twice in a row on fresh dedicated numbers. If you hit it more than once, switch to QR-browser auth — it has a noticeably higher success rate:
|
||||
|
||||
```bash
|
||||
pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts --clean
|
||||
@@ -304,8 +258,9 @@ pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts --clean
|
||||
|
||||
### "waiting for this message" on reactions
|
||||
|
||||
WhatsApp sessions corrupted from rapid restarts. Clear sessions, then restart the
|
||||
service. Run from your NanoClaw project root:
|
||||
Signal sessions corrupted from rapid restarts. Clear sessions.
|
||||
|
||||
Run from your NanoClaw project root:
|
||||
|
||||
```bash
|
||||
source setup/lib/install-slug.sh
|
||||
@@ -323,5 +278,4 @@ systemctl --user start $(systemd_unit)
|
||||
|
||||
### "conflict" disconnection
|
||||
|
||||
Two instances connected with the same credentials. Ensure only one NanoClaw
|
||||
process is running.
|
||||
Two instances connected with same credentials. Ensure only one NanoClaw process is running.
|
||||
|
||||
@@ -13,18 +13,18 @@ Configure which host directories NanoClaw agent containers can access. The mount
|
||||
cat ~/.config/nanoclaw/mount-allowlist.json 2>/dev/null || echo "No mount allowlist configured"
|
||||
```
|
||||
|
||||
Show the current config to the user in a readable format: which directories are allowed, and whether each is read-only or read-write.
|
||||
Show the current config to the user in a readable format: which directories are allowed, whether non-main agents are read-only.
|
||||
|
||||
## Add Directories
|
||||
|
||||
Ask which directories the user wants agents to access. For each path:
|
||||
- Validate the path exists
|
||||
- Ask if it should be read-write (`allowReadWrite: true`) or read-only (`allowReadWrite: false`, the safer default)
|
||||
- Ask if it should be read-only for non-main agents (default: yes)
|
||||
|
||||
Build the JSON config and write it:
|
||||
|
||||
```bash
|
||||
pnpm exec tsx setup/index.ts --step mounts --force -- --json '{"allowedRoots":[{"path":"/path/to/dir","allowReadWrite":true}],"blockedPatterns":[]}'
|
||||
pnpm exec tsx setup/index.ts --step mounts --force -- --json '{"allowedRoots":[{"path":"/path/to/dir","readOnly":false}],"blockedPatterns":[],"nonMainReadOnly":true}'
|
||||
```
|
||||
|
||||
Use `--force` to overwrite the existing config.
|
||||
@@ -34,7 +34,7 @@ Use `--force` to overwrite the existing config.
|
||||
Read the current config, show it, ask which entry to remove, then write the updated config through the same write path (build the trimmed JSON and pass it to `--step mounts --force -- --json`):
|
||||
|
||||
```bash
|
||||
pnpm exec tsx setup/index.ts --step mounts --force -- --json '{"allowedRoots":[],"blockedPatterns":[]}'
|
||||
pnpm exec tsx setup/index.ts --step mounts --force -- --json '{"allowedRoots":[],"blockedPatterns":[],"nonMainReadOnly":true}'
|
||||
```
|
||||
|
||||
## Reset to Empty
|
||||
@@ -45,10 +45,12 @@ pnpm exec tsx setup/index.ts --step mounts --force -- --empty
|
||||
|
||||
## After Changes
|
||||
|
||||
The allowlist is read fresh when a container is spawned, so new mounts apply to newly spawned containers automatically — no service restart needed.
|
||||
Restart the service so containers pick up the new config (the unit/label names are per-install — see `setup/lib/install-slug.sh`).
|
||||
|
||||
To apply the new config to a group that already has a running container, restart just that group:
|
||||
Run from your NanoClaw project root:
|
||||
|
||||
```bash
|
||||
ncl groups restart --id <group-id>
|
||||
source setup/lib/install-slug.sh
|
||||
launchctl kickstart -k gui/$(id -u)/$(launchd_label) # macOS
|
||||
systemctl --user restart $(systemd_unit) # Linux
|
||||
```
|
||||
|
||||
@@ -71,7 +71,7 @@ For ad-hoc queries from skills or scripts, use the in-tree wrapper rather than t
|
||||
| `src/command-gate.ts` | Router-side admin command gate — queries `user_roles` directly (no env var, no container-side check) |
|
||||
| `src/modules/approvals/onecli-approvals.ts` | OneCLI credentialed-action approval bridge |
|
||||
| `src/modules/permissions/user-dm.ts` | Cold-DM resolution + `user_dms` cache |
|
||||
| `src/group-init.ts` | Per-agent-group filesystem scaffold (CLAUDE.md, skills) — agent-runner source is a shared read-only mount, not copied per group |
|
||||
| `src/group-init.ts` | Per-agent-group filesystem scaffold (CLAUDE.md, skills, agent-runner-src overlay) |
|
||||
| `src/db/container-configs.ts` | CRUD for `container_configs` table (per-group container runtime config) |
|
||||
| `src/backfill-container-configs.ts` | Migrates legacy `container.json` files into the DB on startup |
|
||||
| `src/container-restart.ts` | Kill + on-wake respawn for agent group containers |
|
||||
@@ -79,8 +79,8 @@ For ad-hoc queries from skills or scripts, use the in-tree wrapper rather than t
|
||||
| `src/channels/` | Channel adapter infra (registry, Chat SDK bridge); specific channel adapters are skill-installed from the `channels` branch |
|
||||
| `src/providers/` | Host-side provider container-config (`claude` baked in; `opencode` etc. installed from the `providers` branch) |
|
||||
| `container/agent-runner/src/` | Agent-runner: poll loop, formatter, provider abstraction, MCP tools, destinations |
|
||||
| `container/skills/` | Container skills mounted into every agent session (`agent-browser`, `frontend-engineer`, `onecli-gateway`, `self-customize`, `slack-formatting`, `vercel-cli`, `welcome`, `whatsapp-formatting`) |
|
||||
| `groups/<folder>/` | Per-agent-group filesystem (CLAUDE.md, skills) — agent-runner source is a shared read-only mount, not copied per group |
|
||||
| `container/skills/` | Container skills mounted into every agent session (`onecli-gateway`, `welcome`, `self-customize`, `agent-browser`, `slack-formatting`) |
|
||||
| `groups/<folder>/` | Per-agent-group filesystem (CLAUDE.md, skills, per-group `agent-runner-src/` overlay) |
|
||||
| `scripts/init-first-agent.ts` | Bootstrap the first DM-wired agent (used by `/init-first-agent` skill) |
|
||||
| `migrate-v2.sh` + `setup/migrate-v2/` | v1→v2 migration. Standalone script: `bash migrate-v2.sh`. Seeds DB, copies groups/sessions, installs channels, builds container, offers service switchover, then hands off to `/migrate-from-v1` skill for owner setup and CLAUDE.md cleanup. See [docs/migration-dev.md](docs/migration-dev.md). |
|
||||
| `nanoclaw.sh --uninstall` + `setup/uninstall/` | Uninstall this copy only (slug-scoped): service, containers + image, `data/`, `logs/`, `groups/`, this copy's OneCLI agents. Confirms per group; `--dry-run` previews, `--yes` skips prompts. Other copies and the shared OneCLI app are untouched. Bypasses bootstrap entirely; `uninstall.sh` is a pointer that execs it. |
|
||||
@@ -182,7 +182,7 @@ Four types of skills. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full taxono
|
||||
- **Channel/provider install skills** — copy the relevant module(s) in from the `channels` or `providers` branch, wire imports, install pinned deps (e.g. `/add-discord`, `/add-slack`, `/add-whatsapp`, `/add-opencode`).
|
||||
- **Utility skills** — ship code files alongside `SKILL.md` (e.g. a `scripts/` CLI or helper).
|
||||
- **Operational skills** — instruction-only workflows (`/setup`, `/debug`, `/customize`, `/init-first-agent`, `/manage-channels`, `/init-onecli`, `/update-nanoclaw`).
|
||||
- **Container skills** — loaded inside agent containers at runtime (`container/skills/`: `agent-browser`, `frontend-engineer`, `onecli-gateway`, `self-customize`, `slack-formatting`, `vercel-cli`, `welcome`, `whatsapp-formatting`).
|
||||
- **Container skills** — loaded inside agent containers at runtime (`container/skills/`: `onecli-gateway`, `welcome`, `self-customize`, `agent-browser`, `slack-formatting`).
|
||||
|
||||
| Skill | When to Use |
|
||||
|-------|-------------|
|
||||
|
||||
@@ -80,7 +80,7 @@ See [docs/v1-to-v2-changes.md](docs/v1-to-v2-changes.md) for what's different an
|
||||
- **Per-agent workspace** — each agent group has its own `CLAUDE.md`, its own memory, its own container, and only the mounts you allow. Nothing crosses the boundary unless you wire it to.
|
||||
- **Scheduled tasks** — recurring jobs that run Claude and can message you back
|
||||
- **Web access** — search and fetch content from the web
|
||||
- **Container isolation** — agents are sandboxed in Docker (macOS/Linux/WSL2), with optional Docker Sandboxes micro-VM isolation
|
||||
- **Container isolation** — agents are sandboxed in Docker (macOS/Linux/WSL2), with optional [Docker Sandboxes](docs/docker-sandboxes.md) micro-VM isolation or Apple Container as a macOS-native opt-in
|
||||
- **Credential security** — agents never hold raw API keys. Outbound requests route through [OneCLI's Agent Vault](https://github.com/onecli/onecli), which injects credentials at request time and enforces per-agent policies and rate limits.
|
||||
- **Agent templates**: stamp a ready-to-run agent (instructions + MCP tools + skills, no secrets) from a reusable bundle, via the setup wizard or `ncl groups create --template <ref>`. Load from the [public library](https://github.com/nanocoai/nanoclaw-templates), a local folder, or any git repo. See [docs/templates.md](docs/templates.md).
|
||||
|
||||
@@ -165,7 +165,7 @@ Key files:
|
||||
|
||||
**Why Docker?**
|
||||
|
||||
Docker provides cross-platform support (macOS, Linux and Windows via WSL2) and a mature ecosystem. For additional isolation, Docker Sandboxes run each container inside a micro VM.
|
||||
Docker provides cross-platform support (macOS, Linux and Windows via WSL2) and a mature ecosystem. On macOS, Apple Container is also supported as a lighter-weight native runtime. For additional isolation, [Docker Sandboxes](docs/docker-sandboxes.md) run each container inside a micro VM.
|
||||
|
||||
**Can I run this on Linux or Windows?**
|
||||
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
/**
|
||||
* Per-batch context the poll loop publishes for downstream consumers
|
||||
* (MCP tools, etc.) that don't sit on the poll-loop's call stack.
|
||||
*
|
||||
* Today the only field is `inReplyTo` — the id of the first inbound
|
||||
* message in the batch the agent is currently processing. MCP tools like
|
||||
* `send_message` and `send_file` read this and stamp it onto the outbound
|
||||
* row so the host's a2a return-path routing can correlate replies back to
|
||||
* the originating session.
|
||||
*
|
||||
* This is module-level state on purpose: the agent-runner is single-process
|
||||
* and processes one batch at a time. Poll-loop calls `setCurrentInReplyTo`
|
||||
* before invoking the provider and `clearCurrentInReplyTo` after the batch
|
||||
* completes (or errors out).
|
||||
*/
|
||||
let currentInReplyTo: string | null = null;
|
||||
|
||||
export function setCurrentInReplyTo(id: string | null): void {
|
||||
currentInReplyTo = id;
|
||||
}
|
||||
|
||||
export function clearCurrentInReplyTo(): void {
|
||||
currentInReplyTo = null;
|
||||
}
|
||||
|
||||
export function getCurrentInReplyTo(): string | null {
|
||||
return currentInReplyTo;
|
||||
}
|
||||
|
||||
@@ -48,11 +48,7 @@ export function openInboundDb(): Database {
|
||||
// so the singleton survives for the rest of the test.
|
||||
if (_testMode && _inbound) {
|
||||
const db = _inbound;
|
||||
return {
|
||||
prepare: (sql: string) => db.prepare(sql),
|
||||
exec: (sql: string) => db.exec(sql),
|
||||
close: () => {},
|
||||
} as unknown as Database;
|
||||
return { prepare: (sql: string) => db.prepare(sql), exec: (sql: string) => db.exec(sql), close: () => {} } as unknown as Database;
|
||||
}
|
||||
const db = new Database(DEFAULT_INBOUND_PATH, { readonly: true });
|
||||
db.exec('PRAGMA busy_timeout = 5000');
|
||||
@@ -264,3 +260,11 @@ export function closeSessionDb(): void {
|
||||
_outbound?.close();
|
||||
_outbound = null;
|
||||
}
|
||||
|
||||
/**
|
||||
* @deprecated Use getInboundDb() / getOutboundDb() instead.
|
||||
* Kept for backward compatibility during migration.
|
||||
*/
|
||||
export function getSessionDb(): Database {
|
||||
return getInboundDb();
|
||||
}
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
export {
|
||||
getInboundDb,
|
||||
getOutboundDb,
|
||||
getSessionDb,
|
||||
initTestSessionDb,
|
||||
closeSessionDb,
|
||||
touchHeartbeat,
|
||||
|
||||
@@ -56,7 +56,7 @@ function getMaxMessagesPerPrompt(): number {
|
||||
* Reads from inbound.db (read-only), filters against processing_ack in outbound.db
|
||||
* to skip messages already picked up by this or a previous container run.
|
||||
*
|
||||
* Returns the most recent `maxMessagesPerPrompt` pending rows in
|
||||
* Returns the most recent `MAX_MESSAGES_PER_PROMPT` pending rows in
|
||||
* chronological order, regardless of their `trigger` flag: accumulated
|
||||
* context (trigger=0) rides along with the wake-eligible rows so the agent
|
||||
* sees the prior context it missed. Host's countDueMessages gates waking on
|
||||
@@ -163,3 +163,4 @@ export function findQuestionResponse(questionId: string): MessageInRow | undefin
|
||||
inbound.close();
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -77,47 +77,3 @@ export function setContinuation(providerName: string, id: string): void {
|
||||
export function clearContinuation(providerName: string): void {
|
||||
deleteValue(continuationKey(providerName));
|
||||
}
|
||||
|
||||
/**
|
||||
* The a2a reply stamp: the id of the first inbound message in the batch the
|
||||
* agent is currently processing. The poll loop publishes it at batch start;
|
||||
* MCP tools (`send_message`, `send_file`) read it and stamp it onto outbound
|
||||
* rows so the host's a2a return-path routing can correlate replies back to
|
||||
* the originating session.
|
||||
*
|
||||
* This lives in outbound.db rather than module state because the MCP server
|
||||
* runs as a separate stdio subprocess from the poll loop — module state set
|
||||
* by the poll loop is invisible to it. Both processes open outbound.db
|
||||
* (journal_mode=DELETE + busy_timeout make intra-container access safe).
|
||||
*/
|
||||
const IN_REPLY_TO_KEY = 'current_in_reply_to';
|
||||
|
||||
/**
|
||||
* Ignore a stamp older than this. The poll loop clears the stamp in a
|
||||
* finally, but a container killed mid-batch (SIGKILL) can leave one behind;
|
||||
* the guard stops a later out-of-batch read from picking up a dead stamp.
|
||||
* Generous so a long-running batch's late sends still stamp correctly.
|
||||
*/
|
||||
const IN_REPLY_TO_MAX_AGE_MS = 30 * 60 * 1000;
|
||||
|
||||
export function setCurrentInReplyTo(id: string | null): void {
|
||||
if (id === null) {
|
||||
clearCurrentInReplyTo();
|
||||
return;
|
||||
}
|
||||
setValue(IN_REPLY_TO_KEY, id);
|
||||
}
|
||||
|
||||
export function clearCurrentInReplyTo(): void {
|
||||
deleteValue(IN_REPLY_TO_KEY);
|
||||
}
|
||||
|
||||
export function getCurrentInReplyTo(): string | null {
|
||||
const row = getOutboundDb()
|
||||
.prepare('SELECT value, updated_at FROM session_state WHERE key = ?')
|
||||
.get(IN_REPLY_TO_KEY) as { value: string; updated_at: string } | undefined;
|
||||
if (!row) return null;
|
||||
const age = Date.now() - new Date(row.updated_at).getTime();
|
||||
if (!Number.isFinite(age) || age > IN_REPLY_TO_MAX_AGE_MS) return null;
|
||||
return row.value;
|
||||
}
|
||||
|
||||
@@ -4,31 +4,14 @@
|
||||
* batch in poll-loop, and outbound writes from MCP tools (send_message,
|
||||
* send_file) must pick it up so a2a return-path routing on the host can
|
||||
* correlate replies back to the originating session.
|
||||
*
|
||||
* The stamp is published through session_state in outbound.db, not module
|
||||
* state — the MCP server runs as a separate stdio subprocess from the poll
|
||||
* loop, so it can only see the stamp through the shared DB. These tests seed
|
||||
* it the same way the poll-loop process does (a direct DB write) rather than
|
||||
* via any in-memory helper, so they exercise the real process boundary.
|
||||
*/
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
|
||||
|
||||
import { initTestSessionDb, closeSessionDb, getInboundDb, getOutboundDb } from '../db/connection.js';
|
||||
import { initTestSessionDb, closeSessionDb, getInboundDb } from '../db/connection.js';
|
||||
import { getUndeliveredMessages } from '../db/messages-out.js';
|
||||
import { setCurrentInReplyTo, clearCurrentInReplyTo } from '../current-batch.js';
|
||||
import { sendMessage } from './core.js';
|
||||
|
||||
/**
|
||||
* Publish the a2a reply stamp the way the poll loop does: a direct write to
|
||||
* session_state in outbound.db. `ageMs` back-dates updated_at to exercise the
|
||||
* staleness guard MCP tools apply when reading it.
|
||||
*/
|
||||
function publishInReplyTo(id: string, ageMs = 0): void {
|
||||
const updatedAt = new Date(Date.now() - ageMs).toISOString();
|
||||
getOutboundDb()
|
||||
.prepare('INSERT OR REPLACE INTO session_state (key, value, updated_at) VALUES (?, ?, ?)')
|
||||
.run('current_in_reply_to', id, updatedAt);
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
initTestSessionDb();
|
||||
// Seed a peer agent destination
|
||||
@@ -41,12 +24,13 @@ beforeEach(() => {
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
clearCurrentInReplyTo();
|
||||
closeSessionDb();
|
||||
});
|
||||
|
||||
describe('send_message MCP tool — in_reply_to plumbing', () => {
|
||||
it('stamps the batch in_reply_to (published via the DB) on outbound rows', async () => {
|
||||
publishInReplyTo('inbound-msg-1');
|
||||
it('stamps current batch in_reply_to on outbound rows', async () => {
|
||||
setCurrentInReplyTo('inbound-msg-1');
|
||||
|
||||
await sendMessage.handler({ to: 'peer', text: 'hello' });
|
||||
|
||||
@@ -56,17 +40,7 @@ describe('send_message MCP tool — in_reply_to plumbing', () => {
|
||||
});
|
||||
|
||||
it('writes null when no batch is active', async () => {
|
||||
// Nothing published to session_state — simulates ad-hoc / out-of-batch invocation.
|
||||
await sendMessage.handler({ to: 'peer', text: 'hello' });
|
||||
|
||||
const out = getUndeliveredMessages();
|
||||
expect(out).toHaveLength(1);
|
||||
expect(out[0].in_reply_to).toBeNull();
|
||||
});
|
||||
|
||||
it('ignores a stale stamp left behind by a killed container', async () => {
|
||||
publishInReplyTo('inbound-msg-1', 60 * 60 * 1000); // an hour old
|
||||
|
||||
// No setCurrentInReplyTo before this call — simulates ad-hoc / out-of-batch invocation.
|
||||
await sendMessage.handler({ to: 'peer', text: 'hello' });
|
||||
|
||||
const out = getUndeliveredMessages();
|
||||
|
||||
@@ -9,9 +9,9 @@
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
|
||||
import { getCurrentInReplyTo } from '../current-batch.js';
|
||||
import { findByName, getAllDestinations } from '../destinations.js';
|
||||
import { getMessageIdBySeq, getRoutingBySeq, writeMessageOut } from '../db/messages-out.js';
|
||||
import { getCurrentInReplyTo } from '../db/session-state.js';
|
||||
import { getSessionRouting } from '../db/session-routing.js';
|
||||
import { registerTools } from './server.js';
|
||||
import type { McpToolDefinition } from './types.js';
|
||||
|
||||
@@ -2,13 +2,8 @@ import { findByName, getAllDestinations, type DestinationEntry } from './destina
|
||||
import { getPendingMessages, markProcessing, markCompleted, type MessageInRow } from './db/messages-in.js';
|
||||
import { writeMessageOut } from './db/messages-out.js';
|
||||
import { getInboundDb, touchHeartbeat, clearStaleProcessingAcks } from './db/connection.js';
|
||||
import {
|
||||
clearContinuation,
|
||||
clearCurrentInReplyTo,
|
||||
migrateLegacyContinuation,
|
||||
setContinuation,
|
||||
setCurrentInReplyTo,
|
||||
} from './db/session-state.js';
|
||||
import { clearContinuation, migrateLegacyContinuation, setContinuation } from './db/session-state.js';
|
||||
import { clearCurrentInReplyTo, setCurrentInReplyTo } from './current-batch.js';
|
||||
import {
|
||||
formatMessages,
|
||||
extractRouting,
|
||||
|
||||
@@ -3,3 +3,4 @@
|
||||
// level. Skills add a new provider by appending one import line below.
|
||||
|
||||
import './claude.js';
|
||||
import './mock.js';
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
# Apple Container Networking Setup (macOS 26)
|
||||
|
||||
Apple Container's vmnet networking requires manual configuration for containers to access the internet. Without this, containers can communicate with the host but cannot reach external services (DNS, HTTPS, APIs).
|
||||
|
||||
## Quick Setup
|
||||
|
||||
Run these two commands (requires `sudo`):
|
||||
|
||||
```bash
|
||||
# 1. Enable IP forwarding so the host routes container traffic
|
||||
sudo sysctl -w net.inet.ip.forwarding=1
|
||||
|
||||
# 2. Enable NAT so container traffic gets masqueraded through your internet interface
|
||||
echo "nat on en0 from 192.168.64.0/24 to any -> (en0)" | sudo pfctl -ef -
|
||||
```
|
||||
|
||||
> **Note:** Replace `en0` with your active internet interface. Check with: `route get 8.8.8.8 | grep interface`
|
||||
|
||||
## Making It Persistent
|
||||
|
||||
These settings reset on reboot. To make them permanent:
|
||||
|
||||
**IP Forwarding** — add to `/etc/sysctl.conf`:
|
||||
```
|
||||
net.inet.ip.forwarding=1
|
||||
```
|
||||
|
||||
**NAT Rules** — add to `/etc/pf.conf` (before any existing rules):
|
||||
```
|
||||
nat on en0 from 192.168.64.0/24 to any -> (en0)
|
||||
```
|
||||
|
||||
Then reload: `sudo pfctl -f /etc/pf.conf`
|
||||
|
||||
## IPv6 DNS Issue
|
||||
|
||||
By default, DNS resolvers return IPv6 (AAAA) records before IPv4 (A) records. Since our NAT only handles IPv4, Node.js applications inside containers will try IPv6 first and fail.
|
||||
|
||||
The container image and runner are configured to prefer IPv4 via:
|
||||
```
|
||||
NODE_OPTIONS=--dns-result-order=ipv4first
|
||||
```
|
||||
|
||||
This is set both in the `Dockerfile` and passed via `-e` flag in `container-runner.ts`.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# Check IP forwarding is enabled
|
||||
sysctl net.inet.ip.forwarding
|
||||
# Expected: net.inet.ip.forwarding: 1
|
||||
|
||||
# Test container internet access
|
||||
container run --rm --entrypoint curl nanoclaw-agent:latest \
|
||||
-s4 --connect-timeout 5 -o /dev/null -w "%{http_code}" https://api.anthropic.com
|
||||
# Expected: 404
|
||||
|
||||
# Check bridge interface (only exists when a container is running)
|
||||
ifconfig bridge100
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Cause | Fix |
|
||||
|---------|-------|-----|
|
||||
| `curl: (28) Connection timed out` | IP forwarding disabled | `sudo sysctl -w net.inet.ip.forwarding=1` |
|
||||
| HTTP works, HTTPS times out | IPv6 DNS resolution | Add `NODE_OPTIONS=--dns-result-order=ipv4first` |
|
||||
| `Could not resolve host` | DNS not forwarded | Check bridge100 exists, verify pfctl NAT rules |
|
||||
| Container hangs after output | Missing `process.exit(0)` in agent-runner | Rebuild container image |
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
Container VM (192.168.64.x)
|
||||
│
|
||||
├── eth0 → gateway 192.168.64.1
|
||||
│
|
||||
bridge100 (192.168.64.1) ← host bridge, created by vmnet when container runs
|
||||
│
|
||||
├── IP forwarding (sysctl) routes packets from bridge100 → en0
|
||||
│
|
||||
├── NAT (pfctl) masquerades 192.168.64.0/24 → en0's IP
|
||||
│
|
||||
en0 (your WiFi/Ethernet) → Internet
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [apple/container#469](https://github.com/apple/container/issues/469) — No network from container on macOS 26
|
||||
- [apple/container#656](https://github.com/apple/container/issues/656) — Cannot access internet URLs during building
|
||||
@@ -6,5 +6,8 @@ The files in this directory are original design documents and developer referenc
|
||||
|
||||
| This directory | Documentation site |
|
||||
|---|---|
|
||||
| [SPEC.md](SPEC.md) | [Architecture](https://docs.nanoclaw.dev/concepts/architecture) |
|
||||
| [SECURITY.md](SECURITY.md) | [Security model](https://docs.nanoclaw.dev/concepts/security) |
|
||||
| [REQUIREMENTS.md](REQUIREMENTS.md) | [Introduction](https://docs.nanoclaw.dev/introduction) |
|
||||
| [docker-sandboxes.md](docker-sandboxes.md) | [Docker Sandboxes](https://docs.nanoclaw.dev/advanced/docker-sandboxes) |
|
||||
| [APPLE-CONTAINER-NETWORKING.md](APPLE-CONTAINER-NETWORKING.md) | [Container runtime](https://docs.nanoclaw.dev/advanced/container-runtime) |
|
||||
|
||||
+59
-105
@@ -1,106 +1,70 @@
|
||||
# NanoClaw Security Model
|
||||
|
||||
> The canonical, continuously-verified version of this model lives at
|
||||
> [docs.nanoclaw.dev/concepts/security](https://docs.nanoclaw.dev/concepts/security).
|
||||
> This in-repo copy can drift; if the two disagree, verify against
|
||||
> `src/container-runner.ts` (`buildMounts`).
|
||||
|
||||
## Trust Model
|
||||
|
||||
Privilege is **user-level**, persisted in the `user_roles` table (owner /
|
||||
admin, global or scoped to an agent group) plus `agent_group_members` (the
|
||||
unprivileged access gate).
|
||||
|
||||
| Entity | Trust Level | Rationale |
|
||||
|--------|-------------|-----------|
|
||||
| Owners / admins (`user_roles`) | Trusted | Hold owner/admin roles; gate admin commands and approve credentialed actions |
|
||||
| Group members (`agent_group_members`) | Access-gated | Membership grants access to an agent group, but their messages are still untrusted input |
|
||||
| Unregistered senders | Untrusted | Subject to each messaging group's `unknown_sender_policy` |
|
||||
| Agent containers | Sandboxed | Long-lived per-session container; isolated by mounts, non-root, no host reach |
|
||||
| Incoming messages | User input | Potential prompt injection regardless of who sent them |
|
||||
| Main group | Trusted | Private self-chat, admin control |
|
||||
| Non-main groups | Untrusted | Other users may be malicious |
|
||||
| Container agents | Sandboxed | Isolated execution environment |
|
||||
| Incoming messages | User input | Potential prompt injection |
|
||||
|
||||
## Security Boundaries
|
||||
|
||||
### 1. Container Isolation (Primary Boundary)
|
||||
|
||||
Agents execute in containers (Docker), providing:
|
||||
- **Process isolation** — container processes cannot affect the host
|
||||
- **Filesystem isolation** — only explicitly mounted directories are visible
|
||||
- **Non-root execution** — runs as an unprivileged user (`node`, uid 1000, or the host uid remapped in)
|
||||
- **Per-session containers** — one long-lived container per session polls that session's DBs and handles many messages, then is torn down (`--rm`) when the session goes idle.
|
||||
Agents execute in containers (lightweight Linux VMs), providing:
|
||||
- **Process isolation** - Container processes cannot affect the host
|
||||
- **Filesystem isolation** - Only explicitly mounted directories are visible
|
||||
- **Non-root execution** - Runs as unprivileged `node` user (uid 1000)
|
||||
- **Ephemeral containers** - Fresh environment per invocation (`--rm`)
|
||||
|
||||
This is the primary security boundary. Rather than relying on application-level
|
||||
permission checks, the attack surface is limited by what's mounted.
|
||||
This is the primary security boundary. Rather than relying on application-level permission checks, the attack surface is limited by what's mounted.
|
||||
|
||||
### 2. Mount Security
|
||||
|
||||
`buildMounts` (`src/container-runner.ts`) composes a fixed set of mounts per
|
||||
spawn. For the default (Claude) provider these are:
|
||||
|
||||
| Container path | Host source | Mode | Purpose |
|
||||
|---|---|---|---|
|
||||
| `/workspace` | `data/v2-sessions/<group>/<session>/` | RW | Session folder — `inbound.db`, `outbound.db`, `outbox/`, `.claude/` |
|
||||
| `/workspace/agent` | `groups/<folder>/` | RW | Agent group working files + `CLAUDE.local.md` |
|
||||
| `/workspace/agent/container.json` | group `container.json` | RO | Container config — readable, not writable |
|
||||
| `/workspace/agent/CLAUDE.md` | composed `CLAUDE.md` | RO | Regenerated every spawn; agent edits would be clobbered |
|
||||
| `/workspace/agent/.claude-fragments` | group `.claude-fragments/` | RO | Composer skill/MCP fragments |
|
||||
| `/app/CLAUDE.md` | `container/CLAUDE.md` | RO | Shared base doc imported by the composed entry point |
|
||||
| `/home/node/.claude` | `data/v2-sessions/<group>/.claude-shared/` | RW | Claude state, settings, skill symlinks |
|
||||
| `/app/src` | `container/agent-runner/src/` | RO | Shared agent-runner source (same for all groups) |
|
||||
| `/app/skills` | `container/skills/` | RO | Shared container skills |
|
||||
| `/workspace/extra/<name>` | allowlisted host dir | RO (RW only if allowed) | Operator-configured additional mounts |
|
||||
|
||||
The config mounts (`container.json`, `CLAUDE.md`, `.claude-fragments`) are
|
||||
**nested read-only mounts on top of the read-write group dir** — the agent can
|
||||
read its config but cannot modify it. The project root is **never mounted**: the
|
||||
container only ever sees the paths above plus any provider-contributed mounts
|
||||
(e.g. an OpenCode XDG dir). Host application source (`src/`, `dist/`,
|
||||
`package.json`) is not reachable.
|
||||
|
||||
**Additional-mount allowlist** — extra mounts from a group's container config
|
||||
are validated against an allowlist at `~/.config/nanoclaw/mount-allowlist.json`,
|
||||
which is:
|
||||
- Outside the project root
|
||||
**External Allowlist** - Mount permissions stored at `~/.config/nanoclaw/mount-allowlist.json`, which is:
|
||||
- Outside project root
|
||||
- Never mounted into containers
|
||||
- Not modifiable by agents
|
||||
- Cannot be modified by agents
|
||||
|
||||
Its schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"allowedRoots": [
|
||||
{ "path": "~/projects", "allowReadWrite": true, "description": "Dev projects" },
|
||||
{ "path": "~/Documents/work", "allowReadWrite": false, "description": "Read-only" }
|
||||
],
|
||||
"blockedPatterns": ["password", "secret", "token"]
|
||||
}
|
||||
**Default Blocked Patterns:**
|
||||
```
|
||||
|
||||
**Default blocked patterns** (merged with any in the file):
|
||||
```
|
||||
.ssh, .gnupg, .gpg, .aws, .azure, .gcloud, .kube, .docker,
|
||||
credentials, .env, .netrc, .npmrc, .pypirc, id_rsa, id_ed25519,
|
||||
.ssh, .gnupg, .aws, .azure, .gcloud, .kube, .docker,
|
||||
credentials, .env, .netrc, .npmrc, id_rsa, id_ed25519,
|
||||
private_key, .secret
|
||||
```
|
||||
|
||||
**Enforcement** (`src/modules/mount-security/index.ts`):
|
||||
- **No allowlist file ⇒ every additional mount is blocked** — the fixed mounts above are unaffected, but nothing extra is granted until the operator creates the file.
|
||||
- Symlinks are resolved to their real path (`realpathSync`) before any check, defeating traversal via symlink.
|
||||
- The real path is rejected if it matches a blocked pattern, and rejected unless it sits under one of `allowedRoots`.
|
||||
- The container path is validated: relative, non-empty, no `..`, no leading `/`, no `:` (blocks Docker `-v` option injection). It is mounted under `/workspace/extra/`.
|
||||
- **Read-write is granted only when the mount requests it (`readonly: false`) *and* the matched root has `allowReadWrite: true`.** Otherwise the mount is forced read-only.
|
||||
**Protections:**
|
||||
- Symlink resolution before validation (prevents traversal attacks)
|
||||
- Container path validation (rejects `..` and absolute paths)
|
||||
- `nonMainReadOnly` option forces read-only for non-main groups
|
||||
|
||||
**Read-Only Project Root:**
|
||||
|
||||
The main group's project root is mounted read-only. Writable paths the agent needs (store, group folder, IPC, `.claude/`) are mounted separately. This prevents the agent from modifying host application code (`src/`, `dist/`, `package.json`, etc.) which would bypass the sandbox entirely on next restart. The `store/` directory is mounted read-write so the main agent can access the SQLite database directly.
|
||||
|
||||
### 3. Session Isolation
|
||||
|
||||
Per-session state lives under `data/v2-sessions/<agent-group>/<session>/`
|
||||
(`inbound.db`, `outbound.db`, `outbox/`, `.claude/`). Claude state
|
||||
(`.claude-shared`) and the working folder are scoped to the agent group, so:
|
||||
- Different agent groups cannot see each other's conversation history or files.
|
||||
- A group's sessions share that group's memory but keep separate message DBs.
|
||||
Each group has isolated Claude sessions at `data/sessions/{group}/.claude/`:
|
||||
- Groups cannot see other groups' conversation history
|
||||
- Session data includes full message history and file contents read
|
||||
- Prevents cross-group information disclosure
|
||||
|
||||
This prevents cross-group information disclosure.
|
||||
### 4. IPC Authorization
|
||||
|
||||
### 4. Credential Isolation (OneCLI Agent Vault)
|
||||
Messages and task operations are verified against group identity:
|
||||
|
||||
| Operation | Main Group | Non-Main Group |
|
||||
|-----------|------------|----------------|
|
||||
| Send message to own chat | ✓ | ✓ |
|
||||
| Send message to other chats | ✓ | ✗ |
|
||||
| Schedule task for self | ✓ | ✓ |
|
||||
| Schedule task for others | ✓ | ✗ |
|
||||
| View all tasks | ✓ | Own only |
|
||||
| Manage other groups | ✓ | ✗ |
|
||||
|
||||
### 5. Credential Isolation (OneCLI Agent Vault)
|
||||
|
||||
Real API credentials **never enter containers**. NanoClaw uses [OneCLI's Agent Vault](https://github.com/onecli/onecli) to proxy outbound requests and inject credentials at the gateway level.
|
||||
|
||||
@@ -113,12 +77,13 @@ Real API credentials **never enter containers**. NanoClaw uses [OneCLI's Agent V
|
||||
**Per-agent policies:**
|
||||
Each NanoClaw group gets its own OneCLI agent identity. This allows different credential policies per group (e.g. your sales agent vs. support agent). OneCLI supports rate limits, and time-bound access and approval flows are on the roadmap.
|
||||
|
||||
**Never on the container filesystem:**
|
||||
- The project root and `.env` — never mounted; the container only receives the paths in the mount table above.
|
||||
- The mount allowlist — external (`~/.config/nanoclaw/…`), never mounted.
|
||||
- Real credentials — injected per request by the OneCLI gateway, never written into any mount.
|
||||
**NOT Mounted:**
|
||||
- Channel auth sessions (`store/auth/`) — host only
|
||||
- Mount allowlist — external, never mounted
|
||||
- Any credentials matching blocked patterns
|
||||
- `.env` is shadowed with `/dev/null` in the project root mount
|
||||
|
||||
### 5. Egress Lockdown (Forced Proxy)
|
||||
### 6. Egress Lockdown (Forced Proxy)
|
||||
|
||||
The `HTTPS_PROXY` env var only redirects *proxy-aware* clients — a tool that
|
||||
ignores it (or a raw socket) could reach the internet directly and bypass
|
||||
@@ -146,42 +111,31 @@ no `host-gateway` route).
|
||||
exception: a heal failure there is logged but not fatal, since already-running
|
||||
agents stay on the internal net (no leak) until the gateway returns.
|
||||
|
||||
**Default: egress is open.** Lockdown is **off** unless you opt in; by default
|
||||
the agent reaches the OneCLI gateway over the host-gateway path and outbound
|
||||
traffic is not confined to the internal network.
|
||||
|
||||
**Configuration:**
|
||||
|
||||
| Env | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `NANOCLAW_EGRESS_LOCKDOWN` | `false` | Set `true` to opt in (otherwise the host-gateway path is used). |
|
||||
| `NANOCLAW_EGRESS_LOCKDOWN` | `false` | Set `true` to opt in (otherwise the host-gateway path is used). Enabled automatically by `/add-golden-registry`. |
|
||||
| `NANOCLAW_EGRESS_NETWORK` | `nanoclaw-egress` | Network name. |
|
||||
| `ONECLI_GATEWAY_CONTAINER` | `onecli` | Gateway container to attach. |
|
||||
|
||||
These variables are read from the **host process** environment (the service's
|
||||
environment / `.env`), not from inside the container. The agent container is
|
||||
started with only `TZ` and any provider-declared variables — host environment
|
||||
variables, including secrets, are never forwarded into the agent.
|
||||
|
||||
**⚠ Behavior when enabled:** with lockdown on, agents have **no direct
|
||||
internet** — all traffic must go through OneCLI. Proxy-aware clients (npm, pnpm,
|
||||
pip, curl, node/bun with the proxy env) are unaffected. Any workflow that relies
|
||||
on a **non-proxy-aware** tool reaching the internet directly will fail by design.
|
||||
Lockdown is **off by default**; opt in with `NANOCLAW_EGRESS_LOCKDOWN=true`.
|
||||
|
||||
## Resource Limits
|
||||
## Privilege Comparison
|
||||
|
||||
Per-container CPU and memory caps are **opt-in and unset by default** — a runaway
|
||||
agent is not throttled unless the operator configures a limit:
|
||||
|
||||
| Env | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `CONTAINER_CPU_LIMIT` | *(empty — unbounded)* | Passed to `--cpus` when set (e.g. `2`). |
|
||||
| `CONTAINER_MEMORY_LIMIT` | *(empty — unbounded)* | Passed to `--memory` when set (e.g. `8g`). |
|
||||
|
||||
Only `--memory` is a container-level cap; whether it's a *hard* cap depends on
|
||||
the host having no swap (a deployment concern). On a swapless host a runaway is
|
||||
OOM-killed at the limit.
|
||||
| Capability | Main Group | Non-Main Group |
|
||||
|------------|------------|----------------|
|
||||
| Project root access | `/workspace/project` (ro) | None |
|
||||
| Store (SQLite DB) | `/workspace/project/store` (rw) | None |
|
||||
| Group folder | `/workspace/group` (rw) | `/workspace/group` (rw) |
|
||||
| Global memory | Implicit via project | `/workspace/global` (ro) |
|
||||
| Additional mounts | Configurable | Read-only unless allowed |
|
||||
| Network access | Unrestricted | Unrestricted |
|
||||
| MCP tools | All | All |
|
||||
|
||||
## Security Architecture Diagram
|
||||
|
||||
@@ -195,7 +149,7 @@ OOM-killed at the limit.
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ HOST PROCESS (TRUSTED) │
|
||||
│ • Message routing │
|
||||
│ • Role / access checks (user_roles, agent_group_members) │
|
||||
│ • IPC authorization │
|
||||
│ • Mount validation (external allowlist) │
|
||||
│ • Container lifecycle │
|
||||
│ • OneCLI Agent Vault (injects credentials, enforces policies) │
|
||||
|
||||
@@ -1,7 +1,5 @@
|
||||
# NanoClaw Specification
|
||||
|
||||
> **⚠️ Historical v1 spec.** This document describes the original NanoClaw v1 architecture — the single `store/messages.db`, the file-based IPC watcher, the `task-scheduler.ts` loop, the `MAX_CONCURRENT_CONTAINERS` cap, and the `groups/{channel}_{name}/` folder convention. **None of these exist in v2.** v2 replaced them with the two-DB session split (`inbound.db`/`outbound.db`), the entity model (users → messaging groups → agent groups → sessions), and the system-action delivery path. Kept for reference only. For the current architecture start at [architecture.md](architecture.md) and the root [CLAUDE.md](../CLAUDE.md); the v1→v2 diff is in [v1-to-v2-changes.md](v1-to-v2-changes.md).
|
||||
|
||||
A personal Claude assistant with multi-channel support, persistent memory per conversation, scheduled tasks, and container-isolated agent execution.
|
||||
|
||||
---
|
||||
|
||||
@@ -596,7 +596,7 @@ Schedule a one-shot or recurring task.
|
||||
}
|
||||
```
|
||||
|
||||
Implementation: the container can't write host-owned `inbound.db`, so this writes a `messages_out` row with `kind: 'system'` and `action: 'schedule_task'` (`container/agent-runner/src/mcp-tools/scheduling.ts`). During delivery the host's action handler (`src/modules/scheduling/actions.ts` → `insertTask()` in `src/modules/scheduling/db.ts`) inserts the `kind: 'task'` row into `inbound.db` with `process_after` and optionally `recurrence`. The host sweep picks it up when due.
|
||||
Implementation: write a `messages_in` row (to self) with `kind: 'task'`, `process_after`, and optionally `recurrence`. The host sweep picks it up when due.
|
||||
|
||||
#### list_tasks
|
||||
|
||||
@@ -609,7 +609,7 @@ List active scheduled/recurring tasks.
|
||||
}
|
||||
```
|
||||
|
||||
Implementation: a read, not a write — the container may read the read-only `inbound.db` mount directly. Returns one row per series (the live pending/paused occurrence): `SELECT series_id AS id, ... FROM messages_in WHERE kind = 'task' AND status IN ('pending','paused') GROUP BY series_id`. See `container/agent-runner/src/mcp-tools/scheduling.ts`.
|
||||
Implementation: query `messages_in WHERE recurrence IS NOT NULL AND status != 'failed'`.
|
||||
|
||||
#### cancel_task / pause_task / resume_task / update_task
|
||||
|
||||
@@ -625,7 +625,7 @@ Modify a scheduled task.
|
||||
// update_task: merge { prompt?, recurrence?, processAfter?, script? } into the live row
|
||||
```
|
||||
|
||||
Implementation: all four are sent as system actions (`messages_out`, `kind: 'system'`, `action: 'cancel_task' | 'pause_task' | 'resume_task' | 'update_task'`) — the container never writes `inbound.db`. The host's handlers in `src/modules/scheduling/actions.ts` apply the change against `inbound.db` via `src/modules/scheduling/db.ts`: cancel/pause/resume flip status on the live row(s); update_task reads current content, merges supplied fields, and writes back. All four match by `(id = ? OR series_id = ?) AND kind='task' AND status IN ('pending','paused')`, so they reach the live next occurrence of a recurring task even when the agent passes the original (now-completed) id.
|
||||
Implementation: cancel/pause/resume update the live row(s) directly. update_task is sent as a system action — the host reads current content, merges supplied fields, and writes back. All four match by `(id = ? OR series_id = ?) AND kind='task' AND status IN ('pending','paused')`, so they reach the live next occurrence of a recurring task even when the agent passes the original (now-completed) id.
|
||||
|
||||
#### register_agent_group
|
||||
|
||||
@@ -712,9 +712,9 @@ These are ephemeral to the container's lifetime. When the container is killed an
|
||||
|
||||
The agent-runner receives configuration via:
|
||||
|
||||
- **`container.json`:** The provider name, model, assistant name, MCP servers, and other NanoClaw config are read from `/workspace/agent/container.json` (materialized by the host from the `container_configs` table), not from environment variables. See `container/agent-runner/src/config.ts`.
|
||||
- **Environment variables:** provider-specific vars only (API keys, model overrides), `TZ`.
|
||||
- **Environment variables:** `AGENT_PROVIDER` (claude/codex/opencode), `NANOCLAW_ADMIN_USER_ID`, provider-specific vars (API keys, model overrides), `TZ`
|
||||
- **Fixed mount paths:** Session DB at `/workspace/session.db`. Agent group folder at `/workspace/agent/`. System prompt from `/workspace/agent/CLAUDE.md` and `/workspace/global/CLAUDE.md`.
|
||||
- **Optional startup config:** Some config may be passed as a JSON file at a fixed path (e.g., `/workspace/config.json`) for things like the session ID to resume, assistant name, and admin user ID. This avoids overloading environment variables.
|
||||
|
||||
The agent-runner reads config, creates the provider, and enters the poll loop. No stdin, no initial prompt — messages are already in the session DB.
|
||||
|
||||
@@ -731,7 +731,7 @@ function createProvider(name: ProviderName, config: ProviderConfig): AgentProvid
|
||||
}
|
||||
```
|
||||
|
||||
The provider name comes from the `provider` key in `/workspace/agent/container.json` (defaulting to `'claude'`), which the host materializes from the `container_configs` table — set it with `ncl groups config update --provider`. It is not an environment variable.
|
||||
The provider name comes from the container's environment (`AGENT_PROVIDER` env var), set by the host based on `agent_groups.agent_provider` or `sessions.agent_provider`.
|
||||
|
||||
`ProviderConfig` contains provider-specific settings (API keys, model overrides, etc.) passed via environment variables — not via the interface. Each provider reads what it needs from `env`.
|
||||
|
||||
|
||||
@@ -31,7 +31,7 @@ flowchart TB
|
||||
subgraph Session["Per-Session Container (Docker / Apple Container)"]
|
||||
direction TB
|
||||
PollLoop["Poll Loop<br/>(container/agent-runner)"]
|
||||
Provider["Agent providers<br/>(claude, opencode; todo: codex)"]
|
||||
Provider["Agent providers<br/>(claude, opencode, mock; todo: codex)"]
|
||||
MCP["MCP Tools<br/>send_message, send_file, edit_message,<br/>add_reaction, send_card, ask_user_question,<br/>schedule_task, create_agent,<br/>install_packages, add_mcp_server"]
|
||||
Skills["Container Skills<br/>(container/skills/)"]
|
||||
InDB[("inbound.db<br/>host writes<br/>even seq<br/>messages_in<br/>destinations<br/>processing_ack")]
|
||||
|
||||
@@ -1,7 +1,5 @@
|
||||
# NanoClaw Architecture (Draft)
|
||||
|
||||
> **Draft — design intent, not a line-by-line spec.** Some passages predate the current implementation and can drift from it. The root [CLAUDE.md](../CLAUDE.md) and the cited source files (`src/`, `container/agent-runner/src/`) are the source of truth; when this doc and the code disagree, trust the code. Notably, scheduling MCP tools do **not** write `inbound.db` directly — they emit `messages_out` system actions that the host applies (see [agent-runner-details.md](agent-runner-details.md) and `src/modules/scheduling/`).
|
||||
|
||||
## Core Idea
|
||||
|
||||
Each agent session has a mounted SQLite DB. The DB is the one and only IO mechanism between host and container. No IPC files, no stdin piping. Two tables: messages_in (host → agent-runner) and messages_out (agent-runner → host). Everything is a message.
|
||||
@@ -130,6 +128,7 @@ Non-Chat-SDK channels (WhatsApp via Baileys, Gmail, custom integrations) impleme
|
||||
The host is an orchestrator:
|
||||
1. **Spawn** — when wakeUpAgent is called and no container exists for the session
|
||||
2. **Idle kill** — when a container has no unprocessed messages for some timeout period
|
||||
3. **Limits** — MAX_CONCURRENT_CONTAINERS caps active containers
|
||||
|
||||
When a container spins up, the agent-runner immediately starts polling its session DB. Messages are already there waiting.
|
||||
|
||||
@@ -245,7 +244,7 @@ One-shot and recurring tasks use the same tables — no separate scheduler.
|
||||
|
||||
**Active container poll** (~1s) checks the same conditions but only for sessions with running containers.
|
||||
|
||||
**Agent-runner creates schedules** by emitting a `messages_out` row with `kind: 'system'` and an `action` (`schedule_task`, `cancel_task`, …) — it cannot write host-owned `inbound.db` directly. The host applies the action during delivery (`src/modules/scheduling/actions.ts`), inserting/updating the `kind: 'task'` `messages_in` row with `process_after` and optionally `recurrence`.
|
||||
**Agent-runner creates schedules** by writing messages_in (to itself) or messages_out (reminders/notifications) with `process_after` and optionally `recurrence`.
|
||||
|
||||
### messages_in content by kind
|
||||
|
||||
@@ -556,7 +555,7 @@ const DISCORD_TOKEN = process.env.DISCORD_BOT_TOKEN;
|
||||
const GMAIL_CREDS = process.env.GMAIL_CREDENTIALS_PATH;
|
||||
```
|
||||
|
||||
Shared config (DATA_DIR, TIMEZONE) stays in `config.ts`. Channel/skill-specific config stays in the module that uses it.
|
||||
Shared config (DATA_DIR, TIMEZONE, MAX_CONCURRENT_CONTAINERS) stays in `config.ts`. Channel/skill-specific config stays in the module that uses it.
|
||||
|
||||
### Code Style
|
||||
|
||||
@@ -830,7 +829,7 @@ Mixed batches (e.g., a chat message + a system result both pending) are combined
|
||||
|
||||
### MCP Tools
|
||||
|
||||
MCP tools write to the container's own `outbound.db`. Anything that needs a change in host-owned `inbound.db` (schedule/cancel/pause/resume/update a task, register a group) is emitted as a `kind: 'system'` `messages_out` action that the host applies during delivery — the container never writes `inbound.db`.
|
||||
MCP tools write directly to the session DB.
|
||||
|
||||
**Core tools:**
|
||||
|
||||
@@ -838,9 +837,9 @@ MCP tools write to the container's own `outbound.db`. Anything that needs a chan
|
||||
|------|-------------|
|
||||
| `send_message` | Write `messages_out` row, `kind: 'chat'` |
|
||||
| `send_file` | Move file to `outbox/{msg_id}/`, write `messages_out` with filenames |
|
||||
| `schedule_task` | Write `messages_out`, `kind: 'system'`, `action: 'schedule_task'`; host inserts the `kind: 'task'` `messages_in` row with `process_after` + optional `recurrence` |
|
||||
| `list_tasks` | Read `messages_in` (read-only mount) — one row per series: `kind = 'task' AND status IN ('pending','paused') GROUP BY series_id` |
|
||||
| `pause_task` / `resume_task` / `cancel_task` | Write `messages_out`, `kind: 'system'`, matching `action`; host updates the live `messages_in` row(s) |
|
||||
| `schedule_task` | Write `messages_in` row (to self) with `process_after` + `recurrence`. Or `messages_out` with `deliver_after` for outbound reminders. |
|
||||
| `list_tasks` | Query `messages_in WHERE recurrence IS NOT NULL` |
|
||||
| `pause_task` / `resume_task` / `cancel_task` | Modify `messages_in` rows (update status, clear/set recurrence) |
|
||||
| `register_agent_group` | Write `messages_out`, `kind: 'system'`, `action: 'register_agent_group'` |
|
||||
|
||||
**New tools:**
|
||||
|
||||
+2
-2
@@ -17,7 +17,7 @@ data/v2-sessions/<agent_group_id>/<session_id>/
|
||||
outbox/<message_id>/ ← attachments the agent produced
|
||||
```
|
||||
|
||||
One session = one folder = one pair of DBs. The `agent_group_id` parent directory also holds per-group state (`.claude-shared/`) that is shared across every session of that agent group. (The agent-runner source is not copied per group — it's a shared read-only mount from `container/agent-runner/src` into every container; see `src/container-runner.ts`.)
|
||||
One session = one folder = one pair of DBs. The `agent_group_id` parent directory also holds per-group state (`.claude-shared/`, `agent-runner-src/`) that is shared across every session of that agent group.
|
||||
|
||||
Path helpers in `src/session-manager.ts`: `sessionDir()`, `inboundDbPath()`, `outboundDbPath()`, `heartbeatPath()`.
|
||||
|
||||
@@ -55,7 +55,7 @@ CREATE INDEX idx_messages_in_series ON messages_in(series_id);
|
||||
|
||||
Content shapes: see [api-details.md §Session DB Schema Details](api-details.md#session-db-schema-details).
|
||||
|
||||
**Writers (host):** `insertMessage()` (and `nextEvenSeq()`) in `src/db/session-db.ts`; `insertTask()` and `insertRecurrence()` in `src/modules/scheduling/db.ts`. Each calls `nextEvenSeq()`.
|
||||
**Writers (host):** `insertMessage()`, `insertTask()`, `insertRecurrence()` — all in `src/db/session-db.ts`. Each calls `nextEvenSeq()`.
|
||||
**Reader (container):** `container/agent-runner/src/db/messages-in.ts` — polls `status='pending' AND (process_after IS NULL OR process_after <= now)`.
|
||||
|
||||
### 2.2 `delivered`
|
||||
|
||||
@@ -35,6 +35,7 @@ data/
|
||||
v2-sessions/
|
||||
<agent_group_id>/
|
||||
.claude-shared/ ← shared Claude state for the agent group
|
||||
agent-runner-src/ ← per-group agent-runner overlay
|
||||
<session_id>/
|
||||
inbound.db ← host writes, container reads
|
||||
outbound.db ← container writes, host reads
|
||||
|
||||
@@ -0,0 +1,359 @@
|
||||
# Running NanoClaw in Docker Sandboxes (Manual Setup)
|
||||
|
||||
This guide walks through setting up NanoClaw inside a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) from scratch — no install script, no pre-built fork. You'll clone the upstream repo, apply the necessary patches, and have agents running in full hypervisor-level isolation.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Host (macOS / Windows WSL)
|
||||
└── Docker Sandbox (micro VM with isolated kernel)
|
||||
├── NanoClaw process (Node.js)
|
||||
│ ├── Channel adapters (WhatsApp, Telegram, etc.)
|
||||
│ └── Container spawner → nested Docker daemon
|
||||
└── Docker-in-Docker
|
||||
└── nanoclaw-agent containers
|
||||
└── Claude Agent SDK
|
||||
```
|
||||
|
||||
Each agent runs in its own container, inside a micro VM that is fully isolated from your host. Two layers of isolation: per-agent containers + the VM boundary.
|
||||
|
||||
The sandbox provides a MITM proxy at `host.docker.internal:3128` that handles network access and injects your Anthropic API key automatically.
|
||||
|
||||
> **Note:** This guide is based on a validated setup running on macOS (Apple Silicon) with WhatsApp. Other channels (Telegram, Slack, etc.) and environments (Windows WSL) may require additional proxy patches for their specific HTTP/WebSocket clients. The core patches (container runner, credential proxy, Dockerfile) apply universally — channel-specific proxy configuration varies.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Docker Desktop v4.40+** with Sandbox support
|
||||
- **Anthropic API key** (the sandbox proxy manages injection)
|
||||
- For **Telegram**: a bot token from [@BotFather](https://t.me/BotFather) and your chat ID
|
||||
- For **WhatsApp**: a phone with WhatsApp installed
|
||||
|
||||
Verify sandbox support:
|
||||
```bash
|
||||
docker sandbox version
|
||||
```
|
||||
|
||||
## Step 1: Create the Sandbox
|
||||
|
||||
On your host machine:
|
||||
|
||||
```bash
|
||||
# Create a workspace directory
|
||||
mkdir -p ~/nanoclaw-workspace
|
||||
|
||||
# Create a shell sandbox with the workspace mounted
|
||||
docker sandbox create shell ~/nanoclaw-workspace
|
||||
```
|
||||
|
||||
If you're using WhatsApp, configure proxy bypass so WhatsApp's Noise protocol isn't MITM-inspected:
|
||||
|
||||
```bash
|
||||
docker sandbox network proxy shell-nanoclaw-workspace \
|
||||
--bypass-host web.whatsapp.com \
|
||||
--bypass-host "*.whatsapp.com" \
|
||||
--bypass-host "*.whatsapp.net"
|
||||
```
|
||||
|
||||
Telegram does not need proxy bypass.
|
||||
|
||||
Enter the sandbox:
|
||||
```bash
|
||||
docker sandbox run shell-nanoclaw-workspace
|
||||
```
|
||||
|
||||
## Step 2: Install Prerequisites
|
||||
|
||||
Inside the sandbox:
|
||||
|
||||
```bash
|
||||
sudo apt-get update && sudo apt-get install -y build-essential python3
|
||||
npm config set strict-ssl false
|
||||
```
|
||||
|
||||
## Step 3: Clone and Install NanoClaw
|
||||
|
||||
NanoClaw must live inside the workspace directory — Docker-in-Docker can only bind-mount from the shared workspace path.
|
||||
|
||||
```bash
|
||||
# Clone to home first (virtiofs can corrupt git pack files during clone)
|
||||
cd ~
|
||||
git clone https://github.com/nanocoai/nanoclaw.git
|
||||
|
||||
# Replace with YOUR workspace path (the host path you passed to `docker sandbox create`)
|
||||
WORKSPACE=/Users/you/nanoclaw-workspace
|
||||
|
||||
# Move into workspace so DinD mounts work
|
||||
mv nanoclaw "$WORKSPACE/nanoclaw"
|
||||
cd "$WORKSPACE/nanoclaw"
|
||||
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
pnpm install https-proxy-agent
|
||||
```
|
||||
|
||||
## Step 4: Apply Proxy and Sandbox Patches
|
||||
|
||||
NanoClaw needs several patches to work inside a Docker Sandbox. These handle proxy routing, CA certificates, and Docker-in-Docker mount restrictions.
|
||||
|
||||
### 4a. Dockerfile — proxy args for container image build
|
||||
|
||||
`pnpm install` inside `docker build` fails with `SELF_SIGNED_CERT_IN_CHAIN` because the sandbox's MITM proxy presents its own certificate. Add proxy build args to `container/Dockerfile`:
|
||||
|
||||
Add these lines after the `FROM` line:
|
||||
|
||||
```dockerfile
|
||||
# Accept proxy build args
|
||||
ARG http_proxy
|
||||
ARG https_proxy
|
||||
ARG no_proxy
|
||||
ARG NODE_EXTRA_CA_CERTS
|
||||
ARG npm_config_strict_ssl=true
|
||||
RUN npm config set strict-ssl ${npm_config_strict_ssl}
|
||||
```
|
||||
|
||||
And after the `RUN pnpm install` line:
|
||||
|
||||
```dockerfile
|
||||
RUN npm config set strict-ssl true
|
||||
```
|
||||
|
||||
### 4b. Build script — forward proxy args
|
||||
|
||||
Patch `container/build.sh` to pass proxy env vars to `docker build`:
|
||||
|
||||
Add these `--build-arg` flags to the `docker build` command:
|
||||
|
||||
```bash
|
||||
--build-arg http_proxy="${http_proxy:-$HTTP_PROXY}" \
|
||||
--build-arg https_proxy="${https_proxy:-$HTTPS_PROXY}" \
|
||||
--build-arg no_proxy="${no_proxy:-$NO_PROXY}" \
|
||||
--build-arg npm_config_strict_ssl=false \
|
||||
```
|
||||
|
||||
### 4c. Container runner — proxy forwarding, CA cert mount, /dev/null fix
|
||||
|
||||
Three changes to `src/container-runner.ts`:
|
||||
|
||||
**Replace `/dev/null` shadow mount.** The sandbox rejects `/dev/null` bind mounts. Find where `.env` is shadow-mounted to `/dev/null` and replace it with an empty file:
|
||||
|
||||
```typescript
|
||||
// Create an empty file to shadow .env (Docker Sandbox rejects /dev/null mounts)
|
||||
const emptyEnvPath = path.join(DATA_DIR, 'empty-env');
|
||||
if (!fs.existsSync(emptyEnvPath)) fs.writeFileSync(emptyEnvPath, '');
|
||||
// Use emptyEnvPath instead of '/dev/null' in the mount
|
||||
```
|
||||
|
||||
**Forward proxy env vars** to spawned agent containers. Add `-e` flags for `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and their lowercase variants.
|
||||
|
||||
**Mount CA certificate.** If `NODE_EXTRA_CA_CERTS` or `SSL_CERT_FILE` is set, copy the cert into the project directory and mount it into agent containers:
|
||||
|
||||
```typescript
|
||||
const caCertSrc = process.env.NODE_EXTRA_CA_CERTS || process.env.SSL_CERT_FILE;
|
||||
if (caCertSrc) {
|
||||
const certDir = path.join(DATA_DIR, 'ca-cert');
|
||||
fs.mkdirSync(certDir, { recursive: true });
|
||||
fs.copyFileSync(caCertSrc, path.join(certDir, 'proxy-ca.crt'));
|
||||
// Mount: certDir -> /workspace/ca-cert (read-only)
|
||||
// Set NODE_EXTRA_CA_CERTS=/workspace/ca-cert/proxy-ca.crt in the container
|
||||
}
|
||||
```
|
||||
|
||||
### 4d. Container runtime — prevent self-termination
|
||||
|
||||
In `src/container-runtime.ts`, the `cleanupOrphans()` function matches containers by the `nanoclaw-` prefix. Inside a sandbox, the sandbox container itself may match (e.g., `nanoclaw-docker-sandbox`). Filter out the current hostname:
|
||||
|
||||
```typescript
|
||||
// In cleanupOrphans(), filter out os.hostname() from the list of containers to stop
|
||||
```
|
||||
|
||||
### 4e. Credential proxy — route through MITM proxy
|
||||
|
||||
In `src/credential-proxy.ts`, upstream API requests need to go through the sandbox proxy. Add `HttpsProxyAgent` to outbound requests:
|
||||
|
||||
```typescript
|
||||
import { HttpsProxyAgent } from 'https-proxy-agent';
|
||||
|
||||
const proxyUrl = process.env.HTTPS_PROXY || process.env.https_proxy;
|
||||
const upstreamAgent = proxyUrl ? new HttpsProxyAgent(proxyUrl) : undefined;
|
||||
// Pass upstreamAgent to https.request() options
|
||||
```
|
||||
|
||||
### 4f. Setup script — proxy build args
|
||||
|
||||
Patch `setup/container.ts` to pass the same proxy `--build-arg` flags as `build.sh` (Step 4b).
|
||||
|
||||
## Step 5: Build
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
bash container/build.sh
|
||||
```
|
||||
|
||||
## Step 6: Add a Channel
|
||||
|
||||
### Telegram
|
||||
|
||||
```bash
|
||||
# Apply the Telegram skill
|
||||
pnpm exec tsx scripts/apply-skill.ts .claude/skills/add-telegram
|
||||
|
||||
# Rebuild after applying the skill
|
||||
pnpm run build
|
||||
|
||||
# Configure .env
|
||||
cat > .env << EOF
|
||||
TELEGRAM_BOT_TOKEN=<your-token-from-botfather>
|
||||
ASSISTANT_NAME=nanoclaw
|
||||
ANTHROPIC_API_KEY=proxy-managed
|
||||
EOF
|
||||
mkdir -p data/env && cp .env data/env/env
|
||||
|
||||
# Register your chat
|
||||
pnpm exec tsx setup/index.ts --step register \
|
||||
--jid "tg:<your-chat-id>" \
|
||||
--name "My Chat" \
|
||||
--trigger "@nanoclaw" \
|
||||
--folder "telegram_main" \
|
||||
--channel telegram \
|
||||
--assistant-name "nanoclaw" \
|
||||
--is-main \
|
||||
--no-trigger-required
|
||||
```
|
||||
|
||||
**To find your chat ID:** Send any message to your bot, then:
|
||||
```bash
|
||||
curl -s --proxy $HTTPS_PROXY "https://api.telegram.org/bot<TOKEN>/getUpdates" | python3 -m json.tool
|
||||
```
|
||||
|
||||
**Telegram in groups:** Disable Group Privacy in @BotFather (`/mybots` > Bot Settings > Group Privacy > Turn off), then remove and re-add the bot.
|
||||
|
||||
**Important:** If the Telegram skill creates `src/channels/telegram.ts`, you'll need to patch it for proxy support. Add an `HttpsProxyAgent` and pass it to grammy's `Bot` constructor via `baseFetchConfig.agent`. Then rebuild.
|
||||
|
||||
### WhatsApp
|
||||
|
||||
Make sure you configured proxy bypass in [Step 1](#step-1-create-the-sandbox) first.
|
||||
|
||||
```bash
|
||||
# Apply the WhatsApp skill
|
||||
pnpm exec tsx scripts/apply-skill.ts .claude/skills/add-whatsapp
|
||||
|
||||
# Rebuild
|
||||
pnpm run build
|
||||
|
||||
# Configure .env
|
||||
cat > .env << EOF
|
||||
ASSISTANT_NAME=nanoclaw
|
||||
ANTHROPIC_API_KEY=proxy-managed
|
||||
EOF
|
||||
mkdir -p data/env && cp .env data/env/env
|
||||
|
||||
# Authenticate (choose one):
|
||||
|
||||
# QR code — scan with WhatsApp camera:
|
||||
pnpm exec tsx src/whatsapp-auth.ts
|
||||
|
||||
# OR pairing code — enter code in WhatsApp > Linked Devices > Link with phone number:
|
||||
pnpm exec tsx src/whatsapp-auth.ts --pairing-code --phone <phone-number-no-plus>
|
||||
|
||||
# Register your chat (JID = your phone number + @s.whatsapp.net)
|
||||
pnpm exec tsx setup/index.ts --step register \
|
||||
--jid "<phone>@s.whatsapp.net" \
|
||||
--name "My Chat" \
|
||||
--trigger "@nanoclaw" \
|
||||
--folder "whatsapp_main" \
|
||||
--channel whatsapp \
|
||||
--assistant-name "nanoclaw" \
|
||||
--is-main \
|
||||
--no-trigger-required
|
||||
```
|
||||
|
||||
**Important:** The WhatsApp skill files (`src/channels/whatsapp.ts` and `src/whatsapp-auth.ts`) also need proxy patches — add `HttpsProxyAgent` for WebSocket connections and a proxy-aware version fetch. Then rebuild.
|
||||
|
||||
### Both Channels
|
||||
|
||||
Apply both skills, patch both for proxy support, combine the `.env` variables, and register each chat separately.
|
||||
|
||||
## Step 7: Run
|
||||
|
||||
```bash
|
||||
pnpm start
|
||||
```
|
||||
|
||||
You don't need to set `ANTHROPIC_API_KEY` manually. The sandbox proxy intercepts requests and replaces `proxy-managed` with your real key automatically.
|
||||
|
||||
## Networking Details
|
||||
|
||||
### How the proxy works
|
||||
|
||||
All traffic from the sandbox routes through the host proxy at `host.docker.internal:3128`:
|
||||
|
||||
```
|
||||
Agent container → DinD bridge → Sandbox VM → host.docker.internal:3128 → Host proxy → api.anthropic.com
|
||||
```
|
||||
|
||||
**"Bypass" does not mean traffic skips the proxy.** It means the proxy passes traffic through without MITM inspection. Node.js doesn't automatically use `HTTP_PROXY` env vars — you need explicit `HttpsProxyAgent` configuration in every HTTP/WebSocket client.
|
||||
|
||||
### Shared paths for DinD mounts
|
||||
|
||||
Only the workspace directory is available for Docker-in-Docker bind mounts. Paths outside the workspace fail with "path not shared":
|
||||
- `/dev/null` → replace with an empty file in the project dir
|
||||
- `/usr/local/share/ca-certificates/` → copy cert to project dir
|
||||
- `/home/agent/` → clone to workspace instead
|
||||
|
||||
### Git clone and virtiofs
|
||||
|
||||
The workspace is mounted via virtiofs. Git's pack file handling can corrupt over virtiofs during clone. Workaround: clone to `/home/agent` first, then `mv` into the workspace.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### pnpm install fails with SELF_SIGNED_CERT_IN_CHAIN
|
||||
```bash
|
||||
npm config set strict-ssl false
|
||||
```
|
||||
|
||||
### Container build fails with proxy errors
|
||||
```bash
|
||||
docker build \
|
||||
--build-arg http_proxy=$http_proxy \
|
||||
--build-arg https_proxy=$https_proxy \
|
||||
-t nanoclaw-agent:latest container/
|
||||
```
|
||||
|
||||
### Agent containers fail with "path not shared"
|
||||
All bind-mounted paths must be under the workspace directory. Check:
|
||||
- Is NanoClaw cloned into the workspace? (not `/home/agent/`)
|
||||
- Is the CA cert copied to the project root?
|
||||
- Has the empty `.env` shadow file been created?
|
||||
|
||||
### Agent containers can't reach Anthropic API
|
||||
Verify proxy env vars are forwarded to agent containers. Check container logs for `HTTP_PROXY=http://host.docker.internal:3128`.
|
||||
|
||||
### WhatsApp error 405
|
||||
The version fetch is returning a stale version. Make sure the proxy-aware `fetchWaVersionViaProxy` patch is applied — it fetches `sw.js` through `HttpsProxyAgent` and parses `client_revision`.
|
||||
|
||||
### WhatsApp "Connection failed" immediately
|
||||
Proxy bypass not configured. From the **host**, run:
|
||||
```bash
|
||||
docker sandbox network proxy <sandbox-name> \
|
||||
--bypass-host web.whatsapp.com \
|
||||
--bypass-host "*.whatsapp.com" \
|
||||
--bypass-host "*.whatsapp.net"
|
||||
```
|
||||
|
||||
### Telegram bot doesn't receive messages
|
||||
1. Check the grammy proxy patch is applied (look for `HttpsProxyAgent` in `src/channels/telegram.ts`)
|
||||
2. Check Group Privacy is disabled in @BotFather if using in groups
|
||||
|
||||
### Git clone fails with "inflate: data stream error"
|
||||
Clone to a non-workspace path first, then move:
|
||||
```bash
|
||||
cd ~ && git clone https://github.com/nanocoai/nanoclaw.git && mv nanoclaw /path/to/workspace/nanoclaw
|
||||
```
|
||||
|
||||
### WhatsApp QR code doesn't display
|
||||
Run the auth command interactively inside the sandbox (not piped through `docker sandbox exec`):
|
||||
```bash
|
||||
docker sandbox run shell-nanoclaw-workspace
|
||||
# Then inside:
|
||||
pnpm exec tsx src/whatsapp-auth.ts
|
||||
```
|
||||
+1
-1
@@ -193,7 +193,7 @@ leaking the token to disk outweighs the debugging value.
|
||||
| `setup/logs.ts` | The logging primitives (`logStep`, `logUserInput`, `logComplete`, `stepRawLog`, `initSetupLog`). Single source of truth for level 2/3 formatting and file paths. |
|
||||
| `setup/<step>.ts` | Individual step implementations. Must emit one terminal status block; must not write directly to the terminal. |
|
||||
| `setup/register-claude-token.sh` | The Anthropic exception. Inherits stdio, prints its own UI, returns a status to the driver. |
|
||||
| `setup/channels/telegram.ts` | Telegram channel flow. Installs the adapter in-process by applying the `/add-telegram` skill (directive engine; SKILL.md is the single source of truth), feeding the collected bot token to the skill's `bot_token` prompt var. |
|
||||
| `setup/add-telegram.sh` | Non-interactive adapter installer. Reads `TELEGRAM_BOT_TOKEN` from env; never prompts. User-facing bits live in `auto.ts`. |
|
||||
| `setup/pair-telegram.ts` | Emits `PAIR_TELEGRAM_CODE` / `PAIR_TELEGRAM_ATTEMPT` / `PAIR_TELEGRAM` status blocks. Never prints UI. The driver renders it via clack notes. |
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
@@ -1,646 +0,0 @@
|
||||
# The skill-engine seam: declare/emit vs. acquire/present
|
||||
|
||||
Status: SPEC — approved boundary decision, pre-implementation, review findings folded. Branch: `feat/structured-skill-format` (pre-merge; clean break, no compat shims).
|
||||
|
||||
## 1. The boundary rule
|
||||
|
||||
> **The engine may DECLARE needs and EMIT events; it may never ACQUIRE input or PRESENT anything.**
|
||||
|
||||
`scripts/skill-apply.ts` accumulated interactive-setup-wizard concerns in its core
|
||||
contract: a `Prompter` with `tell`/`confirm`/`open`, authored presentation attrs
|
||||
(`gate`, `open:`, `min:`, `error:`, `label:`, `on-fail:`), and a `StepReporter`
|
||||
shaped around a clack spinner. That couples the deterministic applier to one
|
||||
consumer (the setup wizard) when there are three:
|
||||
|
||||
1. **wizard** — interactive setup (`setup/lib/skill-driver.ts` + `setup/channels/run-channel-skill.ts`, clack UI)
|
||||
2. **agent-relay** — a coding agent driving a skill conversationally over chat
|
||||
3. **pipeline** — CI/CD & customer deployments: inputs from env, no human, `operatorMessages` consumed as a "manual steps" report
|
||||
|
||||
Declaration & semantics (what a value must look like, what a step is, what the
|
||||
human must be told) = **core**. Acquisition & presentation (how the value is
|
||||
collected, how the message is rendered, when to pause) = **consumer**. The
|
||||
rule binds only the core: a driver may define whatever interaction types it
|
||||
wants on its side of the seam.
|
||||
|
||||
### Invariants (non-negotiable)
|
||||
|
||||
- **Prose-primary / oblivious-to-auto-apply**: with `nc:` fences stripped, every SKILL.md reads as a normal skill. Never narrate the engine.
|
||||
- **Degrade-to-agent**: anything the engine can't do bounces to an `agentTask` — never a crash, never a silent drop.
|
||||
- **Option A split untouched**: no change to any resolve/wire logic; every `platform_id` / `user_id` byte produced by the **production code paths** is identical. The Option-A test (`setup/channels/run-channel-skill.test.ts:24-70`) keeps its assertion structure, but its fixture credentials MUST be updated to valid-shaped values in the same step that lands validate-at-bind (§4): today's `signing_secret: 's'` fails add-slack's `^[a-fA-F0-9]{16,}$` and `owner_handle: 'U1'` fails `^U[A-Z0-9]{8,}$` (both bypass validation only because inputs bypass it today). The `userId` assertion updates consistently (e.g. `owner_handle: 'U12345678'` ⇒ `'slack:U12345678'`). Byte-parity is a claim about production code, not about test-fixture literals shaped to exploit the removed bypass.
|
||||
- **Coverage parity**: suite is 680 passed | 1 skipped today. Seam-touching tests are reworked *at the seam*; gate/open attr tests become driver-policy tests proving the parity claims in §5.
|
||||
- **Never stage/commit** the pre-existing unrelated local changes: `package.json`, `pnpm-lock.yaml`, `src/channels/index.ts`, `src/providers/claude.ts`, `src/providers/index.ts` — nor untracked files this work did not create.
|
||||
|
||||
## 2. The new core interface
|
||||
|
||||
The entire interaction surface of the engine, after the refactor
|
||||
(`scripts/skill-apply.ts`):
|
||||
|
||||
```ts
|
||||
// What an nc:prompt declares about the value it needs. Passed to resolveInput
|
||||
// so a consumer can run its OWN re-ask loop (clack validate, a chat exchange).
|
||||
export interface InputMeta {
|
||||
question: string; // the prompt body (verbatim)
|
||||
secret: boolean; // consumer must mask
|
||||
validate?: string; // regex source (nc:prompt validate:<re>)
|
||||
flags?: string; // regex flags (nc:prompt flags:<f>)
|
||||
normalize?: 'trim' | 'rstrip-slash' | 'lower'; // applied by the ENGINE at bind
|
||||
}
|
||||
|
||||
// Everything the engine emits. `onEvent` is AWAITED before the engine
|
||||
// proceeds — that ordering guarantee is what lets a consumer implement
|
||||
// gating (hold the operator event until the human confirms readiness).
|
||||
export type ApplyEvent =
|
||||
| { type: 'step-start'; kind: string; line: number; label: string | null }
|
||||
| { type: 'step-end'; kind: string; line: number; label: string | null;
|
||||
ok: boolean; durationMs: number; error?: string }
|
||||
| { type: 'operator'; line: number; text: string };
|
||||
// text = the rendered, {{var}}-substituted block body;
|
||||
// line = the directive's opening-fence line (keys driver policy maps)
|
||||
|
||||
export interface ApplyOptions {
|
||||
// Pre-supplied answers (var → value). Checked FIRST. Unchanged.
|
||||
inputs?: Record<string, string>;
|
||||
// Replaces Prompter.ask. undefined ⇒ defer (unchanged semantics).
|
||||
resolveInput?: (name: string, meta: InputMeta) => Promise<string | undefined>;
|
||||
// Unchanged.
|
||||
exec?: (cmd: string) => string | void | Promise<string | void>;
|
||||
// Unchanged.
|
||||
execStream?: (cmd: string) => Promise<StepOutcome>;
|
||||
// Unchanged.
|
||||
skipEffects?: string[];
|
||||
// Unchanged.
|
||||
resolveRemote?: (branch: string) => string;
|
||||
// Replaces BOTH StepReporter and Prompter.tell. Awaited before proceeding.
|
||||
onEvent?: (e: ApplyEvent) => void | Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
**Gone from the core entirely**: `Prompter` (ask/tell/confirm/open), `PromptOpts`,
|
||||
`StepReporter`, `ApplyOptions.prompter`, `ApplyOptions.reporter`.
|
||||
|
||||
**`ApplyResult` — unchanged fields**: `applied`, `skipped`, `agentTasks`,
|
||||
`operatorMessages` (still collected in the result — the pipeline reads them
|
||||
there; the `operator` *event* is for live rendering), `vars`, `journal`,
|
||||
`referenceProse`. `fullyApplied()` and `firstFailureHint()` unchanged.
|
||||
Two adjustments:
|
||||
|
||||
- `deferred: string[]` — same field, one new entry form: an input rejected by
|
||||
validate-at-bind is recorded as `` `<var>: invalid value (does not match validate:<re>)` ``
|
||||
(see §4). Missing-input entries stay the bare var name; unresolved-`{{var}}`
|
||||
entries stay the thrown message (`skill-apply.ts:841` today).
|
||||
- `AgentTask.hint` is **dropped** (it existed only for `on-fail:`; with that attr
|
||||
gone, hint ≡ prose). `firstFailureHint` reads `prose` directly.
|
||||
|
||||
**Derived metadata stays core** (exposure, not authored presentation):
|
||||
`stepLabel` (heading-derived only — the `label:` attr override at
|
||||
`skill-apply.ts:458` is removed), `AgentTask` prose/`reason` (proseFor-derived),
|
||||
`firstFailureHint`, `referenceProse`, `operatorMessages`.
|
||||
|
||||
**`stepLabel` null semantics, re-documented.** Today's doc comment
|
||||
(`skill-apply.ts:73-79`, `:442-446`) frames `label: null` as "the driver should
|
||||
NOT spin on this" — spinner advice, i.e. presentation smuggled into the core.
|
||||
The contract wording changes (no payload change): `label: null` means *instant/
|
||||
cheap, or the step renders its own live operator-facing output* (`effect:step`'s
|
||||
QR card / pairing code). That is step-cost/interactivity **declaration**; the
|
||||
event carries `kind` + `line`, so a consumer wanting a different render policy
|
||||
can derive its own.
|
||||
|
||||
**Event ordering contract** (normative):
|
||||
|
||||
1. Per directive, `step-start` fires immediately before the mutation, `step-end`
|
||||
immediately after (or on the failure path) — always balanced. The payload is
|
||||
today's `StepReporter` payload (`skill-apply.ts:80-83` — it already includes
|
||||
`line`) unchanged, plus only the discriminating `type` field.
|
||||
2. For an `nc:operator`, the engine substitutes `{{vars}}`, pushes to
|
||||
`res.operatorMessages`, then `await onEvent({type:'operator', …})` before
|
||||
evaluating the next directive. An unresolved `{{var}}` in the body defers the
|
||||
whole block before any event fires (today's behavior, `skill-apply.ts:787`).
|
||||
**Once the run is `blocked`** (an earlier bounce), operator directives are
|
||||
skipped instead — no event, no `operatorMessages` entry, recorded in
|
||||
`skipped`. Walking the human through steps whose side effects the run has
|
||||
already gated ("a pairing code is about to appear" → nothing appears) is
|
||||
actively misleading, and a failed run's manual-steps report must not include
|
||||
steps predicated on the failure.
|
||||
3. Every `onEvent` call is awaited; a rejection from `onEvent` is treated like
|
||||
any other throw at that directive (bounce, not crash). This applies to
|
||||
operator events too: a consumer that throws from `onEvent` **accepts the
|
||||
bounce consequence**, including the `blocked` latch cascading over later
|
||||
side effects. The engine itself never defers/bounces an operator block
|
||||
(open question 7); consequently a well-behaved driver's handler must never
|
||||
throw for a *declined* confirm — decline semantics are defined in §5.1.
|
||||
|
||||
## 3. Migration table
|
||||
|
||||
Every existing hook / attr / caller → destination. "core seam" = survives in
|
||||
`ApplyOptions`/`ApplyResult`; "driver policy" = reimplemented from document
|
||||
structure (shared policy module + `setup/lib/skill-driver.ts`, §5); "deleted" =
|
||||
removed with no replacement syntax.
|
||||
|
||||
### Engine hooks
|
||||
|
||||
| Today | Where (file:line) | Destination |
|
||||
|---|---|---|
|
||||
| `ApplyOptions.inputs` | `scripts/skill-apply.ts:263` | core seam (unchanged, but validated — §4) |
|
||||
| `Prompter.ask(name, question, secret, validate, opts)` | `scripts/skill-apply.ts:50`, called at `:774` | core seam → `resolveInput(name, meta)` |
|
||||
| `Prompter.tell(text)` | `scripts/skill-apply.ts:54`, called at `:793` | core seam → `onEvent` `operator` event |
|
||||
| `Prompter.confirm(msg)` | `scripts/skill-apply.ts:58`, called at `:802` (gate; result discarded — decline proceeds today) | driver policy (natural-barrier gating, §5.1) + driver-owned reuse offer — both via the new `RunSkillOptions.confirm` seam (§5.0) |
|
||||
| `Prompter.open(url)` | `scripts/skill-apply.ts:63`, called at `:796` | driver policy (URL offer, §5.2) via the new `RunSkillOptions.openUrl` seam (§5.0) |
|
||||
| `StepReporter.stepStart/stepEnd` | `scripts/skill-apply.ts:80-83`, fired at `:827,:830,:839` | core seam → `onEvent` `step-start`/`step-end` events (payload + balance guarantee identical; only `type` added) |
|
||||
| `ApplyOptions.prompter` | `scripts/skill-apply.ts:266` | deleted (split into `resolveInput` + `onEvent`) |
|
||||
| `ApplyOptions.reporter` | `scripts/skill-apply.ts:287` | deleted (folded into `onEvent`) |
|
||||
| `ApplyOptions.exec` / `execStream` | `scripts/skill-apply.ts:269,:275` | core seam (unchanged) |
|
||||
| `ApplyOptions.skipEffects` | `scripts/skill-apply.ts:279` | core seam (unchanged) |
|
||||
| `ApplyOptions.resolveRemote` | `scripts/skill-apply.ts:283` | core seam (unchanged) |
|
||||
| `PromptOpts` (flags/min/error/normalize) | `scripts/skill-apply.ts:37-42`, built at `:499` (`promptOptsOf`) | type deleted; `flags`/`normalize` move into `InputMeta`; `min`/`error` deleted (§ grammar) |
|
||||
| `normalizeValue` at bind | `scripts/skill-apply.ts:483`, applied `:779` | core seam (unchanged; now paired with validate-at-bind, §4) |
|
||||
| `stepLabel` | `scripts/skill-apply.ts:457-474` | core seam, minus the `label:` attr branch (`:458`); null semantics re-documented (§2) |
|
||||
| `failHint` / `AgentTask.hint` | `scripts/skill-apply.ts:419-430`, `:236`, `:749` | deleted (`on-fail:` gone ⇒ hint ≡ prose; `firstFailureHint` at `:308` reads `prose`) |
|
||||
| run-health gate (`blocked` latch) | `scripts/skill-apply.ts:744-750,:816` | core seam (unchanged) |
|
||||
| `when:` guard | `scripts/skill-apply.ts:521-525,:762` | core seam (unchanged) |
|
||||
| `effect:check` / `effect:step` + terminal-block capture | `scripts/skill-apply.ts:646-667` | core seam (unchanged) |
|
||||
| multi-field JSON capture + validate-on-capture | `scripts/skill-apply.ts:551-572` | core seam (unchanged) |
|
||||
| journal / `removeSkill` | `scripts/skill-apply.ts:851-870` | core seam (unchanged) |
|
||||
| `referenceProse` / `operatorMessages` / `vars` in result | `scripts/skill-apply.ts:239-257` | core seam (unchanged) |
|
||||
|
||||
### Authored grammar (`scripts/skill-directives.ts`)
|
||||
|
||||
| Attr / syntax | Where | Destination |
|
||||
|---|---|---|
|
||||
| `nc:operator open:<url>` | grammar doc `:61-73`; lint `:277`, `:287-291`; engine `:791,:796` | **deleted**. Driver URL-offer policy scans the rendered text (§5.2). URLs must live in the prose. |
|
||||
| `nc:operator gate` | grammar doc `:68-71`; engine `:802` | **deleted**. Driver natural-barrier policy (§5.1). |
|
||||
| `nc:prompt min:<n>` | grammar doc `:53-54`; lint `:264-266`; driver enforcement `setup/lib/skill-driver.ts:46` | **deleted**. Authors re-encode as regex, e.g. `min:20` → `validate:^.{20,}$`. |
|
||||
| `nc:prompt error:<msg>` | grammar doc `:55`; driver `setup/lib/skill-driver.ts:46-47` | **deleted**. Error text derived from the question prose (§5.3). |
|
||||
| `nc:run label:<word>` | `scripts/skill-apply.ts:458`; doc-comment mention `:451` | **deleted**. Labels are heading-derived only. |
|
||||
| `on-fail:<token>` | `scripts/skill-apply.ts:419-430` (no lint rule exists) | **deleted**. Hint is always the surrounding prose. |
|
||||
| `validate:` + `flags:` (prompt & run-capture) | lint `:249-263,:311-317` | **kept** (data semantics). Prompt validate now enforced at bind (§4). |
|
||||
| `normalize:trim\|rstrip-slash\|lower` | lint `:267-269`; bind `skill-apply.ts:483` | **kept** (canonical-value semantics). |
|
||||
| `reuse:<ENV_KEY>` | lint `:270-272`; driver `setup/lib/skill-driver.ts:169-172` | **kept** (binding metadata; consumed only by the driver's reuse offer). |
|
||||
| `when:`, `effect:check`, `effect:step`, capture forms, journal semantics | various | **kept**, unchanged. |
|
||||
|
||||
Lint addition: `validate()` gains errors for the six removed attrs
|
||||
(`operator open:/gate`, `prompt min:/error:`, any-directive `label:`/`on-fail:`)
|
||||
so stale authorship fails loudly instead of silently no-oping. Lint also gains a
|
||||
**warning** for an unguarded `nc:operator` immediately followed by `when:`-guarded
|
||||
directives spanning more than one branch value (the static gate policy cannot
|
||||
know which branch runs — see §5.1 and open question 1).
|
||||
|
||||
### Authored skills carrying removed attrs (strip + prose check)
|
||||
|
||||
| Skill | Line | Change |
|
||||
|---|---|---|
|
||||
| `.claude/skills/add-teams/SKILL.md` | `:101` | drop `open:https://portal.azure.com` (URL already in the body — step 1, body line 2; body line 1 is the heading sentence) |
|
||||
| `.claude/skills/add-teams/SKILL.md` | `:132` | `min:20` → `validate:^.{20,}$` |
|
||||
| `.claude/skills/add-teams/SKILL.md` | `:173`, `:203` | drop `gate` (policy reproduces both — §5.1 parity) |
|
||||
| `.claude/skills/add-telegram/SKILL.md` | `:134` | drop `open:https://t.me/{{bot_username}}` **and fold the URL into the body** (verified: body says "Open @{{bot_username}}" — the URL exists only in the attr today) |
|
||||
| `.claude/skills/add-discord/SKILL.md` | `:125` | drop `open:https://discord.com/...` **and fold the invite URL into the body** (verified: body says "Open the invite link" — URL only in the attr today) |
|
||||
|
||||
No skill uses `error:`, `label:`, or `on-fail:` (grep verified). Re-lint every
|
||||
touched skill (`pnpm exec tsx scripts/skill-directives.ts <dir>`).
|
||||
|
||||
### Prompter / reporter implementers & callers (all migrate — clean break)
|
||||
|
||||
| Caller / implementer | Where | Migration |
|
||||
|---|---|---|
|
||||
| `clackPrompter` (the wizard Prompter) | `setup/lib/skill-driver.ts:66-120` | becomes the driver's `resolveInput` impl (ask + `?` help-escape + clearOnError + secret masking) — `tell`/`confirm`/`open` dissolve into the `onEvent` handler + the `confirm`/`openUrl` seams (§5) |
|
||||
| `promptValidator` | `setup/lib/skill-driver.ts:37-50` | driver-side; loses `min`/`error`, gains prose-derived message (§5.3) |
|
||||
| `spinnerReporter` | `setup/lib/skill-driver.ts:259-274` | folded into the driver's `onEvent` handler (step-start/step-end branch), still built on `startSpinner` (`setup/lib/runner.ts:314`) |
|
||||
| `runSkill` + `RunSkillOptions` | `setup/lib/skill-driver.ts:286-340` | `prompter?`/`reporter?` options become `resolveInput?`/`onEvent?`; **new** `confirm?`/`openUrl?` options (§5.0); `reuse`, `channel`/`step` (help-escape ctx, `:308-314`), `reuseFromEnv` (`:143-188`, now validate-pre-filtered — §5.4) stay driver-side |
|
||||
| skill-driver CLI | `setup/lib/skill-driver.ts:343-360` | uses the new defaults; no interface change visible to the operator |
|
||||
| `runChannelSkill` overrides | `setup/channels/run-channel-skill.ts:122` (`prompter`), `:126` (`reporter`) | override fields renamed to `resolveInput`/`onEvent`; `confirm`/`openUrl` passthroughs added; fail-path (`:133-151`) unchanged |
|
||||
| `applyProviderSkill` defer-all Prompter | `setup/providers/install.ts:62-66` | delete the stub — omit `resolveInput` entirely (absent ⇒ defer, same semantics) |
|
||||
| `setup/auto.ts` call sites | `:350` (provider), `:560-572` (channels) | no signature change needed (they pass no prompter/reporter) |
|
||||
| `setup/provider-auth.ts` | `:53` | unchanged (blockers contract survives) |
|
||||
| engine test fakes | `scripts/skill-apply.test.ts:39` (`headless`), `:447`, `:505`, `:518`, `:534`, `:545`, `:613`, `:637`, `:1219` | `headless(vals)` becomes `{ resolveInput: async (n) => vals[n] }`; tell/open/confirm fakes become recorded `onEvent` handlers or move to driver-policy tests (§9); any fixture whose `inputs` violate a declared `validate:` updates to valid-shaped values (§4) |
|
||||
| driver test fakes | `setup/lib/skill-driver.test.ts:73`, `:100` (reporter) | mechanical rewrite to `resolveInput`/`onEvent` |
|
||||
| driver reuse-offer tests | `setup/lib/skill-driver.test.ts:149`, `:167`, `:202` | NOT a mechanical rewrite — today they queue answers through fake `prompter.confirm`s; they migrate to the new `RunSkillOptions.confirm` seam (§5.0) |
|
||||
| run-channel-skill test stub prompter | `setup/channels/run-channel-skill.test.ts:95-100` (teams gate/open assertions `:115-124`) | becomes a driver-policy assertion running the **default** `onEvent` policy handler with `confirm`/`openUrl` injected (§5.0 injection semantics) — proving the §5.1/§5.2 parity claims. Fixture `app_password: 'sekret'` → a 20+-char value (§4); Option-A slack fixture (`:41-70`) updates `signing_secret`/`owner_handle` + the `userId` assertion (§1 invariant) |
|
||||
| `back-nav.ts` `backGate`, `claude-handoff.ts` help-escape | `setup/lib/back-nav.ts:31`, `setup/lib/claude-handoff.ts:82,:164,:182` | untouched (already driver-side) |
|
||||
|
||||
## 4. Behavior change: validate + normalize apply to EVERY bound value
|
||||
|
||||
Today `validate:` is enforced only by the interactive prompter
|
||||
(`setup/lib/skill-driver.ts:37-50`); `inputs` bypass it
|
||||
(documented at `scripts/skill-directives.ts:51`). That is data validation
|
||||
misfiled as prompt UX. New rule, at the single bind point
|
||||
(`skill-apply.ts:766-780` region):
|
||||
|
||||
1. Resolve the raw value: `inputs[var]` first, else `await resolveInput(var, meta)`.
|
||||
Both `undefined` ⇒ defer (push bare var name — unchanged).
|
||||
2. Apply `normalize:` (unchanged, already both-paths — `normalizeValue`, `:483`).
|
||||
3. **New:** if the prompt carries `validate:` (+ `flags:`), test the *normalized*
|
||||
value. On mismatch: the var stays **unbound**, and
|
||||
`` `<var>: invalid value (does not match validate:<re>)` `` is pushed to
|
||||
`deferred`. Not an agentTask, not a throw — downstream consumers of the var
|
||||
defer exactly as if the value were never supplied, and `fullyApplied` is
|
||||
`false`. A pipeline passing a malformed env value fails loudly.
|
||||
|
||||
Notes:
|
||||
- Normalize-then-validate order is normative (a trailing-slash URL is stripped
|
||||
before the `^https://` check — matches the teams `public_url` authoring).
|
||||
- An invalid `inputs` value does **not** fall through to `resolveInput` — inputs
|
||||
win outright, and a caller that pre-supplied a value gets a loud rejection,
|
||||
never a surprise second acquisition path. The interactive dead-end this could
|
||||
create for reused `.env` credentials is closed on the driver side instead:
|
||||
`reuseFromEnv` pre-filters every offer through the prompt's
|
||||
`normalize`/`validate`/`flags` meta, so a stale credential that no longer
|
||||
matches the declared shape is **never offered** and the operator is prompted
|
||||
fresh (§5.4). A caller passing raw `inputs` (pipeline, tests) still fails
|
||||
loudly — that is the point.
|
||||
- The interactive re-ask loop moves into the wizard's `resolveInput` (clack
|
||||
`validate`), so engine-level rejection rarely fires interactively; it is the
|
||||
backstop for programmatic paths.
|
||||
- Secret values never appear in the deferred entry (only the var name and the
|
||||
regex source).
|
||||
- run-capture `validate:` is unchanged (it already throws → bounces,
|
||||
`skill-apply.ts:551-572` — a command's output has no human to re-ask).
|
||||
- **Test-fixture consequence** (part of the step that lands this change): every
|
||||
in-tree fixture that supplies an `inputs` value violating its prompt's
|
||||
declared `validate:` must update to a valid-shaped value. Known: the Option-A
|
||||
slack fixture (`run-channel-skill.test.ts:49` — `signing_secret`,
|
||||
`owner_handle`, with the `userId` assertion at `:62` updated consistently)
|
||||
and the teams deferWire fixture (`:102-107` — `app_password` vs. the new
|
||||
`^.{20,}$`). Sweep `scripts/skill-apply.test.ts` fixtures the same way.
|
||||
|
||||
## 5. Wizard driver policy (presentation derived from document structure)
|
||||
|
||||
### 5.0 Where the policy lives, and the driver's own seams
|
||||
|
||||
The policy **logic** is UI-free and shared: a new module
|
||||
`scripts/skill-policy.ts` beside the parser exports `gatePolicy(md)` (→ map of
|
||||
operator line → needs-confirm + confirm flavor, §5.1) and `extractOfferUrl(text)`
|
||||
(§5.2), both built on the shared `parseDirectives`. The wizard driver consumes
|
||||
it; an agent-relay consumer (§7) imports the same module instead of duplicating
|
||||
the judgment or dragging in clack. The §9 policy unit tests live at this shared
|
||||
home.
|
||||
|
||||
The wizard driver (`setup/lib/skill-driver.ts`) keeps the clack rendering and
|
||||
gains two injectable interaction seams on `RunSkillOptions` — these are
|
||||
*driver* options, allowed by the boundary rule (it binds only the core):
|
||||
|
||||
- `confirm?: (message: string) => Promise<boolean>` — used by the reuse offer
|
||||
(§5.4), the natural-barrier gate (§5.1), and the URL offer (§5.2). Default:
|
||||
clack `p.confirm`, **TTY-gated exactly like `spinnerReporter`**
|
||||
(`skill-driver.ts:260`) — non-TTY resolves `true` (proceed), preserving
|
||||
today's headless-prompter-without-confirm semantics (`skill-apply.ts:802`'s
|
||||
optional chain). A non-TTY run with full inputs never stalls.
|
||||
- `openUrl?: (url: string) => Promise<void>` — used by the URL offer. Default:
|
||||
`setup/lib/browser.ts` `openUrl`, attempted only after a `confirm` yes.
|
||||
|
||||
**Injection semantics (normative):** an injected `onEvent` **replaces** the
|
||||
driver's default policy handler entirely — same rule as today's injected
|
||||
prompter ("the injector owns its I/O", `skill-driver.ts:311`). Therefore
|
||||
driver-policy parity tests must run the **default** handler and inject
|
||||
`confirm`/`openUrl` (the run-channel teams test does exactly this — §3, §9);
|
||||
injecting `onEvent` to observe policy behavior would only observe itself.
|
||||
|
||||
Because the engine awaits `onEvent` (§2), a confirm inside the default handler
|
||||
blocks the engine — that is the entire gating mechanism.
|
||||
|
||||
### 5.1 Natural-barrier gate policy
|
||||
|
||||
For each `nc:operator` directive at line L, `gatePolicy` computes
|
||||
`needsConfirm(L)`:
|
||||
|
||||
1. Scan forward through subsequent directives, skipping **only** directives
|
||||
whose `when:<var>=<value>` guard is **incompatible** with this operator's own
|
||||
guard — same var, different value. No guard, or an identical guard, is
|
||||
compatible. (This makes mutually-exclusive branches gate on their *own* next
|
||||
action: imessage's `when:mode=local` operator at `:111` skips the two
|
||||
remote-only prompts and gates on the local configure run at `:151`;
|
||||
whatsapp's `when:auth_method=qr` operator at `:96` skips the pairing-code
|
||||
operator at `:104` — guard-incompatible — and gates on the qr step at `:114`.)
|
||||
2. Next compatible directive is another `operator` → **no confirm** — the chain's
|
||||
**last** operator carries the barrier. (Operators are NOT skipped-and-scanned-past:
|
||||
that would make the earlier block of a chain inherit the later block's barrier
|
||||
and double-confirm — the exact bug the teams parity table below forbids.)
|
||||
3. Next compatible directive is a `prompt` → **no confirm** (the prompt is the barrier).
|
||||
4. No such directive (end of document) → **no confirm** (a final handoff block, e.g. teams `:228`).
|
||||
5. Anything else (`run`, `copy`, `dep`, `append`, `env-set`, `json-merge`) →
|
||||
**confirm** after rendering. Confirm wording is derived from the barrier's
|
||||
*flavor* — the next compatible directive's effect: `effect:step` →
|
||||
readiness phrasing (`"Ready? The next step starts immediately."` — the block
|
||||
describes future action: "a pairing code is about to appear"); anything else
|
||||
→ completed-work phrasing (`"Done with the steps above? Continue when you're
|
||||
ready."`). `gatePolicy` returns the flavor with the boolean.
|
||||
|
||||
**Decline semantics (normative):** the barrier confirm is a *pause*, not a
|
||||
branch. A "No"/cancel answer proceeds anyway — matching today's engine, which
|
||||
discards the gate confirm's result (`skill-apply.ts:802`). The driver's handler
|
||||
must never throw for a decline (an operator-event throw would bounce + latch
|
||||
`blocked`, §2.3). A driver MAY upgrade decline to a re-ask loop as pure polish;
|
||||
it must not abort.
|
||||
|
||||
**Known limitation (lint-warned, open question 1):** an *unguarded* operator
|
||||
followed by guarded directives of more than one branch value keys its barrier
|
||||
decision off a directive that may be runtime-skipped. No in-tree skill authors
|
||||
this; the §3 lint warning flags it.
|
||||
|
||||
At runtime, on each `operator` event the default handler: renders the clack
|
||||
note (`p.note(text, 'Do this')`), runs the URL offer (§5.2), then the confirm
|
||||
if `needsConfirm(line)`.
|
||||
|
||||
**Verified parity against today's tree** (re-derived under rules 1–5 above):
|
||||
|
||||
- teams `:80` → prompt `:93`: no confirm. `:101` → prompt `:110`: no confirm.
|
||||
`:124` → prompt `:132`: no confirm. `:158` → next compatible is **operator**
|
||||
`:173` (rule 2): **no confirm** — the chain's last block carries the barrier.
|
||||
`:173` → `run effect:check` `:186`: **confirm**. `:203` → `run effect:restart`
|
||||
`:217`: **confirm**. `:228` → end: no confirm. Exactly the two authored
|
||||
`gate`s reproduced — behavior identical.
|
||||
- telegram `:134` (→ `run effect:step` pairing `:142`) **gains** a confirm with
|
||||
readiness phrasing — this restores the old bespoke flow's readiness pause
|
||||
that the directive port lost.
|
||||
- signal `:94` (→ `effect:step` `:105`) and both whatsapp operators (`:96` →
|
||||
guard-skip `:104` → `effect:step` `:114`; `:104` → guard-skip `:114` →
|
||||
`effect:step` `:117`) gain the same readiness pause before a QR/pairing
|
||||
appears. whatsapp `:146` → prompt `:155`: no confirm.
|
||||
- imessage `:111` (`when:mode=local`) → guard-skips `:126`,`:134`,`:137` →
|
||||
`run effect:external` `:151`: **confirm**. `:126` (`when:mode=remote`) →
|
||||
prompt `:134`: no confirm.
|
||||
- discord `:125` (→ `run effect:fetch` `:139`, the DM resolve) gains a confirm —
|
||||
desirable: the DM open fails until the bot is invited (open question 2). Slack's
|
||||
operators (`:69` → prompt `:80`; `:97` → prompt `:112`) are prompt-followed →
|
||||
unchanged.
|
||||
|
||||
### 5.2 URL offer (replaces `open:`)
|
||||
|
||||
On an `operator` event, `extractOfferUrl(text)` scans the **rendered** text for
|
||||
the first *offerable* URL: matches `/https?:\/\/[^\s)>\]]+/`, then **excludes**
|
||||
candidates containing `<` or `{{` (template placeholders / unsubstituted vars)
|
||||
and requires the candidate to parse via `new URL()` with a well-formed host.
|
||||
Without the exclusion, slack's `:97` block — `https://<your-public-host>/webhook/slack`
|
||||
— would produce a nonsense "Open https://<your-public-host?" offer (the char
|
||||
class stops at `>` but not `<`). Slack `:97` is the normative negative fixture.
|
||||
|
||||
If an offerable URL is found and the run is interactive:
|
||||
`confirm("Open <url> in your browser?")` → on yes, `openUrl` (both via the §5.0
|
||||
seams — TTY-gated, non-TTY skips). Confirm-then-open matches the old bespoke
|
||||
flows; prose-primary already forces URLs into the text (after the §3 skill
|
||||
edits), so `open:` was redundant authorship. Order within the handler:
|
||||
note → URL offer → natural-barrier confirm.
|
||||
|
||||
**Full operator-body URL inventory** (the offer scans *every* operator body,
|
||||
not just ex-`open:` blocks — audited like §5.1):
|
||||
|
||||
| Site | URL | Outcome |
|
||||
|---|---|---|
|
||||
| teams `:101` (body line 2) | `https://portal.azure.com` | offer — preserves today's `open:` behavior |
|
||||
| telegram `:134`, discord `:125` (after the §3 fold-into-prose edits) | t.me / invite URL | offer — preserves today's `open:` behavior |
|
||||
| teams `:158` (body) | `https://portal.azure.com` | **new** offer (no `open:` today) — accepted, same judgment as the discord confirm; open question 3 |
|
||||
| discord `:70` (body `:72`) | `https://discord.com/developers/applications` | **new** offer — accepted; open question 3 |
|
||||
| imessage `:126` (body `:128`) | `https://photon.codes` | **new** offer — accepted; open question 3 |
|
||||
| slack `:97` (body `:99`) | `https://<your-public-host>/webhook/slack` | **excluded** (placeholder) — slack stays offer-free, as today |
|
||||
| slack `:69` (`api.slack.com/apps`, no scheme), signal `:94` (`sgnl://…`), all other operators | — | no match |
|
||||
|
||||
### 5.3 Validation error text (replaces `error:`)
|
||||
|
||||
`promptValidator(validate, flags, question)` — on a regex miss the message is
|
||||
`` `That doesn't match the expected format. ${question}` `` (the full prompt
|
||||
body, which by authoring convention describes the expected shape, e.g.
|
||||
"Paste the bot token from BotFather (looks like `123456:ABC-DEF...`)."). No
|
||||
`min` branch (regex-encoded now), no `error:` override.
|
||||
|
||||
### 5.4 Stays driver-side, unchanged in spirit
|
||||
|
||||
`clearOnError` secret re-paste, secret masking (`p.password`), the masked reuse
|
||||
offer (`reuseFromEnv` + its `reuse:` linkage — confirm now via the §5.0 seam,
|
||||
`skill-driver.ts:327-328` today), the `?` help-escape (channel/step ctx already
|
||||
threaded via `RunSkillOptions`, `run-channel-skill.ts:130-131`), `backGate`,
|
||||
spinners (now driven by step events), `hostExec`/`hostExecStream`.
|
||||
|
||||
**One behavior addition:** `reuseFromEnv` pre-filters offers through the target
|
||||
prompt's `normalize`/`validate`/`flags` (parsed from the same directives it
|
||||
already walks) — an `.env` value that would fail validate-at-bind is silently
|
||||
not offered, so the operator is prompted fresh instead of hitting a §4
|
||||
dead-end (`fullyApplied` false → `failWith`). This is the driver-side closure
|
||||
of the stale-credential path; raw `inputs` remain loud-fail (§4).
|
||||
|
||||
## 6. Pipeline consumer contract
|
||||
|
||||
- **Inputs from env — convention:** for each prompt var `foo_bar`, read
|
||||
`NC_INPUT_FOO_BAR` (prefix `NC_INPUT_`, var uppercased). A small helper
|
||||
`inputsFromEnv(md: string, env = process.env)` (driver-agnostic, may live
|
||||
beside the engine) parses the skill's prompt vars via `parseDirectives` and
|
||||
returns the `inputs` record. Var names are case-sensitive in the grammar
|
||||
(`skill-directives.ts:111`), so uppercasing can collide (`bot_token` vs
|
||||
`Bot_Token`): `inputsFromEnv` **errors on a collision**. All in-tree vars are
|
||||
lowercase today; a lint rule requiring lowercase prompt/capture var names is
|
||||
cheap and makes the mapping bijective (open question 6). No `resolveInput`,
|
||||
no `onEvent` required (optionally an `onEvent` that logs step events as CI
|
||||
lines).
|
||||
- **Run:** `applySkill(skillDir, root, { inputs, exec, execStream?, skipEffects })`
|
||||
with `skipEffects` per deployment (e.g. `['restart']` when the deploy restarts once).
|
||||
- **What a pipeline can fully apply (normative boundary):** `inputs` binds
|
||||
**prompt** vars only — the engine never reads it for `run`/`step` captures
|
||||
(`skill-apply.ts:773` — prompt branch only), so a pipeline cannot pre-supply
|
||||
a capture-bound var like `platform_id`. And `effect:step` without a real
|
||||
`execStream` throws → bounces (`skill-apply.ts:655-656`);
|
||||
`skipEffects:['step']` avoids the bounce but leaves the step's capture vars
|
||||
unbound, so downstream consumers defer either way. Consequence: **skills with
|
||||
an `effect:step` are wizard/relay-only for full application** — today that is
|
||||
telegram (`:142`), whatsapp (`:114`,`:117`), and signal (`:105`). slack,
|
||||
discord, teams, and imessage carry no `effect:step` and can go fully green
|
||||
from env inputs (+ `exec`), with their operator blocks landing in the
|
||||
manual-steps report. A pipeline-grade `execStream`, or letting `inputs`
|
||||
pre-bind capture vars (bound var ⇒ capture skipped), would move that
|
||||
boundary — deliberately out of scope here (open question 10).
|
||||
- **Consume the result:**
|
||||
- `res.operatorMessages` → emitted verbatim, numbered, as the "manual steps"
|
||||
report artifact (the human steps the pipeline cannot do).
|
||||
- `fullyApplied(res)` gates the job: `false` ⇒ non-zero exit, printing
|
||||
`res.deferred` (which now includes §4 invalid-input reasons — a malformed
|
||||
env value is a loud failure) and `firstFailureHint(res)` + each
|
||||
`agentTask.reason` for real bounces.
|
||||
- `res.vars` → exported for downstream jobs (e.g. `platform_id` into a wire step).
|
||||
|
||||
## 7. Agent-relay consumer sketch
|
||||
|
||||
A coding agent driving a skill over chat implements the two seams:
|
||||
|
||||
- `resolveInput(name, meta)`: send `meta.question` to the chat; for
|
||||
`meta.secret`, instruct the user to supply the value out-of-band (or via the
|
||||
platform's redaction affordance) and never echo it back. Run its own re-ask
|
||||
loop against `meta.validate`/`meta.flags` conversationally ("that doesn't look
|
||||
like a bot token — it should start with `xoxb-`"); return the final answer, or
|
||||
`undefined` if the user says skip (⇒ defer, degrade-to-agent semantics apply
|
||||
downstream).
|
||||
- `onEvent(e)`: `operator` → relay the text as a chat message and (because the
|
||||
engine awaits) hold the return until the user replies "done" when the next
|
||||
action is side-effecting — importing `gatePolicy` from the shared
|
||||
`scripts/skill-policy.ts` (§5.0) for the same natural-barrier judgment as the
|
||||
wizard, with no clack/TTY baggage; or simply always ask.
|
||||
`step-start`/`step-end` → optional progress messages ("Building… ok, 12s").
|
||||
- Everything else (`exec`, journal, bounce handling) is identical to the wizard;
|
||||
the agent reads `agentTasks[].prose` and applies bounced steps itself — which
|
||||
is exactly the degrade-to-agent path the prose was written for.
|
||||
|
||||
## 8. Implementation step plan
|
||||
|
||||
Each step must be independently green — `pnpm exec tsc --noEmit` (root) +
|
||||
`pnpm test` (full vitest suite) + skill lint on every touched skill — and
|
||||
committable on its own. Core lands before consumers migrate; the old seam is
|
||||
deleted only after no consumer uses it (transitional coexistence inside the
|
||||
branch is fine; the *merged* result has no compat layer).
|
||||
|
||||
1. **Core: add the new seam (additive) + validate-at-bind.**
|
||||
`scripts/skill-apply.ts`: add `resolveInput` + `onEvent` + `InputMeta` +
|
||||
`ApplyEvent`; engine prefers them when present (falls back to
|
||||
`prompter`/`reporter` if not — temporary); implement validate-at-bind (§4)
|
||||
and the awaited-event ordering; re-document `stepLabel` null semantics (§2).
|
||||
**Includes the §4 fixture sweep**: Option-A slack inputs + `userId`
|
||||
assertion, teams deferWire `app_password`, and any `skill-apply.test.ts`
|
||||
fixture with shape-violating inputs — updated in this same commit so the
|
||||
suite is green. New tests: event union payloads + balance,
|
||||
await-before-proceed ordering (an async `onEvent` that records completion),
|
||||
`resolveInput` meta contents, validate-at-bind for inputs AND resolveInput
|
||||
answers (normalize-then-validate, no-fallthrough from invalid inputs to
|
||||
`resolveInput`, deferred entry format, `fullyApplied` false, secret never in
|
||||
the entry), onEvent-throw ⇒ bounce (incl. on an operator event).
|
||||
2. **Shared policy module + wizard driver migration.** New
|
||||
`scripts/skill-policy.ts`: `gatePolicy(md)` (§5.1 rules incl. operator-chain
|
||||
termination, guard-compatibility, confirm flavor) + `extractOfferUrl(text)`
|
||||
(§5.2 incl. placeholder exclusion) — with the parity-table unit tests.
|
||||
`setup/lib/skill-driver.ts`: `resolveInput` impl (ex-`clackPrompter.ask`,
|
||||
help-escape intact), default `onEvent` handler (spinner branch from
|
||||
`spinnerReporter` + operator branch consuming `gatePolicy`/`extractOfferUrl`),
|
||||
new `confirm`/`openUrl` options with TTY-gated defaults (§5.0), decline =
|
||||
proceed, `reuseFromEnv` validate-pre-filter (§5.4), §5.3 error text;
|
||||
`RunSkillOptions.prompter/reporter` → `resolveInput/onEvent` (+ documented
|
||||
replacement semantics for injected `onEvent`);
|
||||
`setup/channels/run-channel-skill.ts` override renames + `confirm`/`openUrl`
|
||||
passthrough; `setup/providers/install.ts` drops its stub Prompter. Reuse
|
||||
tests migrate to the `confirm` seam; the teams run-channel test runs the
|
||||
default handler with injected `confirm`/`openUrl` (§9). After this step no
|
||||
in-tree caller passes `prompter`/`reporter`.
|
||||
3. **Core: delete the old seam.** Remove `Prompter`, `PromptOpts`,
|
||||
`StepReporter`, `ApplyOptions.prompter/reporter`; remove engine handling of
|
||||
`open:`/`gate` (`:791,:796,:802`), `label:` (`:458`), `on-fail:`+`AgentTask.hint`
|
||||
(`:419-430,:236`), `min:`/`error:` plumbing (`:499-506`). Rework/delete the
|
||||
engine tests that asserted removed behavior (§9).
|
||||
4. **Skills cleanup.** Strip attrs per §3 table; fold the telegram + discord
|
||||
URLs into their operator prose; teams `min:20` → `validate:^.{20,}$`.
|
||||
Re-lint all touched skills; the run-channel teams parity test (now
|
||||
driver-policy-based from step 2) must still prove both barriers fire and the
|
||||
portal offer survives the `open:` removal (body URL, §5.2 inventory).
|
||||
5. **Grammar diet.** `scripts/skill-directives.ts`: drop `min:`/`error:`/`open:`/`gate`
|
||||
validation + grammar doc; add lint errors rejecting the six removed attrs
|
||||
and the §3 unguarded-operator/multi-branch warning; rework directive tests.
|
||||
(Ordered after step 4 so lint never fails on skills still carrying the attrs.)
|
||||
6. **Sweep + parity audit.** Grep proves zero remaining references to
|
||||
`Prompter|PromptOpts|StepReporter|on-fail:|label:|min:|error:` (in the seam
|
||||
sense) and `operator.*(open:|gate)`; container typecheck
|
||||
(`pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit`) untouched;
|
||||
full suite count ≥ 680 passed | 1 skipped; Option-A test assertion structure
|
||||
unmodified (fixture values per §1/§4); production resolve/wire paths
|
||||
untouched.
|
||||
|
||||
## 9. Test-migration notes (per step)
|
||||
|
||||
- **Step 1:** all existing tests stay green — the ONLY permitted edits are the
|
||||
§4 shape-violating input fixtures (Option-A slack `:49`/`:62`, teams deferWire
|
||||
`:106`, plus any `skill-apply.test.ts` siblings the sweep finds). New
|
||||
describe blocks in `scripts/skill-apply.test.ts`: `onEvent` events (mirror of
|
||||
the reporter suite at `:1003-1054`, plus operator events + await-ordering) and
|
||||
validate-at-bind (extends the PromptOpts suite pattern at `:1189-1242`).
|
||||
- **Step 2:** `setup/lib/skill-driver.test.ts` fakes (`:73,:100`) rewritten
|
||||
mechanically to `resolveInput`/`onEvent`; the reuse-offer tests
|
||||
(`:149,:167,:202`) migrate to the injected `confirm` option (accept /
|
||||
decline / helper-reuse paths preserved); the `clackPrompter.open`
|
||||
existence test (`:218-223`) becomes a URL-offer policy test; help-escape tests
|
||||
(`:225-259`) keep their shape (the escape lives in the driver's `resolveInput`);
|
||||
`promptValidator` test (`:261-271`) loses min/error, gains prose-derived-message
|
||||
assertions. **Policy tests at `scripts/skill-policy.ts`'s home** encode the
|
||||
§5.1 parity table: teams (confirm ×2, **no confirm on the `:158` chain head** —
|
||||
the operator-chain rule's regression fixture), telegram/signal/whatsapp
|
||||
(readiness-flavor pause), imessage (guard-compatibility), end-of-document;
|
||||
plus `extractOfferUrl` fixtures: the §5.2 inventory incl. slack's placeholder
|
||||
as the negative case. `run-channel-skill.test.ts:75-125` (teams) re-asserts
|
||||
gate-before-manifest + portal-URL-offer by running the **default** `onEvent`
|
||||
handler with injected `confirm`/`openUrl` (never an injected `onEvent`, which
|
||||
replaces the policy — §5.0).
|
||||
- **Step 3:** delete engine tests for removed syntax: `nc:operator open + gate`
|
||||
(`scripts/skill-apply.test.ts:492-551`), `label:` override + `on-fail:` cases
|
||||
(`:1064,:1072`, `:1145-1162`); keep their *semantic* siblings (heading labels,
|
||||
prose hint default, unresolved-var deferral of an operator body). The prompter
|
||||
threading tests (`:634-645,:1212-1231`) become `InputMeta` assertions.
|
||||
- **Step 4:** no test-file changes beyond fixtures; skill lint is the gate.
|
||||
- **Step 5:** `scripts/skill-directives.test.ts`: drop `:268-271` (min) and
|
||||
`:325-355` (open/gate) as validations-of-supported-syntax; re-add them
|
||||
inverted (the new lint errors reject the attrs). PromptOpts-parse test
|
||||
(`:247-261`) drops `min:`.
|
||||
- **Throughout:** the coverage-parity bar is behavioral, not file-shaped: every
|
||||
guarantee an old test proved (barrier ordering, open-after-render, balanced
|
||||
spinner events, hint provenance) must have a successor at its new home.
|
||||
|
||||
## 10. Open questions (decisions this spec made that the design left open)
|
||||
|
||||
1. **Guard-compatibility in the gate scan (§5.1.1).** The design said "followed
|
||||
by"; this spec defines *followed by* as skipping `when:`-incompatible
|
||||
directives so mutually-exclusive branches gate correctly (imessage local,
|
||||
whatsapp qr/pairing). Alternative (pure document order) would miss imessage's
|
||||
"stop and wait" and double-gate whatsapp. Two scrutiny points: (a) the
|
||||
compatibility rule compares only same-var/different-value; different-var
|
||||
guards are treated as compatible (conservative). (b) An **unguarded**
|
||||
operator followed by guarded directives of more than one branch value keys
|
||||
its decision off a directive that may be runtime-skipped (e.g. unguarded
|
||||
operator → `prompt when:mode=remote` → `run when:mode=local`: policy says
|
||||
no-confirm, but at runtime mode=local skips the prompt). No in-tree skill
|
||||
authors this; §3's lint warning covers it.
|
||||
2. **Discord gains a confirm** (`add-discord:125` → `effect:fetch`). The design's
|
||||
parity list mentioned teams + telegram only; the policy also pauses before
|
||||
discord's DM resolve. Judged desirable (the fetch fails until the bot is
|
||||
invited) — but it is a new prompt in an existing flow.
|
||||
3. **Three new URL offers** (§5.2 inventory): teams `:158` (portal.azure.com),
|
||||
discord `:70` (developers portal), imessage `:126` (photon.codes) had no
|
||||
`open:` today and gain an offer because the scan covers every operator body.
|
||||
Accepted — same judgment as the discord confirm — but they are behavior
|
||||
changes in existing flows.
|
||||
4. **Confirm triggers on ALL non-prompt/non-operator directives** (§5.1.5), not
|
||||
just the engine's dangerous-side-effect set (`restart|step|wire`). Needed for
|
||||
teams parity (its first gate precedes `effect:check`+`external`). Consequence:
|
||||
an operator block directly followed by e.g. an `env-set` would also confirm —
|
||||
no such authoring exists today.
|
||||
5. **Invalid-input failure shape (§4): deferred, not agentTask.** Chosen because
|
||||
a bad value is a missing-*valid*-value (re-supply and re-run), not a step an
|
||||
agent can apply from prose; it also keeps the run-health gate un-tripped so a
|
||||
re-run with a fixed env var completes. The alternative (bounce) would
|
||||
cascade-block later side effects. Relatedly: invalid `inputs` do NOT fall
|
||||
through to `resolveInput` (§4) — the driver's reuse pre-filter (§5.4) is the
|
||||
interactive recovery path.
|
||||
6. **Env-input convention `NC_INPUT_<VAR>` (§6)** and that `inputsFromEnv` is a
|
||||
helper, not an engine feature (inputs stay the only env-agnostic seam). Prefix
|
||||
bikeshed welcome; the engine never reads `process.env` for inputs.
|
||||
`inputsFromEnv` errors on an uppercase collision; a lowercase-var lint rule
|
||||
would make the mapping bijective.
|
||||
7. **Operator event fires even with no consumer** — with `onEvent` absent the
|
||||
block is still collected in `operatorMessages` (today's headless behavior,
|
||||
`skill-apply.test.ts:452-456`). The **engine** never defers/bounces an
|
||||
operator block on its own; a consumer that *throws* from `onEvent` opts into
|
||||
the standard bounce path (§2.3) — that is the consumer's choice, not an
|
||||
engine judgment, and the wizard's default handler never throws (decline =
|
||||
proceed, §5.1).
|
||||
8. **`AgentTask.hint` field removal** (vs. keeping it always-equal-to-prose for
|
||||
result-shape stability). Removal chosen for the clean break; any external
|
||||
consumer of `hint` (none in-tree) would break.
|
||||
9. **Teams `min:20` regex** chosen as `^.{20,}$` (any 20+ chars). If the intent
|
||||
was tighter (Azure secret alphabet), tighten in the skill edit — the seam
|
||||
doesn't care.
|
||||
10. **Pipeline boundary for `effect:step` skills (§6).** telegram/whatsapp/signal
|
||||
cannot go fully green in a pipeline (no human at the QR/pairing step, and
|
||||
`inputs` cannot pre-bind capture vars). Two possible future escapes — a
|
||||
pipeline-grade `execStream` contract, or `inputs` pre-binding capture vars
|
||||
(bound var ⇒ capture skipped) — both deliberately out of scope; the spec'd
|
||||
behavior is the loud `fullyApplied:false`.
|
||||
11. **`step-end` on validate-at-bind rejection:** none — prompts never emitted
|
||||
step events (they are not mutations) and still don't. Only the deferred entry
|
||||
records the rejection. If wizards want live feedback, their own `resolveInput`
|
||||
loop already provided it.
|
||||
|
||||
## 11. Rejected review findings
|
||||
|
||||
- **"`run-channel-skill.ts:122` is `exec`; the `prompter` passthrough is at `:123`"**
|
||||
(review 1, citation sweep) — rejected: `grep -n` shows `:121 exec: overrides.exec,`
|
||||
and `:122 prompter: overrides.prompter,`. The spec's `:122` citation was
|
||||
correct as written. (The same review's other three citation fixes —
|
||||
`resolveRemote :283`, teams `:101` body-line wording, `label:` doc mention
|
||||
`:451` — were verified correct and are folded.)
|
||||
@@ -0,0 +1,166 @@
|
||||
# Main
|
||||
|
||||
You are Main, a personal assistant. You help with tasks, answer questions, and can schedule reminders.
|
||||
|
||||
## What You Can Do
|
||||
|
||||
- Answer questions and have conversations
|
||||
- Search the web and fetch content from URLs
|
||||
- **Browse the web** with `agent-browser` — open pages, click, fill forms, take screenshots, extract data (run `agent-browser open <url>` to start, then `agent-browser snapshot -i` to see interactive elements)
|
||||
- Read and write files in your workspace
|
||||
- Run bash commands in your sandbox
|
||||
- Schedule tasks to run later or on a recurring basis
|
||||
- Send messages back to the chat
|
||||
|
||||
## Communication
|
||||
|
||||
Be concise — every message costs the reader's attention.
|
||||
|
||||
### Destinations
|
||||
|
||||
Each turn, your system prompt lists the destinations available to you. If you only have one destination, just write your response directly — it goes there automatically. If you have multiple, wrap each message in a `<message to="name">...</message>` block:
|
||||
|
||||
```
|
||||
<message to="family">On my way home, 15 minutes</message>
|
||||
<message to="worker-1">kick off the pipeline</message>
|
||||
```
|
||||
|
||||
Inbound messages are labeled with `from="name"` so you can tell which destination they came from and reply using that same name.
|
||||
|
||||
### Mid-turn updates
|
||||
|
||||
Use the `mcp__nanoclaw__send_message` tool to send a message mid-work (before your final output). If you have one destination, `to` is optional; with multiple, specify it. Pace your updates to the length of the work:
|
||||
|
||||
- **Short work (a few seconds, ≤2 quick tool calls):** Don't narrate. Just do it and put the result in your final response.
|
||||
- **Longer work (many tool calls, web searches, installs, sub-agents):** Send a short acknowledgment right away ("On it — checking the logs now") so the user knows you got the message.
|
||||
- **Long-running work (many minutes, multi-step tasks):** Send periodic updates at natural milestones, and especially **before** slow operations like spinning up an explore sub-agent, downloading large files, or installing packages.
|
||||
|
||||
**Never narrate micro-steps.** "I'm going to read the file now… okay, I'm reading it… now I'm parsing it…" is noise. Updates should mark meaningful transitions, not every tool call.
|
||||
|
||||
**Outcomes, not play-by-play.** When the work is done, the final message should be about the result, not a transcript of what you did.
|
||||
|
||||
### Internal thoughts
|
||||
|
||||
Wrap reasoning in `<internal>...</internal>` tags to mark it as scratchpad — logged but not sent. With multiple destinations, any text outside of `<message>` blocks is also treated as scratchpad. With a single destination, only explicit `<internal>` tags are scratchpad; the rest of your response is sent.
|
||||
|
||||
```
|
||||
<internal>Compiled all three reports, ready to summarize.</internal>
|
||||
|
||||
Here are the key findings from the research…
|
||||
```
|
||||
|
||||
### Sub-agents and teammates
|
||||
|
||||
When working as a sub-agent or teammate, only use `send_message` if instructed to by the main agent.
|
||||
|
||||
## Your Workspace
|
||||
|
||||
Files you create are saved in `/workspace/group/`. Use this for notes, research, or anything that should persist.
|
||||
|
||||
## Memory
|
||||
|
||||
The `conversations/` folder contains searchable history of past conversations. Use this to recall context from previous sessions.
|
||||
|
||||
When you learn something important:
|
||||
- Create files for structured data (e.g., `customers.md`, `preferences.md`)
|
||||
- Split files larger than 500 lines into folders
|
||||
- Keep an index in your memory for the files you create
|
||||
|
||||
## Message Formatting
|
||||
|
||||
Format messages based on the channel you're responding to. Check your group folder name:
|
||||
|
||||
### Slack channels (folder starts with `slack_`)
|
||||
|
||||
Use Slack mrkdwn syntax. Run `/slack-formatting` for the full reference. Key rules:
|
||||
- `*bold*` (single asterisks)
|
||||
- `_italic_` (underscores)
|
||||
- `<https://url|link text>` for links (NOT `[text](url)`)
|
||||
- `•` bullets (no numbered lists)
|
||||
- `:emoji:` shortcodes
|
||||
- `>` for block quotes
|
||||
- No `##` headings — use `*Bold text*` instead
|
||||
|
||||
### WhatsApp/Telegram channels (folder starts with `whatsapp_` or `telegram_`)
|
||||
|
||||
- `*bold*` (single asterisks, NEVER **double**)
|
||||
- `_italic_` (underscores)
|
||||
- `•` bullet points
|
||||
- ` ``` ` code blocks
|
||||
|
||||
No `##` headings. No `[links](url)`. No `**double stars**`.
|
||||
|
||||
### Discord channels (folder starts with `discord_`)
|
||||
|
||||
Standard Markdown works: `**bold**`, `*italic*`, `[links](url)`, `# headings`.
|
||||
|
||||
---
|
||||
|
||||
## Installing Packages & Tools
|
||||
|
||||
Your container is ephemeral — anything installed via `apt-get` or `pnpm install -g` is lost on restart. To install packages that persist, use the self-modification tools:
|
||||
|
||||
1. **`install_packages`** — request system (apt) or global npm packages. Requires admin approval.
|
||||
2. **`request_rebuild`** — rebuild your container image so approved packages are baked in. Always call this after `install_packages` to apply the changes.
|
||||
|
||||
Example flow:
|
||||
```
|
||||
install_packages({ apt: ["ffmpeg"], npm: ["@xenova/transformers"], reason: "Audio transcription" })
|
||||
# → Admin gets an approval card → approves
|
||||
request_rebuild({ reason: "Apply ffmpeg + transformers" })
|
||||
# → Admin approves → image rebuilt with the packages
|
||||
```
|
||||
|
||||
**When to use this vs workspace pnpm install:**
|
||||
- `pnpm install` in `/workspace/agent/` persists on disk (it's mounted) but isn't on the global PATH — use it for project-level dependencies
|
||||
- `install_packages` is for system tools (ffmpeg, imagemagick) and global npm packages that need to be on PATH
|
||||
|
||||
### MCP Servers
|
||||
|
||||
Use **`add_mcp_server`** to add an MCP server to your configuration, then **`request_rebuild`** to apply. Browse available servers at https://mcp.so — it's a curated directory of high-quality MCP servers. Most Node.js servers run via `pnpm dlx`, e.g.:
|
||||
|
||||
```
|
||||
add_mcp_server({ name: "memory", command: "pnpm", args: ["dlx", "@modelcontextprotocol/server-memory"] })
|
||||
request_rebuild({ reason: "Add memory MCP server" })
|
||||
```
|
||||
|
||||
## Task Scripts
|
||||
|
||||
For any recurring task, use `schedule_task`. This is the scheduling path — tasks persist across sessions and restarts, and support the pre-task `script` hook described below. Other scheduling tools you might discover (e.g. `CronCreate`, `ScheduleWakeup`) are session-scoped SDK builtins and won't behave the way NanoClaw users expect, so stick with `schedule_task`.
|
||||
|
||||
To inspect or change existing tasks, use `list_tasks` (returns one row per series with the stable id) and `update_task` / `cancel_task` / `pause_task` / `resume_task`. Prefer `update_task` over cancel + reschedule — it preserves the series id the user already knows.
|
||||
|
||||
Frequent agent invocations — especially multiple times a day — consume API credits and can risk account restrictions. If a simple check can determine whether action is needed, add a `script` — it runs first, and the agent is only called when the check passes. This keeps invocations to a minimum.
|
||||
|
||||
### How it works
|
||||
|
||||
1. You provide a bash `script` alongside the `prompt` when scheduling
|
||||
2. When the task fires, the script runs first (30-second timeout)
|
||||
3. Script prints JSON to stdout: `{ "wakeAgent": true/false, "data": {...} }`
|
||||
4. If `wakeAgent: false` — nothing happens, task waits for next run
|
||||
5. If `wakeAgent: true` — you wake up and receive the script's data + prompt
|
||||
|
||||
### Always test your script first
|
||||
|
||||
Before scheduling, run the script in your sandbox to verify it works:
|
||||
|
||||
```bash
|
||||
bash -c 'node --input-type=module -e "
|
||||
const r = await fetch(\"https://api.github.com/repos/owner/repo/pulls?state=open\");
|
||||
const prs = await r.json();
|
||||
console.log(JSON.stringify({ wakeAgent: prs.length > 0, data: prs.slice(0, 5) }));
|
||||
"'
|
||||
```
|
||||
|
||||
### When NOT to use scripts
|
||||
|
||||
If a task requires your judgment every time (daily briefings, reminders, reports), skip the script — just use a regular prompt.
|
||||
|
||||
### Frequent task guidance
|
||||
|
||||
If a user wants tasks running more than ~2x daily and a script can't reduce agent wake-ups:
|
||||
|
||||
- Explain that each wake-up uses API credits and risks rate limits
|
||||
- Suggest restructuring with a script that checks the condition first
|
||||
- If the user needs an LLM to evaluate data, suggest using an API key with direct Anthropic API calls inside the script
|
||||
- Help the user find the minimum viable frequency
|
||||
@@ -0,0 +1,312 @@
|
||||
@./.claude-global.md
|
||||
# Main
|
||||
|
||||
You are Main, a personal assistant. You help with tasks, answer questions, and can schedule reminders.
|
||||
|
||||
## What You Can Do
|
||||
|
||||
- Answer questions and have conversations
|
||||
- Search the web and fetch content from URLs
|
||||
- **Browse the web** with `agent-browser` — open pages, click, fill forms, take screenshots, extract data (run `agent-browser open <url>` to start, then `agent-browser snapshot -i` to see interactive elements)
|
||||
- Read and write files in your workspace
|
||||
- Run bash commands in your sandbox
|
||||
- Schedule tasks to run later or on a recurring basis
|
||||
- Send messages back to the chat
|
||||
|
||||
## Communication
|
||||
|
||||
Your output is sent to the user or group.
|
||||
|
||||
You also have `mcp__nanoclaw__send_message` which sends a message immediately while you're still working. This is useful when you want to acknowledge a request before starting longer work.
|
||||
|
||||
### Internal thoughts
|
||||
|
||||
If part of your output is internal reasoning rather than something for the user, wrap it in `<internal>` tags:
|
||||
|
||||
```
|
||||
<internal>Compiled all three reports, ready to summarize.</internal>
|
||||
|
||||
Here are the key findings from the research...
|
||||
```
|
||||
|
||||
Text inside `<internal>` tags is logged but not sent to the user. If you've already sent the key information via `send_message`, you can wrap the recap in `<internal>` to avoid sending it again.
|
||||
|
||||
### Sub-agents and teammates
|
||||
|
||||
When working as a sub-agent or teammate, only use `send_message` if instructed to by the main agent.
|
||||
|
||||
## Memory
|
||||
|
||||
The `conversations/` folder contains searchable history of past conversations. Use this to recall context from previous sessions.
|
||||
|
||||
When you learn something important:
|
||||
- Create files for structured data (e.g., `customers.md`, `preferences.md`)
|
||||
- Split files larger than 500 lines into folders
|
||||
- Keep an index in your memory for the files you create
|
||||
|
||||
## Message Formatting
|
||||
|
||||
Format messages based on the channel. Check the group folder name prefix:
|
||||
|
||||
### Slack channels (folder starts with `slack_`)
|
||||
|
||||
Use Slack mrkdwn syntax. Run `/slack-formatting` for the full reference. Key rules:
|
||||
- `*bold*` (single asterisks)
|
||||
- `_italic_` (underscores)
|
||||
- `<https://url|link text>` for links (NOT `[text](url)`)
|
||||
- `•` bullets (no numbered lists)
|
||||
- `:emoji:` shortcodes like `:white_check_mark:`, `:rocket:`
|
||||
- `>` for block quotes
|
||||
- No `##` headings — use `*Bold text*` instead
|
||||
|
||||
### WhatsApp/Telegram (folder starts with `whatsapp_` or `telegram_`)
|
||||
|
||||
- `*bold*` (single asterisks, NEVER **double**)
|
||||
- `_italic_` (underscores)
|
||||
- `•` bullet points
|
||||
- ` ``` ` code blocks
|
||||
|
||||
No `##` headings. No `[links](url)`. No `**double stars**`.
|
||||
|
||||
### Discord (folder starts with `discord_`)
|
||||
|
||||
Standard Markdown: `**bold**`, `*italic*`, `[links](url)`, `# headings`.
|
||||
|
||||
---
|
||||
|
||||
## Admin Context
|
||||
|
||||
This is the **main channel**, which has elevated privileges.
|
||||
|
||||
## Authentication
|
||||
|
||||
Anthropic credentials must be either an API key from console.anthropic.com (`ANTHROPIC_API_KEY`) or a long-lived OAuth token from `claude setup-token` (`CLAUDE_CODE_OAUTH_TOKEN`). Short-lived tokens from the system keychain or `~/.claude/.credentials.json` expire within hours and can cause recurring container 401s. The `/setup` skill walks through this. OneCLI manages credentials (including Anthropic auth) — run `onecli --help`.
|
||||
|
||||
## Container Mounts
|
||||
|
||||
Main has read-only access to the project, read-write access to the store (SQLite DB), and read-write access to its group folder:
|
||||
|
||||
| Container Path | Host Path | Access |
|
||||
|----------------|-----------|--------|
|
||||
| `/workspace/project` | Project root | read-only |
|
||||
| `/workspace/project/store` | `store/` | read-write |
|
||||
| `/workspace/group` | `groups/main/` | read-write |
|
||||
|
||||
Key paths inside the container:
|
||||
- `/workspace/project/store/messages.db` - SQLite database (read-write)
|
||||
- `/workspace/project/store/messages.db` (registered_groups table) - Group config
|
||||
- `/workspace/project/groups/` - All group folders
|
||||
|
||||
---
|
||||
|
||||
## Managing Groups
|
||||
|
||||
### Finding Available Groups
|
||||
|
||||
Available groups are provided in `/workspace/ipc/available_groups.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"groups": [
|
||||
{
|
||||
"jid": "120363336345536173@g.us",
|
||||
"name": "Family Chat",
|
||||
"lastActivity": "2026-01-31T12:00:00.000Z",
|
||||
"isRegistered": false
|
||||
}
|
||||
],
|
||||
"lastSync": "2026-01-31T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
Groups are ordered by most recent activity. The list is synced from WhatsApp daily.
|
||||
|
||||
If a group the user mentions isn't in the list, request a fresh sync:
|
||||
|
||||
```bash
|
||||
echo '{"type": "refresh_groups"}' > /workspace/ipc/tasks/refresh_$(date +%s).json
|
||||
```
|
||||
|
||||
Then wait a moment and re-read `available_groups.json`.
|
||||
|
||||
**Fallback**: Query the SQLite database directly:
|
||||
|
||||
```bash
|
||||
sqlite3 /workspace/project/store/messages.db "
|
||||
SELECT jid, name, last_message_time
|
||||
FROM chats
|
||||
WHERE jid LIKE '%@g.us' AND jid != '__group_sync__'
|
||||
ORDER BY last_message_time DESC
|
||||
LIMIT 10;
|
||||
"
|
||||
```
|
||||
|
||||
### Registered Groups Config
|
||||
|
||||
Groups are registered in the SQLite `registered_groups` table:
|
||||
|
||||
```json
|
||||
{
|
||||
"1234567890-1234567890@g.us": {
|
||||
"name": "Family Chat",
|
||||
"folder": "whatsapp_family-chat",
|
||||
"trigger": "@Andy",
|
||||
"added_at": "2024-01-31T12:00:00.000Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
- **Key**: The chat JID (unique identifier — WhatsApp, Telegram, Slack, Discord, etc.)
|
||||
- **name**: Display name for the group
|
||||
- **folder**: Channel-prefixed folder name under `groups/` for this group's files and memory
|
||||
- **trigger**: The trigger word (usually same as global, but could differ)
|
||||
- **requiresTrigger**: Whether `@trigger` prefix is needed (default: `true`). Set to `false` for solo/personal chats where all messages should be processed
|
||||
- **isMain**: Whether this is the main control group (elevated privileges, no trigger required)
|
||||
- **added_at**: ISO timestamp when registered
|
||||
|
||||
### Trigger Behavior
|
||||
|
||||
- **Main group** (`isMain: true`): No trigger needed — all messages are processed automatically
|
||||
- **Groups with `requiresTrigger: false`**: No trigger needed — all messages processed (use for 1-on-1 or solo chats)
|
||||
- **Other groups** (default): Messages must start with `@AssistantName` to be processed
|
||||
|
||||
### Adding a Group
|
||||
|
||||
1. Query the database to find the group's JID
|
||||
2. Ask the user whether the group should require a trigger word before registering
|
||||
3. Use the `register_group` MCP tool with the JID, name, folder, trigger, and the chosen `requiresTrigger` setting
|
||||
4. Optionally include `containerConfig` for additional mounts
|
||||
5. The group folder is created automatically: `/workspace/project/groups/{folder-name}/`
|
||||
6. Optionally create an initial `CLAUDE.md` for the group
|
||||
|
||||
Folder naming convention — channel prefix with underscore separator:
|
||||
- WhatsApp "Family Chat" → `whatsapp_family-chat`
|
||||
- Telegram "Dev Team" → `telegram_dev-team`
|
||||
- Discord "General" → `discord_general`
|
||||
- Slack "Engineering" → `slack_engineering`
|
||||
- Use lowercase, hyphens for the group name part
|
||||
|
||||
#### Adding Additional Directories for a Group
|
||||
|
||||
Groups can have extra directories mounted. Add `containerConfig` to their entry:
|
||||
|
||||
```json
|
||||
{
|
||||
"1234567890@g.us": {
|
||||
"name": "Dev Team",
|
||||
"folder": "dev-team",
|
||||
"trigger": "@Andy",
|
||||
"added_at": "2026-01-31T12:00:00Z",
|
||||
"containerConfig": {
|
||||
"additionalMounts": [
|
||||
{
|
||||
"hostPath": "~/projects/webapp",
|
||||
"containerPath": "webapp",
|
||||
"readonly": false
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The directory will appear at `/workspace/extra/webapp` in that group's container.
|
||||
|
||||
#### Sender Allowlist
|
||||
|
||||
After registering a group, explain the sender allowlist feature to the user:
|
||||
|
||||
> This group can be configured with a sender allowlist to control who can interact with me. There are two modes:
|
||||
>
|
||||
> - **Trigger mode** (default): Everyone's messages are stored for context, but only allowed senders can trigger me with @{AssistantName}.
|
||||
> - **Drop mode**: Messages from non-allowed senders are not stored at all.
|
||||
>
|
||||
> For closed groups with trusted members, I recommend setting up an allow-only list so only specific people can trigger me. Want me to configure that?
|
||||
|
||||
If the user wants to set up an allowlist, edit `~/.config/nanoclaw/sender-allowlist.json` on the host:
|
||||
|
||||
```json
|
||||
{
|
||||
"default": { "allow": "*", "mode": "trigger" },
|
||||
"chats": {
|
||||
"<chat-jid>": {
|
||||
"allow": ["sender-id-1", "sender-id-2"],
|
||||
"mode": "trigger"
|
||||
}
|
||||
},
|
||||
"logDenied": true
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Your own messages (`is_from_me`) explicitly bypass the allowlist in trigger checks. Bot messages are filtered out by the database query before trigger evaluation, so they never reach the allowlist.
|
||||
- If the config file doesn't exist or is invalid, all senders are allowed (fail-open)
|
||||
- The config file is on the host at `~/.config/nanoclaw/sender-allowlist.json`, not inside the container
|
||||
|
||||
### Removing a Group
|
||||
|
||||
1. Read `/workspace/project/data/registered_groups.json`
|
||||
2. Remove the entry for that group
|
||||
3. Write the updated JSON back
|
||||
4. The group folder and its files remain (don't delete them)
|
||||
|
||||
### Listing Groups
|
||||
|
||||
Read `/workspace/project/data/registered_groups.json` and format it nicely.
|
||||
|
||||
---
|
||||
|
||||
## Global Memory
|
||||
|
||||
You can read and write to `/workspace/global/CLAUDE.md` for facts that should apply to all groups. Only update global memory when explicitly asked to "remember this globally" or similar.
|
||||
|
||||
---
|
||||
|
||||
## Scheduling for Other Groups
|
||||
|
||||
When scheduling tasks for other groups, use the `target_group_jid` parameter with the group's JID from `registered_groups.json`:
|
||||
- `schedule_task(prompt: "...", schedule_type: "cron", schedule_value: "0 9 * * 1", target_group_jid: "120363336345536173@g.us")`
|
||||
|
||||
The task will run in that group's context with access to their files and memory.
|
||||
|
||||
---
|
||||
|
||||
## Task Scripts
|
||||
|
||||
For any recurring task, use `schedule_task`. Frequent agent invocations — especially multiple times a day — consume API credits and can risk account restrictions. If a simple check can determine whether action is needed, add a `script` — it runs first, and the agent is only called when the check passes. This keeps invocations to a minimum.
|
||||
|
||||
Use `list_tasks` to see existing tasks (one row per series with the stable id), and `update_task` / `cancel_task` / `pause_task` / `resume_task` to modify them. Prefer `update_task` over cancel + reschedule when adjusting an existing task.
|
||||
|
||||
### How it works
|
||||
|
||||
1. You provide a bash `script` alongside the `prompt` when scheduling
|
||||
2. When the task fires, the script runs first (30-second timeout)
|
||||
3. Script prints JSON to stdout: `{ "wakeAgent": true/false, "data": {...} }`
|
||||
4. If `wakeAgent: false` — nothing happens, task waits for next run
|
||||
5. If `wakeAgent: true` — you wake up and receive the script's data + prompt
|
||||
|
||||
### Always test your script first
|
||||
|
||||
Before scheduling, run the script in your sandbox to verify it works:
|
||||
|
||||
```bash
|
||||
bash -c 'node --input-type=module -e "
|
||||
const r = await fetch(\"https://api.github.com/repos/owner/repo/pulls?state=open\");
|
||||
const prs = await r.json();
|
||||
console.log(JSON.stringify({ wakeAgent: prs.length > 0, data: prs.slice(0, 5) }));
|
||||
"'
|
||||
```
|
||||
|
||||
### When NOT to use scripts
|
||||
|
||||
If a task requires your judgment every time (daily briefings, reminders, reports), skip the script — just use a regular prompt.
|
||||
|
||||
### Frequent task guidance
|
||||
|
||||
If a user wants tasks running more than ~2x daily and a script can't reduce agent wake-ups:
|
||||
|
||||
- Explain that each wake-up uses API credits and risks rate limits
|
||||
- Suggest restructuring with a script that checks the condition first
|
||||
- If the user needs an LLM to evaluate data, suggest using an API key with direct Anthropic API calls inside the script
|
||||
- Help the user find the minimum viable frequency
|
||||
+2
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "nanoclaw",
|
||||
"version": "2.1.38",
|
||||
"version": "2.1.24",
|
||||
"description": "Personal Claude assistant. Lightweight, secure, customizable.",
|
||||
"type": "module",
|
||||
"packageManager": "pnpm@10.33.0",
|
||||
@@ -21,6 +21,7 @@
|
||||
"setup:auto": "tsx setup/auto.ts",
|
||||
"ncl": "tsx src/cli/client.ts",
|
||||
"chat": "tsx scripts/chat.ts",
|
||||
"auth": "tsx src/whatsapp-auth.ts",
|
||||
"lint": "eslint src/",
|
||||
"lint:fix": "eslint src/ --fix",
|
||||
"test": "vitest run",
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="90" height="20" role="img" aria-label="208k tokens, 104% of context window">
|
||||
<title>208k tokens, 104% of context window</title>
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="90" height="20" role="img" aria-label="204k tokens, 102% of context window">
|
||||
<title>204k tokens, 102% of context window</title>
|
||||
<linearGradient id="s" x2="0" y2="100%">
|
||||
<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
|
||||
<stop offset="1" stop-opacity=".1"/>
|
||||
@@ -15,8 +15,8 @@
|
||||
<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
|
||||
<text aria-hidden="true" x="26" y="15" fill="#010101" fill-opacity=".3">tokens</text>
|
||||
<text x="26" y="14">tokens</text>
|
||||
<text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">208k</text>
|
||||
<text x="71" y="14">208k</text>
|
||||
<text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">204k</text>
|
||||
<text x="71" y="14">204k</text>
|
||||
</g>
|
||||
</g>
|
||||
</a>
|
||||
|
||||
|
Before Width: | Height: | Size: 1.1 KiB After Width: | Height: | Size: 1.1 KiB |
File diff suppressed because it is too large
Load Diff
@@ -1,876 +0,0 @@
|
||||
// The skill application engine — executes `nc:` directives parsed from a SKILL.md.
|
||||
//
|
||||
// The agent is always the top-level applier; this engine is the deterministic
|
||||
// accelerator it delegates to. Anything the engine can't do bounces back to the
|
||||
// AGENT (which reads the same prose and applies it, the way skills work today) —
|
||||
// never to the human, and never as a hard abort. The human is in the loop only
|
||||
// for `prompt` inputs and `operator` instructions — the parts addressed to the
|
||||
// human (e.g. clicking through the Slack UI), which the agent relays.
|
||||
//
|
||||
// Phases (the F2 runtime contract, minimal form):
|
||||
// 1. parse + validate — lint; a malformed skill never reaches apply
|
||||
// 2. PLAN — per directive: skip|apply|needs-input|agent — no writes
|
||||
// 3. acquire inputs — resolve every `prompt` via `inputs` / `resolveInput`
|
||||
// 4. mutate — copy/append/env-set, journaled + idempotent
|
||||
// 5. run — build/test/fetch (+ dep install) via injected exec
|
||||
// Remove is derived from the journal — no hand-written REMOVE.md.
|
||||
//
|
||||
// Inputs + `resolveInput` make one engine serve three contexts:
|
||||
// • programmatic → pass `inputs` (var→value); no resolver, runs through fully
|
||||
// • setup flow → an interactive `resolveInput` collects anything left
|
||||
// • recipe rebuild → headless: no answer for a prompt ⇒ it (and its consumers) defer
|
||||
//
|
||||
// Usage: pnpm exec tsx scripts/skill-apply.ts <skillDir> # plan (no writes)
|
||||
|
||||
import { execSync } from 'node:child_process';
|
||||
import { readFileSync, existsSync, writeFileSync, appendFileSync, copyFileSync, mkdirSync, rmSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { parseDirectives, promptVar, type Directive } from './skill-directives.js';
|
||||
|
||||
// What an `nc:prompt` DECLARES about the value it needs — the core seam's input
|
||||
// contract, passed to `resolveInput` so a consumer can run its OWN re-ask loop
|
||||
// (clack validate, a chat exchange). Declaration only: how the value is
|
||||
// ACQUIRED (a masked TTY prompt, a chat message) is the consumer's business.
|
||||
export interface InputMeta {
|
||||
question: string; // the prompt body (verbatim)
|
||||
secret: boolean; // consumer must mask
|
||||
validate?: string; // regex source (nc:prompt validate:<re>)
|
||||
flags?: string; // regex flags (nc:prompt flags:<f>)
|
||||
normalize?: 'trim' | 'rstrip-slash' | 'lower'; // applied by the ENGINE at bind
|
||||
}
|
||||
|
||||
// Everything the engine EMITS — the core seam's output contract. Every
|
||||
// `onEvent` call is AWAITED before the engine proceeds; that ordering guarantee
|
||||
// is what lets a consumer implement gating (hold the operator event until the
|
||||
// human confirms readiness). For step events, `label` is `stepLabel`'s
|
||||
// declaration: null means the step is instant/cheap, OR it renders its own live
|
||||
// operator-facing output (an `effect:step` QR card / pairing code) — a
|
||||
// step-cost/interactivity declaration, not render advice; the event carries
|
||||
// `kind` + `line`, so a consumer wanting a different render policy can derive
|
||||
// its own.
|
||||
export type ApplyEvent =
|
||||
| { type: 'step-start'; kind: string; line: number; label: string | null }
|
||||
| { type: 'step-end'; kind: string; line: number; label: string | null; ok: boolean; durationMs: number; error?: string }
|
||||
| { type: 'operator'; line: number; text: string };
|
||||
// operator: text = the rendered, {{var}}-substituted block body;
|
||||
// line = the directive's opening-fence line (keys driver policy maps)
|
||||
|
||||
// The result of a streaming `nc:run effect:step`: the spawn's exit success plus
|
||||
// the terminal status block's fields, which `capture:<var>=<FIELD>` binds.
|
||||
export interface StepOutcome {
|
||||
ok: boolean;
|
||||
fields: Record<string, string>;
|
||||
}
|
||||
|
||||
export type StepStatus = 'skip' | 'apply' | 'needs-input' | 'agent';
|
||||
export interface PlanStep {
|
||||
n: number;
|
||||
kind: string;
|
||||
line: number;
|
||||
status: StepStatus;
|
||||
detail: string;
|
||||
}
|
||||
|
||||
const read = (p: string) => (existsSync(p) ? readFileSync(p, 'utf8') : '');
|
||||
const has = (root: string, rel: string) => existsSync(join(root, rel));
|
||||
const VAR_REF = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
|
||||
const destOf = (line: string) => (line.includes('->') ? line.split('->')[1].trim() : line.trim());
|
||||
const srcOf = (line: string) => (line.includes('->') ? line.split('->')[0].trim() : line.trim());
|
||||
|
||||
function fileHasLine(root: string, rel: string, line: string): boolean {
|
||||
return read(join(root, rel))
|
||||
.split('\n')
|
||||
.some((l) => l.trim() === line.trim());
|
||||
}
|
||||
function pkgHasDep(root: string, name: string): boolean {
|
||||
try {
|
||||
const pkg = JSON.parse(read(join(root, 'package.json')) || '{}');
|
||||
return Boolean(pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
function envKeySet(root: string, key: string): boolean {
|
||||
return read(join(root, '.env'))
|
||||
.split('\n')
|
||||
.some((l) => {
|
||||
const m = l.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/);
|
||||
return m !== null && m[1] === key && m[2].trim().length > 0;
|
||||
});
|
||||
}
|
||||
// Does the array-of-objects JSON at `rel` already contain an element whose
|
||||
// [key] equals `value`? The idempotency probe for json-merge.
|
||||
function jsonArrayHasKey(root: string, rel: string, key: string, value: unknown): boolean {
|
||||
try {
|
||||
const arr = JSON.parse(read(join(root, rel)) || '[]');
|
||||
return Array.isArray(arr) && arr.some((el) => el !== null && typeof el === 'object' && (el as Record<string, unknown>)[key] === value);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// Per-directive idempotency check + "what it would do". Read-only.
|
||||
function selfStatus(d: Directive, root: string): { status: StepStatus; detail: string } {
|
||||
switch (d.kind) {
|
||||
case 'copy': {
|
||||
const dests = d.body.map(destOf);
|
||||
const missing = dests.filter((p) => !has(root, p));
|
||||
const from = d.attrs['from-branch'] ? `fetch ${String(d.attrs['from-branch'])} → ` : '';
|
||||
return missing.length
|
||||
? { status: 'apply', detail: `${from}copy ${missing.join(', ')} (absent)` }
|
||||
: { status: 'skip', detail: `${dests.join(', ')} present` };
|
||||
}
|
||||
case 'append': {
|
||||
const to = String(d.attrs.to ?? '');
|
||||
const line = d.body[0] ?? '';
|
||||
return fileHasLine(root, to, line)
|
||||
? { status: 'skip', detail: `${to} already has the line` }
|
||||
: { status: 'apply', detail: `add to ${to}: ${line}` };
|
||||
}
|
||||
case 'dep': {
|
||||
const missing = d.body.filter((s) => !pkgHasDep(root, s.slice(0, s.lastIndexOf('@'))));
|
||||
return missing.length
|
||||
? { status: 'apply', detail: `install ${missing.join(', ')}` }
|
||||
: { status: 'skip', detail: `${d.body.join(', ')} present` };
|
||||
}
|
||||
case 'run':
|
||||
return { status: 'apply', detail: `${String(d.attrs.effect ?? 'run')}: ${d.body.join(' && ')}` };
|
||||
case 'env-set': {
|
||||
const keys = d.body.map((l) => l.split('=')[0].trim());
|
||||
const missing = keys.filter((k) => !envKeySet(root, k));
|
||||
return missing.length
|
||||
? { status: 'apply', detail: `set ${missing.join(', ')} in .env` }
|
||||
: { status: 'skip', detail: `${keys.join(', ')} already set` };
|
||||
}
|
||||
case 'json-merge': {
|
||||
const into = String(d.attrs.into ?? '');
|
||||
const key = String(d.attrs.key ?? '');
|
||||
let value: unknown;
|
||||
try {
|
||||
value = (JSON.parse(d.body.join('\n')) as Record<string, unknown>)[key];
|
||||
} catch {
|
||||
return { status: 'agent', detail: `nc:json-merge body is not parseable JSON — an agent applies it from the prose` };
|
||||
}
|
||||
return jsonArrayHasKey(root, into, key, value)
|
||||
? { status: 'skip', detail: `${into} already has ${key}=${JSON.stringify(value)}` }
|
||||
: { status: 'apply', detail: `merge ${key}=${JSON.stringify(value)} into ${into}` };
|
||||
}
|
||||
case 'prompt':
|
||||
return { status: 'needs-input', detail: '' };
|
||||
case 'operator':
|
||||
return { status: 'apply', detail: `show operator: ${(d.body[0] ?? '').slice(0, 50)}…` };
|
||||
default:
|
||||
return { status: 'agent', detail: `no deterministic handler for nc:${d.kind} — an agent applies it from the prose` };
|
||||
}
|
||||
}
|
||||
|
||||
export function planSkill(skillDir: string, root: string): { steps: PlanStep[]; needsInput: string[]; agentSteps: number } {
|
||||
const directives = parseDirectives(read(join(skillDir, 'SKILL.md')));
|
||||
const self = directives.map((d) => ({ d, ...selfStatus(d, root) }));
|
||||
|
||||
const consumers = new Map<string, number[]>();
|
||||
self.forEach(({ d }, i) => {
|
||||
for (const line of d.body) for (const m of line.matchAll(VAR_REF)) (consumers.get(m[1]) ?? consumers.set(m[1], []).get(m[1])!).push(i);
|
||||
});
|
||||
|
||||
const steps: PlanStep[] = self.map(({ d, status, detail }, i) => {
|
||||
if (d.kind !== 'prompt') return { n: i + 1, kind: d.kind, line: d.line, status, detail };
|
||||
const v = promptVar(d) ?? '?';
|
||||
const tag = `${v}${d.args.includes('secret') ? ' (secret)' : ''}`;
|
||||
const cons = consumers.get(v) ?? [];
|
||||
const satisfied = cons.length > 0 && cons.every((j) => self[j].status === 'skip');
|
||||
return satisfied
|
||||
? { n: i + 1, kind: d.kind, line: d.line, status: 'skip', detail: `${tag} — consumers already satisfied` }
|
||||
: { n: i + 1, kind: d.kind, line: d.line, status: 'needs-input', detail: `${tag} → asked during apply` };
|
||||
});
|
||||
|
||||
return {
|
||||
steps,
|
||||
needsInput: steps.filter((s) => s.status === 'needs-input').map((s) => s.detail.split(' ')[0]),
|
||||
agentSteps: steps.filter((s) => s.status === 'agent').length,
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Apply (phases 3–5) + journal-derived remove.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type JournalEntry =
|
||||
| { op: 'wrote'; path: string }
|
||||
| { op: 'appended'; path: string; line: string }
|
||||
| { op: 'set-env'; key: string }
|
||||
| { op: 'json-merge'; path: string; key: string; value: unknown }
|
||||
| { op: 'ran'; cmd: string; undo?: string };
|
||||
|
||||
export interface AgentTask {
|
||||
kind: string;
|
||||
line: number;
|
||||
reason: string;
|
||||
prose: string; // the surrounding prose the agent reads to apply the step
|
||||
}
|
||||
|
||||
export interface ApplyResult {
|
||||
applied: string[];
|
||||
skipped: string[];
|
||||
deferred: string[]; // prompt vars / blocked consumers with no value yet
|
||||
agentTasks: AgentTask[]; // bounced to an agent — NOT the human
|
||||
operatorMessages: string[]; // `nc:operator` bodies to relay to the human operator
|
||||
// Non-secret resolved values (prompt answers + `run capture:<var>` outputs) so
|
||||
// a caller can read what the skill produced — e.g. a channel skill resolves
|
||||
// `owner_handle` + `platform_id`, the setup flow reads them to wire the agent.
|
||||
vars: Record<string, string>;
|
||||
journal: JournalEntry[];
|
||||
// The skill's author-written REFERENCE floor — its `## Alternatives`,
|
||||
// `## Optional configuration`, and `## Troubleshooting` sections, sliced
|
||||
// verbatim from the RAW markdown (see `referenceProse`). The driver surfaces
|
||||
// this beside the agentTasks on a bounce: the same prose a human reader would
|
||||
// scroll to when a step doesn't apply cleanly. Sliced on the author headings,
|
||||
// never the resolved {{var}} map, so a resolved {{secret}} can never leak in.
|
||||
referenceProse: string;
|
||||
}
|
||||
|
||||
export interface ApplyOptions {
|
||||
// Pre-supplied answers for `prompt` vars (var name → value). Checked FIRST, so
|
||||
// a caller that has every answer needs no resolver at all and the whole skill
|
||||
// runs through with no human interaction (fully programmatic apply).
|
||||
inputs?: Record<string, string>;
|
||||
// The core input seam: resolve a prompt var the caller didn't pre-supply.
|
||||
// `meta` carries the declared semantics (question, secret,
|
||||
// validate/flags/normalize) so a consumer can run its OWN re-ask loop.
|
||||
// Returning undefined ⇒ defer. Optional — omit it (with full `inputs`) for a
|
||||
// headless run; a prompt with neither defers.
|
||||
resolveInput?: (name: string, meta: InputMeta) => Promise<string | undefined>;
|
||||
// The core output seam: every engine emission — the step-start/step-end
|
||||
// brackets and each rendered `nc:operator` block — flows through this one
|
||||
// handler, and every call is AWAITED before the engine proceeds (that
|
||||
// ordering is what lets a consumer gate on an operator block). A rejection is
|
||||
// treated like any other throw at that directive: bounce, never crash — a
|
||||
// consumer that throws on an operator event accepts the bounce consequence,
|
||||
// including the `blocked` latch cascading over later side effects. Absent ⇒
|
||||
// silent; the headless/programmatic apply runs identically.
|
||||
onEvent?: (e: ApplyEvent) => void | Promise<void>;
|
||||
// dep/run/branch-fetch; injectable for tests. Returns the command's stdout so
|
||||
// a `run capture:<var>` can bind it into a {{var}} (the twin of `prompt`).
|
||||
exec?: (cmd: string) => string | void | Promise<string | void>;
|
||||
// Streaming exec for `nc:run effect:step`: spawns a long-running, operator-
|
||||
// interactive step (a pairing code, a QR device-link) that emits
|
||||
// `=== NANOCLAW SETUP: … ===` status blocks, renders them to the operator live,
|
||||
// and resolves with the terminal block's fields (bound via capture:<var>=<FIELD>).
|
||||
// Absent ⇒ a step directive degrades to an agent (runs the step from the prose).
|
||||
execStream?: (cmd: string) => Promise<StepOutcome>;
|
||||
// Run effects the CALLER owns and will perform itself — those runs are skipped
|
||||
// (not executed). e.g. a headless rebuild or a setup that restarts once at the
|
||||
// end passes ['restart']; applyProviderSkill passes ['build','test'].
|
||||
skipEffects?: string[];
|
||||
// Resolve which remote carries a `from-branch` registry branch. Defaults to a
|
||||
// generic resolver (env override → first remote that has the branch → origin);
|
||||
// setup injects one that reuses setup/lib/channels-remote.sh for exact parity.
|
||||
resolveRemote?: (branch: string) => string;
|
||||
}
|
||||
|
||||
/**
|
||||
* True when a skill applied completely — nothing deferred for a missing input and
|
||||
* nothing bounced to an agent. The check a programmatic caller makes to confirm a
|
||||
* fully-headless run-through succeeded.
|
||||
*/
|
||||
export function fullyApplied(res: ApplyResult): boolean {
|
||||
return res.deferred.length === 0 && res.agentTasks.length === 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* The failure diagnosis for the FIRST directive that bounced to an agent, in
|
||||
* document order: a concise headline (the nearest section heading) plus the
|
||||
* bounced step's own prose as the hint. The setup driver surfaces this when a
|
||||
* channel skill doesn't fully apply — the prose beside the step that failed
|
||||
* becomes the operator's failure hint and the Claude-handoff context, instead
|
||||
* of a generic "couldn't finish" message. Returns undefined when nothing
|
||||
* bounced (e.g. a headless rebuild only left prompts deferred — not a failure).
|
||||
*/
|
||||
export function firstFailureHint(res: ApplyResult): { headline: string; hint: string } | undefined {
|
||||
const first = res.agentTasks[0];
|
||||
if (!first) return undefined;
|
||||
const hint = first.prose.trim();
|
||||
// The concise headline: the nearest `#`-heading the prose carries, stripped of
|
||||
// its markers; failing that, the first prose line; failing that, the reason.
|
||||
const lines = first.prose.split('\n').map((l) => l.trim()).filter(Boolean);
|
||||
const heading = lines.find((l) => l.startsWith('#'));
|
||||
const headline = heading ? heading.replace(/^#+\s*/, '').trim() : (lines[0] ?? first.reason);
|
||||
return { headline, hint };
|
||||
}
|
||||
|
||||
// The author-written REFERENCE sections the apply engine ignores entirely:
|
||||
// `## Alternatives`, `## Optional configuration`, `## Troubleshooting`. Matched
|
||||
// on the heading text (lowercased), level-2 only.
|
||||
const REFERENCE_HEADINGS = new Set(['alternatives', 'optional configuration', 'troubleshooting']);
|
||||
|
||||
/**
|
||||
* Slice a skill's reference floor out of its raw markdown — the
|
||||
* `## Alternatives` / `## Optional configuration` / `## Troubleshooting` sections
|
||||
* the engine never executes. This is the human floor a reader scrolls to (a
|
||||
* dedicated-number path, optional env knobs, dropped-symptom fixes); the driver
|
||||
* surfaces it beside the bounced agentTasks so the operator has the same
|
||||
* reference. Returned VERBATIM from the author text keyed on the headings — never
|
||||
* from the resolved {{var}} map — so a resolved {{secret}} can never leak into it
|
||||
* (a `{{token}}` placeholder, if a reference section ever wrote one, stays a
|
||||
* literal placeholder). Any stray `nc:` directive fence inside a section is
|
||||
* dropped: reference prose is plain bash/json/text only — an `nc:` block belongs
|
||||
* under Apply, never here. Fence state is tracked so a `# comment` line inside a
|
||||
* code block is never mistaken for a markdown heading that would end the slice.
|
||||
*/
|
||||
export function referenceProse(md: string): string {
|
||||
const sections: string[] = [];
|
||||
let cur: string[] | null = null; // lines of the section being collected, or null
|
||||
let fence: string | null = null; // open fence's info-string ('' for a bare fence), or null
|
||||
const keep = (line: string): void => {
|
||||
// Inside (or toggling) an `nc:` fence ⇒ drop; otherwise collect when capturing.
|
||||
if (cur && !(fence ?? '').startsWith('nc:')) cur.push(line);
|
||||
};
|
||||
for (const line of md.split('\n')) {
|
||||
if (line.startsWith('```')) {
|
||||
if (fence === null) {
|
||||
fence = line.slice(3).trim();
|
||||
keep(line);
|
||||
} else {
|
||||
keep(line); // closing fence — `fence` still holds the opening info-string
|
||||
fence = null;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (fence !== null) { keep(line); continue; } // fence body
|
||||
const h = line.match(/^(#{1,6})\s+(.*)$/);
|
||||
if (h) {
|
||||
const level = h[1].length;
|
||||
const text = h[2].trim().toLowerCase();
|
||||
if (level === 2 && REFERENCE_HEADINGS.has(text)) {
|
||||
if (cur) sections.push(cur.join('\n').trim());
|
||||
cur = [line]; // open a new reference section
|
||||
} else if (level <= 2) {
|
||||
if (cur) { sections.push(cur.join('\n').trim()); cur = null; } // a non-reference h1/h2 closes the slice
|
||||
} else if (cur) {
|
||||
cur.push(line); // a subsection (### …) inside a captured reference section
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (cur) cur.push(line);
|
||||
}
|
||||
if (cur) sections.push(cur.join('\n').trim());
|
||||
return sections.filter(Boolean).join('\n\n').trim();
|
||||
}
|
||||
|
||||
// A hardcoded `origin` breaks forks where the registry branch lives on
|
||||
// `upstream`. Generic mirror of channels-remote.sh: explicit override → the
|
||||
// first remote that actually has the branch → origin.
|
||||
function defaultResolveRemote(branch: string, root: string): string {
|
||||
const override = process.env.NANOCLAW_CHANNELS_REMOTE;
|
||||
if (override) return override;
|
||||
const cap = (cmd: string): string => {
|
||||
try {
|
||||
return execSync(cmd, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
};
|
||||
const remotes = cap('git remote').split('\n').map((s) => s.trim()).filter(Boolean);
|
||||
const ordered = remotes.includes('origin') ? ['origin', ...remotes.filter((r) => r !== 'origin')] : remotes;
|
||||
for (const r of ordered) if (cap(`git ls-remote --heads ${r} ${branch}`).trim()) return r;
|
||||
return 'origin';
|
||||
}
|
||||
|
||||
// The prose an agent reads when a step degrades: nearest heading + the
|
||||
// paragraph immediately above the directive fence.
|
||||
function proseFor(md: string, fenceLine1: number): string {
|
||||
const lines = md.split('\n');
|
||||
let i = fenceLine1 - 2;
|
||||
while (i >= 0 && lines[i].trim() === '') i--;
|
||||
const para: string[] = [];
|
||||
while (i >= 0 && lines[i].trim() !== '' && !lines[i].startsWith('#')) para.unshift(lines[i--]);
|
||||
let heading = '';
|
||||
for (let h = i; h >= 0; h--) if (lines[h].startsWith('#')) { heading = lines[h]; break; }
|
||||
return [heading, ...para].filter(Boolean).join('\n').trim();
|
||||
}
|
||||
|
||||
// The nearest `#`-prefixed heading above a fence (the same upward scan proseFor
|
||||
// uses), stripped of its leading `#`s — a concise caption for a step spinner.
|
||||
function headingAbove(md: string, fenceLine1: number): string {
|
||||
const lines = md.split('\n');
|
||||
for (let h = fenceLine1 - 2; h >= 0; h--) {
|
||||
if (lines[h].startsWith('#')) return lines[h].replace(/^#+\s*/, '').trim();
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
// The run effects worth a spinner — the slow, operator-waits-on-it ones.
|
||||
// `effect:step` is deliberately absent: it renders its own live operator output
|
||||
// (a QR card, a pairing code) that a concurrent spinner would clobber, so it
|
||||
// stays unlabelled (null) like the instant kinds.
|
||||
const SPIN_EFFECTS = new Set(['build', 'test', 'fetch', 'wire', 'restart', 'external']);
|
||||
|
||||
/**
|
||||
* The human caption a consumer may show for a step. `null` is a DECLARATION,
|
||||
* not render advice: the step is instant/cheap (a local file copy, an env
|
||||
* write, a json-merge), or it renders its own live operator-facing output
|
||||
* (`effect:step`'s QR card / pairing code) — the step event still carries
|
||||
* `kind` + `line`, so a consumer wanting a different render policy can derive
|
||||
* its own. Labels are HEADING-DERIVED only: the caption is the nearest heading
|
||||
* above the directive (so a consumer's progress line reads like the section
|
||||
* it's in), falling back to a kind/effect default.
|
||||
*/
|
||||
export function stepLabel(d: Directive, md: string): string | null {
|
||||
const effect = typeof d.attrs.effect === 'string' ? d.attrs.effect : undefined;
|
||||
const spins =
|
||||
d.kind === 'dep' ||
|
||||
(d.kind === 'copy' && typeof d.attrs['from-branch'] === 'string') ||
|
||||
(d.kind === 'run' && (effect === undefined || SPIN_EFFECTS.has(effect)));
|
||||
if (!spins) return null;
|
||||
const heading = headingAbove(md, d.line);
|
||||
if (heading) return heading;
|
||||
if (d.kind === 'dep') return 'Installing dependencies';
|
||||
if (d.kind === 'copy') return 'Fetching files';
|
||||
const byEffect: Record<string, string> = {
|
||||
build: 'Building', test: 'Testing', fetch: 'Fetching',
|
||||
wire: 'Wiring', restart: 'Restarting', external: 'Running',
|
||||
};
|
||||
return (effect && byEffect[effect]) || 'Running';
|
||||
}
|
||||
|
||||
// Deterministic input normalization applied AT BIND to every prompt value —
|
||||
// `inputs` AND interactive answers alike — driven by `nc:prompt normalize:<how>`:
|
||||
// trim strip leading/trailing whitespace
|
||||
// rstrip-slash drop trailing slash(es) — a base URL with no trailing path
|
||||
// lower lowercase
|
||||
// Absent/unknown ⇒ a no-op (lint gates the known set). Doing it here, not in the
|
||||
// consumer, means a programmatic `inputs` value and a typed answer land identically.
|
||||
// Exported so the driver's reuse-offer pre-filter (§5.4) tests an `.env` value
|
||||
// against the SAME normalize-then-validate the engine will apply at bind.
|
||||
export function normalizeValue(value: string, normalize: string | undefined): string {
|
||||
switch (normalize) {
|
||||
case 'trim':
|
||||
return value.trim();
|
||||
case 'rstrip-slash':
|
||||
return value.replace(/\/+$/, '');
|
||||
case 'lower':
|
||||
return value.toLowerCase();
|
||||
default:
|
||||
return value;
|
||||
}
|
||||
}
|
||||
|
||||
// The engine-applied normalize transforms (see `normalizeValue`) — the set
|
||||
// InputMeta.normalize narrows to. Lint gates authorship to these; an unknown
|
||||
// value simply isn't declared in the meta (and normalizeValue no-ops on it).
|
||||
const NORMALIZE_KINDS: ReadonlySet<string> = new Set(['trim', 'rstrip-slash', 'lower']);
|
||||
|
||||
// The InputMeta an `nc:prompt` declares — handed to `resolveInput` so a
|
||||
// consumer can run its own re-ask loop against the same semantics the engine
|
||||
// enforces at bind. The attrs live on the directive fence, so they're stripped
|
||||
// along with the fence when a skill degrades to prose — invisible to the agent.
|
||||
function inputMetaOf(d: Directive, secret: boolean, validate: string | undefined): InputMeta {
|
||||
const meta: InputMeta = { question: d.body.join('\n'), secret };
|
||||
if (validate !== undefined) meta.validate = validate;
|
||||
if (typeof d.attrs.flags === 'string') meta.flags = d.attrs.flags;
|
||||
if (typeof d.attrs.normalize === 'string' && NORMALIZE_KINDS.has(d.attrs.normalize)) {
|
||||
meta.normalize = d.attrs.normalize as InputMeta['normalize'];
|
||||
}
|
||||
return meta;
|
||||
}
|
||||
|
||||
function substitute(value: string, vars: Map<string, { value: string; secret: boolean }>): string {
|
||||
return value.replace(VAR_REF, (_, name) => {
|
||||
const v = vars.get(name);
|
||||
if (!v) throw new Error(`unresolved {{${name}}}`);
|
||||
return v.value;
|
||||
});
|
||||
}
|
||||
|
||||
// A `when:<var>=<value>` guard: the directive applies only when an earlier
|
||||
// prompt/capture bound <var> to exactly <value>. Unmet — including the var still
|
||||
// unresolved (a deferred prompt) — skips the directive, so a guarded prompt is
|
||||
// skipped, never deferred. This is how a skill expresses mutually-exclusive
|
||||
// branches (e.g. local vs remote install mode) in plain document order.
|
||||
function whenMet(when: string, vars: Map<string, { value: string; secret: boolean }>): boolean {
|
||||
const eq = when.indexOf('=');
|
||||
if (eq < 1) return true; // malformed → don't block (lint is the gate)
|
||||
return vars.get(when.slice(0, eq).trim())?.value === when.slice(eq + 1).trim();
|
||||
}
|
||||
|
||||
// Resolve a jq-style dot-path (`.id`, `.owner.id`) into a parsed JSON value.
|
||||
// A missing/non-object hop yields undefined — the caller coerces that to ''.
|
||||
function dotPath(obj: unknown, path: string): unknown {
|
||||
let cur: unknown = obj;
|
||||
for (const key of path.replace(/^\./, '').split('.').filter(Boolean)) {
|
||||
if (cur === null || typeof cur !== 'object') return undefined;
|
||||
cur = (cur as Record<string, unknown>)[key];
|
||||
}
|
||||
return cur;
|
||||
}
|
||||
|
||||
// Bind a `run capture:<spec>` from a command's stdout into one or more {{vars}}.
|
||||
// • bare `capture:var` → binds the trimmed stdout as-is (unchanged).
|
||||
// • `capture:a=.x,b=.owner.id` → parses the stdout as JSON and binds each var
|
||||
// to its dot-path, so ONE API call resolves
|
||||
// several values (the structured twin of the
|
||||
// effect:step terminal-block capture — those
|
||||
// two are distinguished by effect: step reads
|
||||
// the status block, fetch/external read JSON
|
||||
// stdout). Unparseable JSON throws → the outer
|
||||
// catch bounces it to an agent.
|
||||
// An optional `validate:<re>` is enforced against every bound value; a mismatch
|
||||
// THROWS so the run bounces to an agent — a command's output has no human to
|
||||
// re-prompt, so an invalid capture is a real failure, not a re-ask.
|
||||
function bindCapture(
|
||||
spec: string,
|
||||
stdout: string,
|
||||
validate: string | undefined,
|
||||
vars: Map<string, { value: string; secret: boolean }>,
|
||||
): void {
|
||||
const re = validate ? new RegExp(validate) : undefined;
|
||||
const set = (name: string, value: string): void => {
|
||||
if (re && !re.test(value)) throw new Error(`captured ${name}="${value}" does not match validate:${validate}`);
|
||||
vars.set(name, { value, secret: false });
|
||||
};
|
||||
if (!spec.includes('=')) {
|
||||
set(spec, stdout);
|
||||
return;
|
||||
}
|
||||
const json = JSON.parse(stdout) as unknown; // not JSON → throws → outer catch bounces
|
||||
for (const pair of spec.split(',')) {
|
||||
const eq = pair.indexOf('=');
|
||||
if (eq < 1) continue;
|
||||
set(pair.slice(0, eq).trim(), String(dotPath(json, pair.slice(eq + 1).trim()) ?? ''));
|
||||
}
|
||||
}
|
||||
|
||||
// The mutating twin of selfStatus. Records what it did to the journal so remove
|
||||
// is derivable. Throws on failure → caught and bounced to an agent.
|
||||
async function applyOne(
|
||||
d: Directive,
|
||||
ctx: { root: string; skillDir: string; exec: (c: string) => string | void | Promise<string | void>; execStream?: (c: string) => Promise<StepOutcome>; resolveRemote: (b: string) => string; vars: Map<string, { value: string; secret: boolean }>; journal: JournalEntry[] },
|
||||
): Promise<void> {
|
||||
const { root, skillDir, exec, vars, journal } = ctx;
|
||||
switch (d.kind) {
|
||||
case 'copy':
|
||||
if (d.attrs['from-branch']) {
|
||||
const b = String(d.attrs['from-branch']);
|
||||
const remote = ctx.resolveRemote(b);
|
||||
await exec(`git fetch ${remote} ${b}`);
|
||||
for (const l of d.body) await exec(`git show ${remote}/${b}:${srcOf(l)} > ${destOf(l)}`);
|
||||
} else {
|
||||
for (const l of d.body) {
|
||||
const dst = join(root, destOf(l));
|
||||
mkdirSync(dirname(dst), { recursive: true });
|
||||
copyFileSync(join(skillDir, srcOf(l)), dst);
|
||||
}
|
||||
}
|
||||
for (const l of d.body) journal.push({ op: 'wrote', path: destOf(l) });
|
||||
break;
|
||||
case 'append': {
|
||||
const to = String(d.attrs.to);
|
||||
const marker = typeof d.attrs.at === 'string' ? d.attrs.at : undefined;
|
||||
const target = join(root, to);
|
||||
if (marker) {
|
||||
// Insert before the `// <<< <marker>` closing line of a dormant marker
|
||||
// region, matching that line's indentation. removeSkill still deletes
|
||||
// by line (position-agnostic), so the journal entry is unchanged.
|
||||
const close = `<<< ${marker}`;
|
||||
for (const line of d.body) {
|
||||
const lines = read(target).split('\n');
|
||||
const idx = lines.findIndex((l) => l.includes(close));
|
||||
if (idx === -1) throw new Error(`append marker "${marker}" not found in ${to}`);
|
||||
const indent = lines[idx].match(/^\s*/)?.[0] ?? '';
|
||||
lines.splice(idx, 0, indent + line);
|
||||
writeFileSync(target, lines.join('\n'));
|
||||
journal.push({ op: 'appended', path: to, line });
|
||||
}
|
||||
} else {
|
||||
for (const line of d.body) {
|
||||
appendFileSync(target, (read(target).endsWith('\n') || read(target) === '' ? '' : '\n') + line + '\n');
|
||||
journal.push({ op: 'appended', path: to, line });
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'dep': {
|
||||
await exec(`pnpm add ${d.body.join(' ')}`);
|
||||
const names = d.body.map((s) => s.slice(0, s.lastIndexOf('@'))).join(' ');
|
||||
journal.push({ op: 'ran', cmd: `pnpm add ${d.body.join(' ')}`, undo: `pnpm remove ${names}` });
|
||||
break;
|
||||
}
|
||||
case 'run': {
|
||||
// `capture:<var>` binds the command's stdout into a {{var}} — the twin of
|
||||
// `prompt` (which binds human input). Lets a run resolve a value from an
|
||||
// API (e.g. Slack conversations.open → the DM channel id) and feed it to a
|
||||
// later directive, so a flow that validates/resolves stays pure directives.
|
||||
const capture = typeof d.attrs.capture === 'string' ? d.attrs.capture : undefined;
|
||||
// A `validate:<re>` shape-guard the stdout capture enforces (see bindCapture).
|
||||
const validate = typeof d.attrs.validate === 'string' ? d.attrs.validate : undefined;
|
||||
// effect:check runs the body as a shell PREDICATE — a precondition gate
|
||||
// that mutates NOTHING. It pushes no journal entry and binds no capture: a
|
||||
// zero exit is a silent pass; a non-zero exit throws → the outer catch
|
||||
// bounces it to an agent (which reads the prose and decides); an unresolved
|
||||
// {{var}} throws from substitute first → deferred (like any other run, e.g.
|
||||
// a headless rebuild before the value is collected). Because a bounce here
|
||||
// latches `blocked`, a failed precondition gates the dangerous side effects
|
||||
// (a restart, a pairing/QR step, a wire) that follow — a broken local
|
||||
// config or an un-registered app never reaches a doomed restart/QR.
|
||||
if (d.attrs.effect === 'check') {
|
||||
for (const cmd of d.body) await exec(substitute(cmd, vars));
|
||||
break;
|
||||
}
|
||||
// effect:step runs a long-running, operator-interactive step (a pairing
|
||||
// code, a QR device-link) through the streaming exec and binds the terminal
|
||||
// status block's named fields via capture:<var>=<FIELD>[,…] — the structured,
|
||||
// multi-valued twin of stdout capture. No streaming exec ⇒ throw → an agent
|
||||
// runs the step from the prose (degrade, not crash).
|
||||
if (d.attrs.effect === 'step') {
|
||||
if (!ctx.execStream) throw new Error('effect:step needs a streaming exec — an agent runs the step from the prose');
|
||||
const { ok, fields } = await ctx.execStream(substitute(d.body.join('\n'), vars));
|
||||
if (!ok) throw new Error('the step did not complete');
|
||||
if (capture) {
|
||||
for (const pair of capture.split(',')) {
|
||||
const eq = pair.indexOf('=');
|
||||
if (eq < 1) continue;
|
||||
vars.set(pair.slice(0, eq).trim(), { value: (fields[pair.slice(eq + 1).trim()] ?? '').trim(), secret: false });
|
||||
}
|
||||
}
|
||||
journal.push({ op: 'ran', cmd: d.body.join('\n') });
|
||||
break;
|
||||
}
|
||||
for (const cmd of d.body) {
|
||||
// Interpolate prompted {{vars}} the same way env-set does, so a run can
|
||||
// call `ncl ... {{owner_email}}` to wire from collected input. A command
|
||||
// with no {{...}} (build/test) is returned unchanged; an unresolved var
|
||||
// throws → caught → deferred (the prompt hasn't been answered yet).
|
||||
const out = await exec(substitute(cmd, vars));
|
||||
// Last command wins for capture (a capture run should be a single command).
|
||||
// bindCapture binds stdout-as-is OR a multi-field JSON spec, and enforces
|
||||
// validate:<re> — a mismatch / unparseable JSON throws → bounced to an agent.
|
||||
if (capture) bindCapture(capture, typeof out === 'string' ? out.trim() : '', validate, vars);
|
||||
// Journal the ORIGINAL command (placeholders intact) — never the
|
||||
// substituted form — so a secret interpolated into a run never lands in
|
||||
// the journal (or a remove replay).
|
||||
const undo = d.attrs.effect === 'external' && typeof d.attrs.remove === 'string' ? d.attrs.remove : undefined;
|
||||
journal.push({ op: 'ran', cmd, undo });
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'env-set': {
|
||||
const envPath = join(root, '.env');
|
||||
for (const entry of d.body) {
|
||||
const eq = entry.indexOf('=');
|
||||
const key = entry.slice(0, eq).trim();
|
||||
const value = substitute(entry.slice(eq + 1).trim(), vars); // throws if a {{var}} is unresolved
|
||||
if (!envKeySet(root, key)) {
|
||||
appendFileSync(envPath, (read(envPath).endsWith('\n') || read(envPath) === '' ? '' : '\n') + `${key}=${value}\n`);
|
||||
journal.push({ op: 'set-env', key });
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'json-merge': {
|
||||
const into = String(d.attrs.into);
|
||||
const key = String(d.attrs.key);
|
||||
const obj = JSON.parse(d.body.join('\n')) as Record<string, unknown>;
|
||||
const target = join(root, into);
|
||||
const arr = JSON.parse(read(target) || '[]') as unknown[];
|
||||
if (!Array.isArray(arr)) throw new Error(`${into} is not a JSON array`);
|
||||
const value = obj[key];
|
||||
// Idempotent: only push when no element already matches on the key.
|
||||
if (!arr.some((el) => el !== null && typeof el === 'object' && (el as Record<string, unknown>)[key] === value)) {
|
||||
arr.push(obj);
|
||||
writeFileSync(target, JSON.stringify(arr, null, 2) + '\n');
|
||||
journal.push({ op: 'json-merge', path: into, key, value });
|
||||
}
|
||||
break;
|
||||
}
|
||||
default:
|
||||
throw new Error(`no handler for nc:${d.kind}`);
|
||||
}
|
||||
}
|
||||
|
||||
export async function applySkill(skillDir: string, root: string, opts: ApplyOptions): Promise<ApplyResult> {
|
||||
// Lint (validate()) is the authoring/CI gate, run before a skill ships — NOT
|
||||
// here. Apply is best-effort: an unknown directive (a typo lint should have
|
||||
// caught, or one newer than this engine) bounces to an agent, never blocks.
|
||||
const md = read(join(skillDir, 'SKILL.md'));
|
||||
const directives = parseDirectives(md);
|
||||
const exec = opts.exec ?? (() => { throw new Error('no exec provided'); });
|
||||
const resolveRemote = opts.resolveRemote ?? ((b: string) => defaultResolveRemote(b, root));
|
||||
const vars = new Map<string, { value: string; secret: boolean }>();
|
||||
const res: ApplyResult = { applied: [], skipped: [], deferred: [], agentTasks: [], operatorMessages: [], vars: {}, journal: [], referenceProse: referenceProse(md) };
|
||||
// A run-health gate: once ANY directive bounces to an agent, the skill is no
|
||||
// longer in a known-good state, so the dangerous side effects below must not
|
||||
// fire on their own — a live restart, an interactive pairing/QR step, or a wire
|
||||
// launched after an upstream failure just wastes the operator's time (a doomed
|
||||
// QR, a restart that loads a bad credential). `blocked` latches on the first
|
||||
// bounce; a later side-effecting run becomes its own bounce so the agent
|
||||
// finishes it from the prose once the upstream failure is fixed. A DEFERRED
|
||||
// prompt (headless rebuild, no answer) is not a failure — it never bounces, so
|
||||
// `blocked` stays false and a later restart remains runnable.
|
||||
let blocked = false;
|
||||
const SIDE_EFFECTS = new Set(['restart', 'step', 'wire']);
|
||||
const bounce = (d: Directive, reason: string) => {
|
||||
blocked = true;
|
||||
res.agentTasks.push({ kind: d.kind, line: d.line, reason, prose: proseFor(md, d.line) });
|
||||
};
|
||||
|
||||
for (const d of directives) {
|
||||
// Tracks an in-flight step so the catch can always close a matching
|
||||
// step-end (start/end stay balanced even when applyOne throws — a consumer's
|
||||
// spinner is never orphaned). Set only after step-start fires.
|
||||
let inFlight: { label: string | null; at: number } | null = null;
|
||||
try {
|
||||
// A `when:<var>=<value>` guard that isn't met skips the directive entirely —
|
||||
// before prompt (so a guarded prompt is skipped, never deferred), operator,
|
||||
// and run handling. This is how mutually-exclusive branches coexist in one
|
||||
// skill while a fully-programmatic apply still completes.
|
||||
if (typeof d.attrs.when === 'string' && !whenMet(d.attrs.when, vars)) {
|
||||
res.skipped.push(`${d.kind}: when ${d.attrs.when} not met`);
|
||||
continue;
|
||||
}
|
||||
if (d.kind === 'prompt') {
|
||||
const v = promptVar(d)!;
|
||||
const secret = d.args.includes('secret');
|
||||
const validate = typeof d.attrs.validate === 'string' ? d.attrs.validate : undefined;
|
||||
const flags = typeof d.attrs.flags === 'string' ? d.attrs.flags : undefined;
|
||||
const normalize = typeof d.attrs.normalize === 'string' ? d.attrs.normalize : undefined;
|
||||
// Pre-supplied inputs win OUTRIGHT (fully-programmatic apply) — an
|
||||
// invalid `inputs` value never falls through to a second acquisition
|
||||
// path (validation below rejects it loudly instead). Otherwise resolve
|
||||
// via `resolveInput`; still undefined ⇒ defer (headless, no answer).
|
||||
let val = opts.inputs?.[v];
|
||||
if (val === undefined) val = await opts.resolveInput?.(v, inputMetaOf(d, secret, validate));
|
||||
if (val === undefined) { res.deferred.push(v); continue; }
|
||||
// normalize:<how> binds DETERMINISTICALLY for both inputs and answers, so
|
||||
// an `inputs` value and a typed one land identically (a trailing slash
|
||||
// stripped, whitespace trimmed) — see normalizeValue.
|
||||
const bound = normalizeValue(val, normalize);
|
||||
// Validate-at-bind: `validate:` (+ `flags:`) is DATA validation, enforced
|
||||
// on the NORMALIZED value no matter where it came from (normalize-then-
|
||||
// validate is normative: a trailing slash is stripped before an anchor
|
||||
// check). On a mismatch the var stays UNBOUND and only the var name +
|
||||
// regex source land in the deferred entry — never the value, so a secret
|
||||
// can't leak. Not an agentTask, not a throw: downstream consumers defer
|
||||
// exactly as if the value were never supplied, `fullyApplied` is false,
|
||||
// and a pipeline passing a malformed env value fails loudly. The
|
||||
// interactive re-ask loop lives in the consumer's `resolveInput`; this is
|
||||
// the backstop for programmatic paths.
|
||||
if (validate !== undefined && !new RegExp(validate, flags).test(bound)) {
|
||||
res.deferred.push(`${v}: invalid value (does not match validate:${validate})`);
|
||||
continue;
|
||||
}
|
||||
vars.set(v, { value: bound, secret });
|
||||
continue;
|
||||
}
|
||||
if (d.kind === 'operator') {
|
||||
// Once the run is blocked, walking the human through further manual
|
||||
// steps is actively misleading — the side effects those instructions
|
||||
// lead up to ("a pairing code is about to appear") have already been
|
||||
// gated. Skip: no event (so a consumer's URL offer / readiness confirm
|
||||
// never fires), no operatorMessages entry (a failed run's manual-steps
|
||||
// report must not include steps predicated on the failed one).
|
||||
if (blocked) {
|
||||
res.skipped.push('operator: skipped after an earlier failure');
|
||||
continue;
|
||||
}
|
||||
// Always collect the human-facing instructions into the result so a
|
||||
// programmatic caller can relay/output them. {{vars}} render so a
|
||||
// resolved value can be shown (throws → deferred if a referenced var is
|
||||
// unset — the whole block defers before any event fires).
|
||||
const text = substitute(d.body.join('\n'), vars);
|
||||
res.operatorMessages.push(text);
|
||||
// The core seam: emit the rendered block and AWAIT the consumer before
|
||||
// evaluating the next directive — that ordering is what lets a consumer
|
||||
// gate (hold the event until the human confirms readiness). The engine
|
||||
// itself never defers/bounces an operator block; a handler that throws
|
||||
// opts into the standard bounce path via the outer catch (including
|
||||
// the `blocked` latch over later side effects).
|
||||
if (opts.onEvent) await opts.onEvent({ type: 'operator', line: d.line, text });
|
||||
res.applied.push(`operator: ${(d.body[0] ?? '').slice(0, 50)}`);
|
||||
continue;
|
||||
}
|
||||
// A run whose effect the caller owns (e.g. restart) is skipped here.
|
||||
if (d.kind === 'run' && typeof d.attrs.effect === 'string' && opts.skipEffects?.includes(d.attrs.effect)) {
|
||||
res.skipped.push(`run ${d.attrs.effect}: owned by the caller`);
|
||||
continue;
|
||||
}
|
||||
// Run-health gate: after an earlier bounce, never fire a dangerous side
|
||||
// effect (a live restart, an interactive pairing/QR step, a wire) on its
|
||||
// own — bounce it too so the agent runs it from the prose once the upstream
|
||||
// failure is fixed. (A deferred prompt did NOT set `blocked`, so this only
|
||||
// trips on a real failure, never a headless rebuild's missing input.)
|
||||
if (d.kind === 'run' && typeof d.attrs.effect === 'string' && SIDE_EFFECTS.has(d.attrs.effect) && blocked) {
|
||||
bounce(d, 'skipped: an earlier step did not complete — run this from the prose after fixing it');
|
||||
continue;
|
||||
}
|
||||
const st = selfStatus(d, root);
|
||||
if (st.status === 'agent') { bounce(d, 'no deterministic handler'); continue; }
|
||||
if (st.status === 'skip') { res.skipped.push(`${d.kind}: ${st.detail}`); continue; }
|
||||
// Bracket the real mutation with step events so a consumer can render
|
||||
// progress. `label` null is a step-cost/interactivity declaration (see
|
||||
// `stepLabel`). `inFlight` is set only after step-start fires; the ok:true
|
||||
// step-end clears it BEFORE its own (awaited) emission, so a consumer
|
||||
// throw there never double-closes.
|
||||
const label = stepLabel(d, md);
|
||||
if (opts.onEvent) await opts.onEvent({ type: 'step-start', kind: d.kind, line: d.line, label });
|
||||
inFlight = { label, at: Date.now() };
|
||||
await applyOne(d, { root, skillDir, exec, execStream: opts.execStream, resolveRemote, vars, journal: res.journal });
|
||||
const durationMs = Date.now() - inFlight.at;
|
||||
inFlight = null;
|
||||
if (opts.onEvent) await opts.onEvent({ type: 'step-end', kind: d.kind, line: d.line, label, ok: true, durationMs });
|
||||
res.applied.push(`${d.kind}: ${st.detail}`);
|
||||
} catch (e) {
|
||||
const msg = e instanceof Error ? e.message : String(e);
|
||||
// Close the step as failed before classifying — keeps step-start/step-end
|
||||
// balanced whether the throw becomes a deferred (unresolved input) or a
|
||||
// bounce (a real failure, handled below). The failure-path close is
|
||||
// best-effort: a consumer that also throws here can't change the outcome —
|
||||
// we're already on the failure path.
|
||||
if (inFlight && opts.onEvent) {
|
||||
const end = { kind: d.kind, line: d.line, label: inFlight.label, ok: false, durationMs: Date.now() - inFlight.at, error: msg };
|
||||
try { await opts.onEvent({ type: 'step-end', ...end }); } catch { /* already failing — the close is best-effort */ }
|
||||
}
|
||||
if (/unresolved \{\{/.test(msg)) res.deferred.push(msg); // blocked on a prompt input
|
||||
else bounce(d, `engine could not apply (${msg}) — an agent applies it from the prose`);
|
||||
}
|
||||
}
|
||||
// Surface the non-secret resolved values for a caller to consume.
|
||||
for (const [k, v] of vars) if (!v.secret) res.vars[k] = v.value;
|
||||
return res;
|
||||
}
|
||||
|
||||
// Remove is the journal played backwards — no hand-written REMOVE.md.
|
||||
export async function removeSkill(root: string, journal: JournalEntry[], exec?: (c: string) => void | Promise<void>): Promise<void> {
|
||||
for (const e of [...journal].reverse()) {
|
||||
if (e.op === 'wrote') rmSync(join(root, e.path), { force: true });
|
||||
else if (e.op === 'appended') {
|
||||
const p = join(root, e.path);
|
||||
writeFileSync(p, read(p).split('\n').filter((l) => l.trim() !== e.line.trim()).join('\n'));
|
||||
} else if (e.op === 'set-env') {
|
||||
const p = join(root, '.env');
|
||||
writeFileSync(p, read(p).split('\n').filter((l) => !l.startsWith(`${e.key}=`)).join('\n'));
|
||||
} else if (e.op === 'json-merge') {
|
||||
const p = join(root, e.path);
|
||||
const arr = JSON.parse(read(p) || '[]') as unknown[];
|
||||
if (Array.isArray(arr)) {
|
||||
writeFileSync(p, JSON.stringify(arr.filter((el) => !(el !== null && typeof el === 'object' && (el as Record<string, unknown>)[e.key] === e.value)), null, 2) + '\n');
|
||||
}
|
||||
} else if (e.op === 'ran' && e.undo && exec) {
|
||||
await exec(e.undo);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// CLI — the planner (no writes)
|
||||
if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
|
||||
const skillDir = process.argv[2];
|
||||
if (!skillDir) {
|
||||
console.error('usage: pnpm exec tsx scripts/skill-apply.ts <skillDir>');
|
||||
process.exit(2);
|
||||
}
|
||||
const root = process.cwd();
|
||||
const { steps, needsInput, agentSteps } = planSkill(skillDir, root);
|
||||
console.log(`PLAN ${skillDir} project: ${root}\n`);
|
||||
const icon: Record<StepStatus, string> = { skip: '✓ skip', apply: '→ apply', 'needs-input': '? human', agent: '↳ agent' };
|
||||
for (const s of steps) console.log(`${String(s.n).padStart(2)}. ${icon[s.status].padEnd(8)} ${s.kind.padEnd(9)} ${s.detail}`);
|
||||
console.log(`\nneeds human input: ${needsInput.join(', ') || '(none)'} →agent: ${agentSteps}`);
|
||||
}
|
||||
@@ -1,458 +0,0 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { parseDirectives, validate, promptVar, resolveChatCoreVersion, lintReferenceFloor, lintGateAmbiguity } from './skill-directives.js';
|
||||
|
||||
// Guards the structured-directive format against the converted add-slack skill:
|
||||
// red if the conversion drifts (a directive dropped/renamed) or the parser breaks.
|
||||
const slack = readFileSync('.claude/skills/add-slack/SKILL.md', 'utf8');
|
||||
const directives = parseDirectives(slack);
|
||||
|
||||
describe('skill-directives parser, on the converted add-slack', () => {
|
||||
it('extracts every directive in document order — install, credentials, resolve, restart', () => {
|
||||
expect(directives.map((d) => d.kind)).toEqual([
|
||||
'copy', // step 1: adapter + test from the channels branch
|
||||
'append', // step 2: barrel registration
|
||||
'dep', // step 3: pinned package
|
||||
'run', // step 4: build
|
||||
'run', // step 4: test
|
||||
'prompt', // credentials: socket vs webhook delivery mode
|
||||
'operator', // credentials: create-app walkthrough, Socket Mode variant
|
||||
'operator', // credentials: create-app walkthrough, webhook variant
|
||||
'prompt', // credentials: capture bot token
|
||||
'prompt', // credentials: capture app-level token (socket only)
|
||||
'prompt', // credentials: capture signing secret (webhook only)
|
||||
'env-set', // credentials: bot token (both modes)
|
||||
'env-set', // credentials: app token — doubles as the Socket Mode switch
|
||||
'env-set', // credentials: signing secret (webhook only)
|
||||
'operator', // credentials: event-delivery walkthrough (webhook only)
|
||||
'prompt', // resolve: owner member id (owner_handle)
|
||||
'run', // resolve: validate token (auth.test) — fast-fail before the restart
|
||||
'run', // resolve: DM channel (conversations.open → capture:platform_id)
|
||||
'run', // restart: load the adapter + creds once the credential is validated
|
||||
]);
|
||||
// The wire (owner role, messaging-group, wiring, /welcome) is NOT in the
|
||||
// skill — it's the shared init-first-agent, called by the setup flow.
|
||||
expect(directives.some((d) => d.attrs.effect === 'wire')).toBe(false);
|
||||
});
|
||||
|
||||
it('delineates the human UI steps as nc:operator (not agent prose or a run)', () => {
|
||||
const ops = directives.filter((d) => d.kind === 'operator');
|
||||
expect(ops).toHaveLength(3);
|
||||
expect(ops[0].body.join('\n')).toMatch(/Create the Slack app \(Socket Mode\)/);
|
||||
expect(ops[0].body.join('\n')).toMatch(/connections:write/);
|
||||
expect(ops[1].body.join('\n')).toMatch(/Create the Slack app \(webhook delivery\)/);
|
||||
expect(ops[1].body.join('\n')).toMatch(/Bot Token Scopes/);
|
||||
expect(ops[2].body.join('\n')).toMatch(/Event Subscriptions/);
|
||||
// the mode branches are guard-delineated, one per delivery mode
|
||||
expect(ops[0].attrs.when).toBe('connection=socket');
|
||||
expect(ops[1].attrs.when).toBe('connection=webhook');
|
||||
expect(ops[2].attrs.when).toBe('connection=webhook');
|
||||
});
|
||||
|
||||
it('reads copy as a branch fetch with both files', () => {
|
||||
const copy = directives.find((d) => d.kind === 'copy')!;
|
||||
expect(copy.attrs['from-branch']).toBe('channels');
|
||||
expect(copy.body).toEqual(['src/channels/slack.ts', 'src/channels/slack-registration.test.ts']);
|
||||
});
|
||||
|
||||
it('reads the barrel append target and line', () => {
|
||||
const append = directives.find((d) => d.kind === 'append')!;
|
||||
expect(append.attrs.to).toBe('src/channels/index.ts');
|
||||
expect(append.body).toEqual(["import './slack.js';"]);
|
||||
});
|
||||
|
||||
it('reads the dependency pinned exactly', () => {
|
||||
const dep = directives.find((d) => d.kind === 'dep')!;
|
||||
expect(dep.body).toEqual(['@chat-adapter/slack@4.29.0']);
|
||||
});
|
||||
|
||||
it('tags the runs with their effects', () => {
|
||||
expect(directives.filter((d) => d.kind === 'run').map((d) => d.attrs.effect)).toEqual([
|
||||
'build',
|
||||
'test',
|
||||
'fetch', // validate: auth.test — credential checked first
|
||||
'fetch', // resolve: conversations.open
|
||||
'restart', // load adapter + creds after the credential is validated, before wiring
|
||||
]);
|
||||
});
|
||||
|
||||
it('captures prompts into named vars — credentials secret, the mode and handle not', () => {
|
||||
const prompts = directives.filter((d) => d.kind === 'prompt');
|
||||
expect(prompts.map(promptVar)).toEqual(['connection', 'bot_token', 'app_token', 'signing_secret', 'owner_handle']);
|
||||
expect(prompts[0].args).not.toContain('secret'); // connection — a mode choice, not a secret
|
||||
expect(prompts[1].args).toContain('secret'); // bot_token
|
||||
expect(prompts[2].args).toContain('secret'); // app_token
|
||||
expect(prompts[3].args).toContain('secret'); // signing_secret
|
||||
expect(prompts[4].args).not.toContain('secret'); // owner_handle — a plain id, not a secret
|
||||
// Each mode's credential is guard-scoped to its branch.
|
||||
expect(prompts[2].attrs.when).toBe('connection=socket');
|
||||
expect(prompts[3].attrs.when).toBe('connection=webhook');
|
||||
// The prompt body is the question; it does not mention env at all.
|
||||
expect(prompts[1].body.join(' ')).toMatch(/Bot User OAuth Token/);
|
||||
});
|
||||
|
||||
it('resolves the conversation address into capture:platform_id (the wire input)', () => {
|
||||
const runs = directives.filter((d) => d.kind === 'run');
|
||||
const resolve = runs.find((d) => d.attrs.capture === 'platform_id')!;
|
||||
expect(resolve).toBeTruthy();
|
||||
expect(resolve.body.join(' ')).toMatch(/conversations\.open/);
|
||||
expect(resolve.body.join(' ')).toMatch(/"slack:" \+ \.channel\.id/); // emits the slack:<id> platform_id
|
||||
});
|
||||
|
||||
it('wires the captured variables into env-set via {{var}} references, one per mode', () => {
|
||||
const envSets = directives.filter((d) => d.kind === 'env-set');
|
||||
expect(envSets.map((d) => d.body)).toEqual([
|
||||
['SLACK_BOT_TOKEN={{bot_token}}'],
|
||||
['SLACK_APP_TOKEN={{app_token}}'],
|
||||
['SLACK_SIGNING_SECRET={{signing_secret}}'],
|
||||
]);
|
||||
expect(envSets[1].attrs.when).toBe('connection=socket');
|
||||
expect(envSets[2].attrs.when).toBe('connection=webhook');
|
||||
});
|
||||
|
||||
it('passes validation (well-formed, pinned, every {{var}} captured first)', () => {
|
||||
expect(validate(directives)).toEqual([]);
|
||||
});
|
||||
|
||||
it('keeps its @chat-adapter pin in sync with our chat core (drift guard)', () => {
|
||||
const chat = resolveChatCoreVersion(process.cwd());
|
||||
expect(chat).toMatch(/^\d+\.\d+\.\d+/); // our lockfile resolves a real chat version
|
||||
expect(validate(directives, { chatVersion: chat })).toEqual([]); // add-slack matches it
|
||||
});
|
||||
|
||||
it('ignores plain (non-nc:) code fences so prose stays the floor', () => {
|
||||
const withProse = slack + '\n```bash\nrm -rf /\n```\n';
|
||||
expect(parseDirectives(withProse).map((d) => d.kind)).toEqual(directives.map((d) => d.kind));
|
||||
});
|
||||
});
|
||||
|
||||
describe('validation catches malformed directives', () => {
|
||||
it('flags an unpinned dependency and an unknown directive', () => {
|
||||
const md = ['```nc:dep', '@chat-adapter/slack@latest', '```', '', '```nc:frobnicate', 'x', '```'].join('\n');
|
||||
const problems = validate(parseDirectives(md));
|
||||
expect(problems.some((p) => /exact semver/.test(p.message))).toBe(true);
|
||||
expect(problems.some((p) => /unknown directive/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('flags an env-set that references a variable no prompt captured', () => {
|
||||
const md = ['```nc:env-set', 'SLACK_BOT_TOKEN={{bot_token}}', '```'].join('\n');
|
||||
const problems = validate(parseDirectives(md));
|
||||
expect(problems.some((p) => /\{\{bot_token\}\} but no earlier nc:prompt/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('flags a @chat-adapter pin that does not match the chat core', () => {
|
||||
const md = ['```nc:dep', '@chat-adapter/slack@4.27.0', '```'].join('\n');
|
||||
const problems = validate(parseDirectives(md), { chatVersion: '4.26.0' });
|
||||
expect(problems.some((p) => /must match the chat package/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('accepts a @chat-adapter pin that matches the chat core', () => {
|
||||
const md = ['```nc:dep', '@chat-adapter/slack@4.26.0', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md), { chatVersion: '4.26.0' })).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('json-merge directive', () => {
|
||||
const codex = ['```nc:json-merge into:container/cli-tools.json key:name', '{ "name": "@openai/codex", "version": "0.138.0" }', '```'].join('\n');
|
||||
|
||||
it('parses into/key attrs and the JSON object body', () => {
|
||||
const [d] = parseDirectives(codex);
|
||||
expect(d.kind).toBe('json-merge');
|
||||
expect(d.attrs.into).toBe('container/cli-tools.json');
|
||||
expect(d.attrs.key).toBe('name');
|
||||
expect(JSON.parse(d.body.join('\n'))).toEqual({ name: '@openai/codex', version: '0.138.0' });
|
||||
});
|
||||
|
||||
it('passes validation when into + key + a parseable object are all present', () => {
|
||||
expect(validate(parseDirectives(codex))).toEqual([]);
|
||||
});
|
||||
|
||||
it('flags a missing into:', () => {
|
||||
const md = ['```nc:json-merge key:name', '{ "name": "x" }', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md)).some((p) => /requires into:/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('flags a missing key:', () => {
|
||||
const md = ['```nc:json-merge into:container/cli-tools.json', '{ "name": "x" }', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md)).some((p) => /requires key:/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('flags an unparseable body', () => {
|
||||
const md = ['```nc:json-merge into:f.json key:name', '{ not json', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md)).some((p) => /parseable JSON object/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('flags a body that is an array, not a single object', () => {
|
||||
const md = ['```nc:json-merge into:f.json key:name', '[{ "name": "x" }]', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md)).some((p) => /single JSON object/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('flags a body missing the match key field', () => {
|
||||
const md = ['```nc:json-merge into:f.json key:name', '{ "version": "1.0.0" }', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md)).some((p) => /no "name" field/.test(p.message))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('append at:<marker> attribute', () => {
|
||||
it('parses an optional at:<marker> alongside to:', () => {
|
||||
const md = ['```nc:append to:setup/index.ts at:nanoclaw:setup-steps', " codex: () => import('./codex.js'),", '```'].join('\n');
|
||||
const [d] = parseDirectives(md);
|
||||
expect(d.kind).toBe('append');
|
||||
expect(d.attrs.to).toBe('setup/index.ts');
|
||||
expect(d.attrs.at).toBe('nanoclaw:setup-steps');
|
||||
});
|
||||
|
||||
it('still validates an append that carries at: (to + a line are all it needs)', () => {
|
||||
const md = ['```nc:append to:setup/index.ts at:nanoclaw:setup-steps', " codex: () => import('./codex.js'),", '```'].join('\n');
|
||||
expect(validate(parseDirectives(md))).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('retired directives', () => {
|
||||
it('flags nc:env-sync with a targeted retirement error, not a generic unknown', () => {
|
||||
const probs = validate(parseDirectives(['```nc:env-sync', '```'].join('\n')));
|
||||
expect(probs).toHaveLength(1);
|
||||
expect(probs[0].message).toMatch(/retired/);
|
||||
expect(probs[0].message).toMatch(/data\/env\/env/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('when: guard + multi-field capture', () => {
|
||||
it('parses when: into attrs and lints a guard whose var an earlier prompt defined', () => {
|
||||
const md = ['```nc:prompt mode', 'local or remote', '```', '```nc:prompt server_url when:mode=remote', 'url', '```'].join('\n');
|
||||
const ds = parseDirectives(md);
|
||||
expect(ds[1].attrs.when).toBe('mode=remote');
|
||||
expect(validate(ds)).toEqual([]);
|
||||
});
|
||||
|
||||
it('flags a when: guard whose var no earlier prompt/capture defined', () => {
|
||||
const probs = validate(parseDirectives(['```nc:env-set when:mode=remote', 'X=1', '```'].join('\n')));
|
||||
expect(probs.some((p) => /when:mode=remote references \{\{mode\}\}/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('flags a malformed when: with no =', () => {
|
||||
const md = ['```nc:prompt mode', 'm', '```', '```nc:env-set when:mode', 'X=1', '```'].join('\n');
|
||||
const probs = validate(parseDirectives(md));
|
||||
expect(probs.some((p) => /when:mode must be <var>=<value>/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('registers each capture:<var>=<FIELD> as defined so downstream {{vars}} pass lint', () => {
|
||||
const md = [
|
||||
'```nc:run effect:step capture:platform_id=PLATFORM_ID,owner_handle=ADMIN_ID',
|
||||
'run the step',
|
||||
'```',
|
||||
'```nc:env-set',
|
||||
'P={{platform_id}}',
|
||||
'O={{owner_handle}}',
|
||||
'```',
|
||||
].join('\n');
|
||||
expect(validate(parseDirectives(md))).toEqual([]);
|
||||
});
|
||||
|
||||
it('registers each capture:<var>=<dot-path> (JSON multi-field) var as defined for downstream {{vars}}', () => {
|
||||
const md = [
|
||||
'```nc:run capture:application_id=.id,public_key=.verify_key,owner_handle=.owner.id effect:fetch',
|
||||
'curl -sf https://example/app',
|
||||
'```',
|
||||
'```nc:env-set',
|
||||
'APP={{application_id}}',
|
||||
'PUB={{public_key}}',
|
||||
'OWN={{owner_handle}}',
|
||||
'```',
|
||||
].join('\n');
|
||||
expect(validate(parseDirectives(md))).toEqual([]);
|
||||
});
|
||||
|
||||
it('flags an invalid run capture validate:<re> regex', () => {
|
||||
const md = ['```nc:run capture:app_id=.id effect:fetch validate:^[', 'curl x', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md)).some((p) => /run validate:.*is not a valid regex/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('accepts a valid run capture validate:<re> regex', () => {
|
||||
const md = ['```nc:run capture:app_id=.id effect:fetch validate:^\\d+$', 'curl x', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md))).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('prompt attrs (flags/normalize/reuse)', () => {
|
||||
it('parses flags/normalize/reuse into attrs alongside the var + secret flag', () => {
|
||||
const md = [
|
||||
'```nc:prompt server_url secret validate:^https?:// flags:i normalize:rstrip-slash reuse:IMESSAGE_SERVER_URL',
|
||||
'URL?',
|
||||
'```',
|
||||
].join('\n');
|
||||
const [d] = parseDirectives(md);
|
||||
expect(promptVar(d)).toBe('server_url'); // the var, not `secret`
|
||||
expect(d.attrs.flags).toBe('i');
|
||||
expect(d.attrs.normalize).toBe('rstrip-slash');
|
||||
expect(d.attrs.reuse).toBe('IMESSAGE_SERVER_URL');
|
||||
expect(validate([d])).toEqual([]); // a well-formed prompt with all attrs lints clean
|
||||
});
|
||||
|
||||
it('accepts validate:<re> combined with flags:i (a case-insensitive regex is still valid)', () => {
|
||||
const md = ['```nc:prompt u validate:^https?:// flags:i', 'URL?', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md))).toEqual([]);
|
||||
});
|
||||
|
||||
it('flags an unknown normalize: value', () => {
|
||||
const md = ['```nc:prompt u normalize:uppercase', 'q', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md)).some((p) => /normalize:uppercase must be one of/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('flags a reuse: that is not a valid ENV_KEY', () => {
|
||||
const md = ['```nc:prompt u reuse:not-an-env-key', 'q', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md)).some((p) => /reuse:not-an-env-key must be a valid ENV_KEY/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('flags illegal regex flags:', () => {
|
||||
const md = ['```nc:prompt u validate:^x flags:zzz', 'q', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md)).some((p) => /is not a valid regex/.test(p.message))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// lintReferenceFloor is a WARN-ONLY smell check (never an error, never blocks):
|
||||
// a credentialed (nc:prompt secret) or interactive (nc:run effect:step) skill
|
||||
// should ship a ## Troubleshooting section — the human floor when a live step
|
||||
// misbehaves. It warns when that floor is absent and is silent otherwise.
|
||||
describe('lintReferenceFloor (warn-only reference floor)', () => {
|
||||
it('warns when a secret-bearing skill has no ## Troubleshooting', () => {
|
||||
const md = ['```nc:prompt token secret', 'Paste it.', '```'].join('\n');
|
||||
const warnings = lintReferenceFloor(md);
|
||||
expect(warnings).toHaveLength(1);
|
||||
expect(warnings[0].kind).toBe('reference-floor');
|
||||
expect(warnings[0].message).toMatch(/## Troubleshooting/);
|
||||
});
|
||||
|
||||
it('warns when an interactive effect:step skill has no ## Troubleshooting', () => {
|
||||
const md = ['```nc:run effect:step capture:platform_id=PLATFORM_ID', 'pair', '```'].join('\n');
|
||||
expect(lintReferenceFloor(md)).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('is silent once a ## Troubleshooting section is present', () => {
|
||||
const md = ['```nc:prompt token secret', 'Paste it.', '```', '', '## Troubleshooting', 'Check the logs.'].join('\n');
|
||||
expect(lintReferenceFloor(md)).toEqual([]);
|
||||
});
|
||||
|
||||
it('is silent for a skill with no secret prompt or effect:step (no floor expected)', () => {
|
||||
const md = ['```nc:prompt handle', 'Your handle.', '```', '```nc:env-set', 'H={{handle}}', '```'].join('\n');
|
||||
expect(lintReferenceFloor(md)).toEqual([]);
|
||||
});
|
||||
|
||||
it('never warns on the real credentialed channel skills — they ship a ## Troubleshooting', () => {
|
||||
for (const ch of ['add-signal', 'add-whatsapp', 'add-teams']) {
|
||||
const md = readFileSync(`.claude/skills/${ch}/SKILL.md`, 'utf8');
|
||||
expect(lintReferenceFloor(md)).toEqual([]);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// Grammar diet: the six removed presentation attrs are hard lint ERRORS so
|
||||
// stale authorship fails loudly instead of silently no-oping. Each error points
|
||||
// at the attr's replacement (validate: regex, question prose, body prose,
|
||||
// document structure, the preceding heading, the surrounding prose).
|
||||
describe('removed presentation attrs are lint errors', () => {
|
||||
it('rejects operator open: — the URL belongs in the body prose', () => {
|
||||
const md = ['```nc:operator open:https://portal.azure.com', 'Visit https://portal.azure.com and click through.', '```'].join('\n');
|
||||
const probs = validate(parseDirectives(md));
|
||||
expect(probs.some((p) => /operator open: was removed — put the URL in the body prose/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('rejects the bare operator gate flag — the barrier is structure-derived', () => {
|
||||
const md = ['```nc:operator gate', 'Finish the UI steps.', '```'].join('\n');
|
||||
const probs = validate(parseDirectives(md));
|
||||
expect(probs.some((p) => /operator gate was removed — the human barrier is derived from document structure/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('rejects prompt min: — length is regex-encoded now', () => {
|
||||
const md = ['```nc:prompt app_password secret min:20', 'Paste the client secret.', '```'].join('\n');
|
||||
const probs = validate(parseDirectives(md));
|
||||
expect(probs.some((p) => /prompt min: was removed — encode the length in validate:/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('rejects prompt error: — the miss message derives from the question prose', () => {
|
||||
const md = ['```nc:prompt token error:bad-token', 'Paste the token.', '```'].join('\n');
|
||||
const probs = validate(parseDirectives(md));
|
||||
expect(probs.some((p) => /prompt error: was removed — the validation-miss message derives from the question prose/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('rejects label: on any directive — labels are heading-derived only', () => {
|
||||
const md = ['```nc:run effect:build label:build', 'pnpm run build', '```'].join('\n');
|
||||
const probs = validate(parseDirectives(md));
|
||||
expect(probs.some((p) => /label: was removed — step labels derive from the preceding heading/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('rejects on-fail: on any directive — the hint is always the surrounding prose', () => {
|
||||
const md = ['```nc:run effect:test on-fail:rerun', 'pnpm test', '```'].join('\n');
|
||||
const probs = validate(parseDirectives(md));
|
||||
expect(probs.some((p) => /on-fail: was removed — the failure hint is always the surrounding prose/.test(p.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('still accepts a plain operator block (body-only, no attrs)', () => {
|
||||
const md = ['```nc:prompt bot', 'Bot?', '```', '```nc:operator', 'Open @{{bot}} and press Start.', '```'].join('\n');
|
||||
expect(validate(parseDirectives(md))).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// lintGateAmbiguity is a WARN-ONLY check (never an error, never blocks): an
|
||||
// UNGUARDED operator followed by when:-guarded directives spanning more than
|
||||
// one branch value keys its natural-barrier decision off a directive that may
|
||||
// be runtime-skipped — the static policy cannot know which branch runs.
|
||||
describe('lintGateAmbiguity (warn-only unguarded-operator/multi-branch)', () => {
|
||||
const branchy = [
|
||||
'```nc:prompt mode', 'local or remote?', '```',
|
||||
'```nc:operator', 'Get ready.', '```',
|
||||
'```nc:prompt server_url when:mode=remote', 'URL?', '```',
|
||||
'```nc:run effect:external when:mode=local', './configure.sh', '```',
|
||||
].join('\n');
|
||||
|
||||
it('warns on an unguarded operator followed by guards spanning two branch values', () => {
|
||||
const warnings = lintGateAmbiguity(parseDirectives(branchy));
|
||||
expect(warnings).toHaveLength(1);
|
||||
expect(warnings[0].kind).toBe('gate-ambiguity');
|
||||
expect(warnings[0].line).toBe(4); // the operator's opening fence
|
||||
expect(warnings[0].message).toMatch(/mode=remote/);
|
||||
expect(warnings[0].message).toMatch(/mode=local/);
|
||||
});
|
||||
|
||||
it('the warning is not a validate() error — the skill still lints clean', () => {
|
||||
expect(validate(parseDirectives(branchy))).toEqual([]);
|
||||
});
|
||||
|
||||
it('is silent when the operator itself is guarded (mutually-exclusive branches gate on their own next action)', () => {
|
||||
const md = [
|
||||
'```nc:prompt mode', 'local or remote?', '```',
|
||||
'```nc:operator when:mode=local', 'Get ready.', '```',
|
||||
'```nc:prompt server_url when:mode=remote', 'URL?', '```',
|
||||
'```nc:run effect:external when:mode=local', './configure.sh', '```',
|
||||
].join('\n');
|
||||
expect(lintGateAmbiguity(parseDirectives(md))).toEqual([]);
|
||||
});
|
||||
|
||||
it('is silent when the following guards all share one branch value', () => {
|
||||
const md = [
|
||||
'```nc:prompt mode', 'local or remote?', '```',
|
||||
'```nc:operator', 'Get ready.', '```',
|
||||
'```nc:prompt server_url when:mode=remote', 'URL?', '```',
|
||||
'```nc:prompt api_key when:mode=remote', 'Key?', '```',
|
||||
].join('\n');
|
||||
expect(lintGateAmbiguity(parseDirectives(md))).toEqual([]);
|
||||
});
|
||||
|
||||
it('stops scanning at the first unguarded directive (it always runs — no ambiguity past it)', () => {
|
||||
const md = [
|
||||
'```nc:prompt mode', 'local or remote?', '```',
|
||||
'```nc:operator', 'Get ready.', '```',
|
||||
'```nc:run effect:build', 'pnpm run build', '```',
|
||||
'```nc:prompt server_url when:mode=remote', 'URL?', '```',
|
||||
'```nc:run effect:external when:mode=local', './configure.sh', '```',
|
||||
].join('\n');
|
||||
expect(lintGateAmbiguity(parseDirectives(md))).toEqual([]);
|
||||
});
|
||||
|
||||
it('never warns on the in-tree channel skills (none author the pattern)', () => {
|
||||
for (const ch of ['add-slack', 'add-discord', 'add-telegram', 'add-teams', 'add-whatsapp', 'add-signal', 'add-imessage']) {
|
||||
const md = readFileSync(`.claude/skills/${ch}/SKILL.md`, 'utf8');
|
||||
expect(lintGateAmbiguity(parseDirectives(md))).toEqual([]);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -1,420 +0,0 @@
|
||||
// Extract `nc:` skill directives embedded in a SKILL.md.
|
||||
//
|
||||
// A fenced code block whose info-string starts with `nc:` is a load-bearing
|
||||
// directive; every other fence (and all prose) is the human floor the parser
|
||||
// ignores. That is the whole "two readers, one document" property: an agent
|
||||
// applies the prose, a tool applies the directives, and anything the tool
|
||||
// can't handle degrades to the prose beside it. This is the seed for both the
|
||||
// conformance linter and the deterministic applier.
|
||||
//
|
||||
// Grammar, derived from add-slack:
|
||||
//
|
||||
// ```nc:<directive> <arg>... [key:value]...
|
||||
// <body line>
|
||||
// ```
|
||||
//
|
||||
// `prompt` only *acquires* a value and binds it to a name; a separate directive
|
||||
// *applies* it, referenced as `{{name}}`. That keeps "ask the human" decoupled
|
||||
// from "what you do with the answer" (env, ncl, the OneCLI vault, a file).
|
||||
//
|
||||
// copy [from-branch:<b>] body: `PATH` (src==dst) or `SRC -> DST` overwrite
|
||||
// append to:<file> [at:<marker>] body: line(s) to add skip if present
|
||||
// dep [manager:pnpm] body: `pkg@<exact-semver>` line(s) reinstall no-op
|
||||
// run [effect:build|test|fetch|external|wire|restart|step|check] [capture:<spec>] re-runnable
|
||||
// body: shell command(s). {{vars}} are substituted in. effect:wire runs
|
||||
// `ncl …` to wire collected input (no undo — the rows it creates are user
|
||||
// runtime data, not reversed on skill remove). effect:restart restarts the
|
||||
// service so following `ncl` runs reach it; a caller that owns the restart
|
||||
// (rebuild, or a setup that restarts once) skips it via ApplyOptions.
|
||||
// skipEffects. capture:<var> binds the command's stdout into {{var}} (twin
|
||||
// of prompt) — e.g. resolve an id from an API and feed it to a later step.
|
||||
// capture:<var>=<dot-path>[,<var2>=<dot-path2>…] parses the stdout as JSON
|
||||
// and binds each var to its jq-style dot-path (.id, .owner.id), so ONE API
|
||||
// call resolves several values at once. validate:<re> shape-guards each
|
||||
// captured value (e.g. validate:^discord:); a mismatch bounces the run to
|
||||
// an agent (a command's output has no human to re-prompt — unlike prompt).
|
||||
// effect:step runs a long-running, operator-interactive step (a pairing
|
||||
// code, a QR device-link) through the streaming exec: its
|
||||
// `=== NANOCLAW SETUP: … ===` status blocks render to the operator live and
|
||||
// `capture:<var>=<FIELD>[,<var2>=<FIELD2>…]` binds the terminal block's
|
||||
// named fields into {{vars}} (multi-valued, structured twin of stdout
|
||||
// capture). Degrades to an agent when no streaming exec is wired.
|
||||
// effect:check runs the body as a shell PREDICATE (a precondition gate):
|
||||
// it mutates nothing (no journal, no capture). A zero exit passes silently;
|
||||
// a non-zero exit bounces to an agent (degrade, not crash) and, via the
|
||||
// run-health gate, blocks the dangerous side effects that follow it (a
|
||||
// restart, a pairing/QR step, a wire). An unresolved {{var}} defers.
|
||||
// prompt <var> [secret] [validate:<re>] [flags:<re-flags>]
|
||||
// [normalize:trim|rstrip-slash|lower] [reuse:<ENV_KEY>]
|
||||
// body: the question → binds {{var}} skip if satisfied
|
||||
// validate:<re> is a regex enforced AT BIND for EVERY value — `inputs` and
|
||||
// interactive answers alike (e.g. validate:^xoxb- to require a Slack bot
|
||||
// token); a mismatch leaves the var unbound and records a deferred entry.
|
||||
// A minimum length is regex-encoded (e.g. validate:^.{20,}$).
|
||||
// flags:<re-flags> are regex flags applied to validate (e.g. flags:i → a
|
||||
// case-insensitive scheme match). normalize:<how> deterministically
|
||||
// transforms the value AT BIND, before validate — for BOTH `inputs` and
|
||||
// interactive answers — one of trim | rstrip-slash | lower.
|
||||
// reuse:<ENV_KEY> lets a re-run offer an existing .env value for a credential
|
||||
// a HELPER SCRIPT owns (written by effect:external, not nc:env-set) — the
|
||||
// masked reuse offer the env-set→ENV_KEY inference can't otherwise see.
|
||||
// operator body: instructions for the human operator output-only
|
||||
// The SKILL.md is addressed to the coding agent; `operator` delineates the
|
||||
// parts meant for the HUMAN (e.g. clicking through the Slack UI). Lead it
|
||||
// with agent-facing prose like "Tell the user:" so the agent relays it;
|
||||
// the engine renders the body to the operator ({{vars}} substituted in).
|
||||
// The block carries NO presentation attrs: a URL to visit lives in the
|
||||
// body prose (a consumer may offer to open it), and whether a consumer
|
||||
// pauses for confirmation before the next side effect is derived from
|
||||
// document structure (scripts/skill-policy.ts), never authored here.
|
||||
// env-set body: `KEY=value` ({{var}} allowed) set-if-absent
|
||||
// json-merge into:<file> key:<field> body: a JSON object push-if-absent
|
||||
//
|
||||
// `append` without `at:` adds to EOF; with `at:<marker>` it inserts before the
|
||||
// `// <<< <marker>` closing line of a dormant marker region (see setup/index.ts).
|
||||
// `json-merge` reads an array-of-objects JSON file and pushes the body object
|
||||
// unless an element already has body[key]===element[key] (idempotent by key).
|
||||
//
|
||||
// Any directive may carry `when:<var>=<value>` — a guard evaluated against an
|
||||
// earlier prompt/capture var. If it doesn't match (including the var being
|
||||
// unresolved), the directive is skipped — a guarded prompt is skipped, never
|
||||
// deferred — so one skill can express mutually-exclusive branches (e.g. a local
|
||||
// vs remote install mode) in document order while still running fully
|
||||
// programmatically from `inputs`.
|
||||
//
|
||||
// Removed presentation attrs — `min:`/`error:` on prompt, `open:`/`gate` on
|
||||
// operator, `label:`/`on-fail:` on any directive — are lint ERRORS, so stale
|
||||
// authorship fails loudly instead of silently no-oping. Their jobs moved:
|
||||
// length checks into validate: regexes, miss messages derive from the question
|
||||
// prose, URLs live in the operator body, gating and step labels derive from
|
||||
// document structure (scripts/skill-policy.ts / the preceding heading), and the
|
||||
// failure hint is always the surrounding prose.
|
||||
//
|
||||
// Usage: pnpm exec tsx scripts/skill-directives.ts <SKILL.md>
|
||||
|
||||
import { readFileSync, existsSync, statSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
|
||||
export interface Directive {
|
||||
kind: string;
|
||||
args: string[]; // positional bare tokens, e.g. prompt's variable name
|
||||
attrs: Record<string, string | true>; // key:value tokens
|
||||
body: string[];
|
||||
line: number; // 1-based line of the opening fence
|
||||
}
|
||||
|
||||
export interface Problem {
|
||||
line: number;
|
||||
kind: string;
|
||||
message: string;
|
||||
}
|
||||
|
||||
const FENCE = /^```(\S.*)?$/;
|
||||
const EXACT_SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
|
||||
const VAR_REF = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
|
||||
const KNOWN = new Set(['copy', 'append', 'dep', 'run', 'prompt', 'operator', 'env-set', 'json-merge']);
|
||||
// Retired directives get a targeted lint error (not just "unknown") so an
|
||||
// author knows the removal was deliberate and what to do instead.
|
||||
const RETIRED: Record<string, string> = {
|
||||
'env-sync': 'nc:env-sync was retired — nothing reads the data/env/env mirror (and it copied live tokens); delete the fence, the adapter reads .env directly',
|
||||
};
|
||||
const PROMPT_FLAGS = new Set(['secret']);
|
||||
|
||||
export function parseDirectives(markdown: string): Directive[] {
|
||||
const lines = markdown.split('\n');
|
||||
const out: Directive[] = [];
|
||||
let i = 0;
|
||||
while (i < lines.length) {
|
||||
const info = lines[i].match(FENCE)?.[1]?.trim();
|
||||
if (info === undefined) {
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
// A fence opens here; consume to its closing fence either way.
|
||||
let j = i + 1;
|
||||
const body: string[] = [];
|
||||
while (j < lines.length && !FENCE.test(lines[j])) {
|
||||
body.push(lines[j]);
|
||||
j++;
|
||||
}
|
||||
if (info.startsWith('nc:')) {
|
||||
const [tag, ...rest] = info.split(/\s+/);
|
||||
const args: string[] = [];
|
||||
const attrs: Record<string, string | true> = {};
|
||||
for (const tok of rest) {
|
||||
const eq = tok.indexOf(':');
|
||||
if (eq > 0) attrs[tok.slice(0, eq)] = tok.slice(eq + 1);
|
||||
else args.push(tok);
|
||||
}
|
||||
out.push({
|
||||
kind: tag.slice('nc:'.length),
|
||||
args,
|
||||
attrs,
|
||||
body: body.map((l) => l.trim()).filter(Boolean),
|
||||
line: i + 1,
|
||||
});
|
||||
}
|
||||
i = j + 1; // skip past the closing fence (directive or plain code block)
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/** The variable a `prompt` binds (the first positional that isn't a flag). */
|
||||
export function promptVar(d: Directive): string | undefined {
|
||||
return d.args.find((a) => !PROMPT_FLAGS.has(a));
|
||||
}
|
||||
|
||||
/**
|
||||
* The variable name(s) a `run capture:<spec>` binds. `capture:dm_channel` →
|
||||
* `['dm_channel']` (stdout form); `capture:platform_id=PLATFORM_ID,owner=ACCOUNT`
|
||||
* → `['platform_id','owner']` (effect:step field form).
|
||||
*/
|
||||
export function captureVars(spec: string): string[] {
|
||||
if (!spec.includes('=')) return [spec];
|
||||
return spec
|
||||
.split(',')
|
||||
.map((pair) => pair.slice(0, pair.indexOf('=')).trim())
|
||||
.filter(Boolean);
|
||||
}
|
||||
|
||||
/** `{{var}}` names referenced anywhere in a directive's body. */
|
||||
function referencedVars(d: Directive): string[] {
|
||||
const found: string[] = [];
|
||||
for (const line of d.body) for (const m of line.matchAll(VAR_REF)) found.push(m[1]);
|
||||
return found;
|
||||
}
|
||||
|
||||
/**
|
||||
* The resolved `chat` core version from our lockfile — the single source of
|
||||
* truth a `@chat-adapter/*` adapter pin must match (the adapter and the core
|
||||
* move in lockstep). Reads the root importer's direct `chat` dependency, whose
|
||||
* `specifier`/`version` pair is unique to importer deps (transitive entries in
|
||||
* the packages section have no `specifier`). Returns undefined if not found.
|
||||
*/
|
||||
export function resolveChatCoreVersion(root: string): string | undefined {
|
||||
let lock = '';
|
||||
try {
|
||||
lock = readFileSync(join(root, 'pnpm-lock.yaml'), 'utf8');
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
const m = lock.match(/\n\s+chat:\n\s+specifier:[^\n]*\n\s+version:\s*([0-9][^\s(]*)/);
|
||||
return m?.[1];
|
||||
}
|
||||
|
||||
export function validate(directives: Directive[], ctx?: { chatVersion?: string }): Problem[] {
|
||||
const problems: Problem[] = [];
|
||||
const defined = new Set<string>();
|
||||
const flag = (d: Directive, message: string) => problems.push({ line: d.line, kind: d.kind, message });
|
||||
for (const d of directives) {
|
||||
if (RETIRED[d.kind]) flag(d, RETIRED[d.kind]);
|
||||
else if (!KNOWN.has(d.kind)) flag(d, `unknown directive nc:${d.kind}`);
|
||||
switch (d.kind) {
|
||||
case 'dep':
|
||||
for (const spec of d.body) {
|
||||
const at = spec.lastIndexOf('@');
|
||||
const name = at > 0 ? spec.slice(0, at) : spec;
|
||||
const version = at > 0 ? spec.slice(at + 1) : '';
|
||||
if (!EXACT_SEMVER.test(version)) flag(d, `dep "${spec}" must pin an exact semver (no ranges/latest)`);
|
||||
// A @chat-adapter/* adapter must match the chat core version in our
|
||||
// lockfile — the family moves together. This catches pin drift (the
|
||||
// 4.27.0-vs-chat@4.26.0 mismatch) at lint time.
|
||||
if (ctx?.chatVersion && name.startsWith('@chat-adapter/') && version !== ctx.chatVersion) {
|
||||
flag(d, `${name} pinned ${version} but our chat core is ${ctx.chatVersion} — a @chat-adapter/* adapter must match the chat package`);
|
||||
}
|
||||
}
|
||||
break;
|
||||
case 'append':
|
||||
if (!d.attrs.to) flag(d, 'append requires to:<file>');
|
||||
if (d.body.length === 0) flag(d, 'append requires a line to add');
|
||||
break;
|
||||
case 'copy':
|
||||
if (d.body.length === 0) flag(d, 'copy requires at least one path');
|
||||
break;
|
||||
case 'json-merge': {
|
||||
if (!d.attrs.into) flag(d, 'json-merge requires into:<json-file>');
|
||||
if (!d.attrs.key) flag(d, 'json-merge requires key:<field>');
|
||||
if (d.body.length === 0) {
|
||||
flag(d, 'json-merge requires a JSON object in its body');
|
||||
} else {
|
||||
let obj: unknown;
|
||||
try {
|
||||
obj = JSON.parse(d.body.join('\n'));
|
||||
} catch {
|
||||
flag(d, 'json-merge body must be a single parseable JSON object');
|
||||
break;
|
||||
}
|
||||
if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
|
||||
flag(d, 'json-merge body must be a single JSON object (not an array or scalar)');
|
||||
} else if (typeof d.attrs.key === 'string' && !(d.attrs.key in obj)) {
|
||||
flag(d, `json-merge body has no "${d.attrs.key}" field to match on`);
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'prompt': {
|
||||
if (!promptVar(d)) flag(d, 'prompt requires a variable name, e.g. `nc:prompt token`');
|
||||
if (d.body.length === 0) flag(d, 'prompt requires a question in its body');
|
||||
const flags = typeof d.attrs.flags === 'string' ? d.attrs.flags : undefined;
|
||||
if (typeof d.attrs.validate === 'string') {
|
||||
try {
|
||||
new RegExp(d.attrs.validate, flags);
|
||||
} catch {
|
||||
flag(d, `prompt validate:${d.attrs.validate}${flags ? ` flags:${flags}` : ''} is not a valid regex`);
|
||||
}
|
||||
} else if (flags !== undefined) {
|
||||
// flags without validate: still verify they're legal regex flags.
|
||||
try {
|
||||
new RegExp('', flags);
|
||||
} catch {
|
||||
flag(d, `prompt flags:${flags} are not valid regex flags`);
|
||||
}
|
||||
}
|
||||
// Removed presentation attrs — reject loudly (they would silently no-op).
|
||||
if (d.attrs.min !== undefined) {
|
||||
flag(d, 'prompt min: was removed — encode the length in validate:, e.g. min:20 → validate:^.{20,}$');
|
||||
}
|
||||
if (d.attrs.error !== undefined) {
|
||||
flag(d, 'prompt error: was removed — the validation-miss message derives from the question prose');
|
||||
}
|
||||
if (typeof d.attrs.normalize === 'string' && !['trim', 'rstrip-slash', 'lower'].includes(d.attrs.normalize)) {
|
||||
flag(d, `prompt normalize:${d.attrs.normalize} must be one of trim|rstrip-slash|lower`);
|
||||
}
|
||||
if (typeof d.attrs.reuse === 'string' && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(d.attrs.reuse)) {
|
||||
flag(d, `prompt reuse:${d.attrs.reuse} must be a valid ENV_KEY`);
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'operator':
|
||||
if (d.body.length === 0) flag(d, 'operator requires instructions for the human in its body');
|
||||
// Removed presentation attrs — reject loudly (they would silently no-op).
|
||||
if (d.attrs.open !== undefined) {
|
||||
flag(d, 'operator open: was removed — put the URL in the body prose (a consumer offers to open it)');
|
||||
}
|
||||
if (d.args.includes('gate') || d.attrs.gate !== undefined) {
|
||||
flag(d, 'operator gate was removed — the human barrier is derived from document structure, never authored');
|
||||
}
|
||||
break;
|
||||
}
|
||||
// Removed on every directive: label: (labels are heading-derived only) and
|
||||
// on-fail: (the failure hint is always the surrounding prose).
|
||||
if (d.attrs.label !== undefined) {
|
||||
flag(d, 'label: was removed — step labels derive from the preceding heading');
|
||||
}
|
||||
if (d.attrs['on-fail'] !== undefined) {
|
||||
flag(d, 'on-fail: was removed — the failure hint is always the surrounding prose');
|
||||
}
|
||||
// A consumer can only reference a variable an earlier prompt captured, or an
|
||||
// earlier `run capture:<var>` bound from a command's output.
|
||||
for (const ref of referencedVars(d)) {
|
||||
if (!defined.has(ref)) flag(d, `references {{${ref}}} but no earlier nc:prompt or nc:run capture defined it`);
|
||||
}
|
||||
// A `when:<var>=<value>` guard references an earlier-defined var by bare name.
|
||||
if (typeof d.attrs.when === 'string') {
|
||||
const eq = d.attrs.when.indexOf('=');
|
||||
if (eq < 1) {
|
||||
flag(d, `when:${d.attrs.when} must be <var>=<value>`);
|
||||
} else {
|
||||
const wvar = d.attrs.when.slice(0, eq).trim();
|
||||
if (!defined.has(wvar)) flag(d, `when:${d.attrs.when} references {{${wvar}}} but no earlier nc:prompt or nc:run capture defined it`);
|
||||
}
|
||||
}
|
||||
if (d.kind === 'prompt') {
|
||||
const v = promptVar(d);
|
||||
if (v) defined.add(v);
|
||||
}
|
||||
// capture:<var> binds stdout; capture:<var>=<FIELD>,… binds step block fields.
|
||||
if (d.kind === 'run' && typeof d.attrs.capture === 'string') {
|
||||
for (const v of captureVars(d.attrs.capture)) defined.add(v);
|
||||
}
|
||||
// A run's capture validate:<re> (the stdout shape-guard) must be a valid regex.
|
||||
if (d.kind === 'run' && typeof d.attrs.validate === 'string') {
|
||||
try {
|
||||
new RegExp(d.attrs.validate);
|
||||
} catch {
|
||||
flag(d, `run validate:${d.attrs.validate} is not a valid regex`);
|
||||
}
|
||||
}
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
/**
|
||||
* A WARN-ONLY reference-floor check — never an error, never blocks a build. A
|
||||
* credentialed or interactive skill (one that prompts for a `secret`, or runs an
|
||||
* `nc:run effect:step` — a pairing code, a QR device-link) should ship a
|
||||
* `## Troubleshooting` section: the human floor a reader scrolls to when the live
|
||||
* step misbehaves. Missing it is a smell, not a failure — the skill still applies
|
||||
* cleanly — so this returns a warning the CLI prints but never exits non-zero on,
|
||||
* keeping it strictly advisory. Returns [] when no secret/step is present (no
|
||||
* floor is expected) or a `## Troubleshooting` heading already exists.
|
||||
*/
|
||||
export function lintReferenceFloor(markdown: string): Problem[] {
|
||||
const directives = parseDirectives(markdown);
|
||||
const isFloorBearing = (d: Directive): boolean =>
|
||||
(d.kind === 'prompt' && d.args.includes('secret')) || (d.kind === 'run' && d.attrs.effect === 'step');
|
||||
const anchor = directives.find(isFloorBearing);
|
||||
if (!anchor) return []; // no credential / interactive step ⇒ no floor expected
|
||||
const hasTroubleshooting = markdown.split('\n').some((l) => /^##\s+Troubleshooting\s*$/.test(l.trim()));
|
||||
if (hasTroubleshooting) return [];
|
||||
return [{
|
||||
line: anchor.line,
|
||||
kind: 'reference-floor',
|
||||
message: 'a credentialed/interactive skill should carry a ## Troubleshooting section (the human floor when a live step misbehaves)',
|
||||
}];
|
||||
}
|
||||
|
||||
/**
|
||||
* A WARN-ONLY gate-ambiguity check — never an error, never blocks a build. The
|
||||
* driver's natural-barrier policy (scripts/skill-policy.ts) keys an operator's
|
||||
* pause decision off the next guard-compatible directive; an UNGUARDED operator
|
||||
* treats every following directive as compatible, so when the directives
|
||||
* immediately after it are `when:`-guarded and span more than one branch value,
|
||||
* the static decision keys off a directive that may be runtime-skipped (e.g.
|
||||
* unguarded operator → `prompt when:mode=remote` → `run when:mode=local`:
|
||||
* policy says no-confirm, but at runtime mode=local skips the prompt). No
|
||||
* in-tree skill authors this; warn so new authorship guards the operator (or
|
||||
* restructures) instead of getting a silently wrong barrier. The scan stops at
|
||||
* the first unguarded directive — that one always runs, so no ambiguity past it.
|
||||
*/
|
||||
export function lintGateAmbiguity(directives: Directive[]): Problem[] {
|
||||
const problems: Problem[] = [];
|
||||
for (let i = 0; i < directives.length; i++) {
|
||||
const d = directives[i];
|
||||
if (d.kind !== 'operator' || typeof d.attrs.when === 'string') continue;
|
||||
const branches = new Set<string>();
|
||||
for (let j = i + 1; j < directives.length; j++) {
|
||||
const g = directives[j].attrs.when;
|
||||
if (typeof g !== 'string') break;
|
||||
branches.add(g);
|
||||
}
|
||||
if (branches.size > 1) {
|
||||
problems.push({
|
||||
line: d.line,
|
||||
kind: 'gate-ambiguity',
|
||||
message: `unguarded nc:operator followed by when:-guarded directives spanning ${branches.size} branch values (${[...branches].join(', ')}) — the barrier decision may key off a runtime-skipped directive; guard the operator or restructure`,
|
||||
});
|
||||
}
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
// CLI
|
||||
if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
|
||||
let path = process.argv[2];
|
||||
if (!path) {
|
||||
console.error('usage: pnpm exec tsx scripts/skill-directives.ts <skillDir|SKILL.md>');
|
||||
process.exit(2);
|
||||
}
|
||||
if (existsSync(path) && statSync(path).isDirectory()) path = join(path, 'SKILL.md');
|
||||
const md = readFileSync(path, 'utf8');
|
||||
const directives = parseDirectives(md);
|
||||
const problems = validate(directives, { chatVersion: resolveChatCoreVersion(process.cwd()) });
|
||||
// Warnings (gate ambiguity, reference floor) are advisory only — printed for
|
||||
// the author, never folded into the exit code (a smell, not a gate). Exit
|
||||
// stays driven solely by `validate` problems.
|
||||
const warnings = [...lintGateAmbiguity(directives), ...lintReferenceFloor(md)];
|
||||
for (const w of warnings) console.error(`warning: ${w.kind} (line ${w.line}): ${w.message}`);
|
||||
console.log(JSON.stringify({ directives, problems, warnings }, null, 2));
|
||||
process.exit(problems.length ? 1 : 0);
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user