ghosty-acp 0.0.6 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghosty-acp",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Conecta tu editor a un agente ACP remoto. Puente entre entrada/salida estándar y WebSocket, sin dependencias.",
   "type": "module",
   "bin": {

package/skills/README.md

@@ -11,7 +11,7 @@ npx skills add https://ghosty.studio
 
 | Skill | What for |
 |---|---|
-| `ghosty-agent` | configure a Ghosty Studio agent through its API: identity, model, files, skills, MCP servers |
+| `ghosty-agent` | configure, test and chat with a Ghosty Studio agent with the `ghosty` CLI (its REST API as a fallback): identity, model, files, skills, MCP servers, databases, demos |
 | `ghosty-docs` | read the Ghosty docs from an agent: markdown pages, `llms.txt`, the docs MCP server |
 | `ghosty-acp` | connect Zed, VS Code, JetBrains or Neovim to the agent over ACP |
 | `ghosty-recipe` | write or review an agent recipe (`.recipe.yaml`) to upload in the creator |

package/skills/ghosty-agent/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ghosty-agent
-description: Configure a Ghosty Studio agent (identity/system prompt, model, knowledge files in its machine, skills, custom MCP servers) through its REST API using the agent token. Use when the user asks to set up, tune, teach, or connect their Ghosty agent, or mentions ghosty.studio.
+description: Configure, test and chat with a Ghosty Studio agent (identity/system prompt, model, knowledge files in its machine, skills, custom MCP servers) with the `ghosty` CLI, or its REST API as a fallback. Use when the user asks to set up, tune, teach, test or connect their Ghosty agent, or mentions ghosty.studio.
 license: MIT
-compatibility: Needs curl or any HTTP client and network access to https://www.ghosty.studio
+compatibility: Needs Node 22+ (for npx @ghostystudio/cli) or curl, and network access to https://www.ghosty.studio
 metadata:
   author: ghosty-studio
-  version: "1.2"
+  version: "1.11"
 ---
 
 # Configure a Ghosty Studio agent
@@ -13,45 +13,103 @@ metadata:
 A Ghosty Studio agent runs on its own isolated machine (disk, terminal, memory). You configure it
 over HTTPS with **its own token**; nothing runs on the user's computer.
 
-## Setup (once)
+## Setup (once): use the CLI
 
-1. Ask the user for the agent id and token. Both are in Ghosty Studio → **Agentes → their agent →
-   Conexión con tu editor → Generar token** (token looks like `gat_…`; id is in the page URL
-   `/app/agents/<id>`).
-2. Keep them in env vars, never in command arguments or committed files:
+Run it with `npx -y @ghostystudio/cli <command>` (or `ghosty <command>` if installed globally).
+Always pass `--json` and read stdout as JSON; notices go to stderr.
+
+**Sign in (the user just opens a link):**
 
 ```bash
-export GHOSTY_AGENT_ID="<id>"
-export GHOSTY_AGENT_TOKEN="gat_…"
+npx -y @ghostystudio/cli login --json
+# first line: {"event":"login_url","url":"…"}  → show this link to the user and ask them to open it
+# then:       {"event":"logged_in","email":"…"} → done; the session is saved and renews itself
 ```
 
-Base URL: `https://www.ghosty.studio/api/v2/agents/$GHOSTY_AGENT_ID`. Every call:
-`-H "Authorization: Bearer $GHOSTY_AGENT_TOKEN"`. Wrong token or id → `404` (do not retry).
+Run it in the background or with a long timeout: it waits (up to 5 min) for the user to sign in
+in their browser. Any command exiting with code **3** means "not signed in" → run `login` again.
+
+**Remote box, SSH or CI?** `login` switches by itself to a device code (`--device` forces it): the
+`login_url` line then carries `"code"` too; pass the link to the user and tell them to check the
+code matches before authorizing.
+
+**Several accounts** (the user's and a customer's)? `--profile <name>` (or `GHOSTY_PROFILE`) keeps
+a separate saved session per name: `ghosty --profile cliente login --json`, then the same
+`--profile` on every command.
+
+Then `ghosty agents ls --json` gives the agent ids.
+
+**No browser available** (CI, remote box)? Ask the user for the agent token (Ghosty Studio →
+**Agentes → their agent → Conexión con tu editor → Generar token**, looks like `gat_…`) and put it
+in the environment, never in arguments or committed files: `export GHOSTY_TOKEN="gat_…"`. It
+reaches only that agent (no `agents ls`, no `chat`).
+
+Exit codes: `0` ok · `1` API error (read the message, don't retry blindly) · `2` usage error
+(check `--help`) · `3` not signed in.
+
+### Fallback: raw HTTP
+
+If Node is not available, use curl with the agent token. Base URL:
+`https://www.ghosty.studio/api/v2/agents/$GHOSTY_AGENT_ID`, header
+`Authorization: Bearer $GHOSTY_AGENT_TOKEN`. Wrong token or id → `404` (do not retry). Shapes in
+`references/api.md`.
+
+**Agent hosted on EasyBits** (`ghosty-lite` / `goose` template)? Same contract for `/prompt`,
+`/files`, `/skills/{slug}`, `/mcp`, `/restart`: base `https://www.easybits.cloud/api/v2/agents/$AGENT_ID`
+with `Authorization: Bearer $EASYBITS_API_KEY` (the owner's key, not an agent token). Identity
+there is `PATCH /` with `{ systemPrompt, systemPromptMode }` (`replace` = only your prompt).
 
 ## Know the engine first
 
-`GET …?fields=name,engine,model,hasMachine,prompt` before anything else. `hasMachine` decides
-what applies:
+`ghosty agents get <id> --fields name,engine,model,needsRestart,prompt --json` before anything else. Every agent
+has its own machine and disk, so files, skills, MCP and `try` work on all of them. `needsRestart` only
+says how new config gets in:
 
-| `hasMachine` | Engines | You can | Identity (`prompt`) takes effect |
+| `needsRestart` | Engines | Files, skills and MCP take effect | Identity (`prompt`) takes effect |
 |---|---|---|---|
-| `true` | Ghosty · Lite, Goose | everything: files, skills, MCP, `restart`, `try` | on the next conversation, or right away with `POST …/restart` |
-| `false` | Claude, Codex, DeepSeek | `GET`, `PATCH` (name, model, prompt, webSearch, channels) and `try` | on the next conversation; **never call `restart`** (it answers `409`) |
+| `true` | Ghosty · Lite, Goose (ACP) | skills after `ghosty agents restart <id>`; MCP restarts by itself; files right away | on the next conversation, or right away with `restart` |
+| `false` | Claude, Codex, DeepSeek, Gemini (pool) | on the next turn, by themselves | on the next turn; **never call `restart`** (it answers `409 restart_no_aplica`) |
 
-The `PATCH` response carries a `nota` saying which case you are in. Files, skills and MCP on a
-machine-less engine answer `409 agente_sin_maquina`: tell the user and stop.
+The `PATCH` and skill responses carry a `nota` saying which case you are in. (`hasMachine` is
+legacy and always `true`.)
 
 ## What you can do
 
 | User asks | Do |
 |---|---|
-| "set its identity / persona / system prompt" | write it with `references/identity.md`, `PATCH` with `{"prompt": "..."}`, then `restart` only if `hasMachine` |
-| "change the model" | `GET` first (lists `models`), then `PATCH {"model": "<id>"}` (restarts by itself) |
-| "give it these files / documents / knowledge" | `PUT …/files/<name>` with raw bytes, one call per file |
-| "install / teach it a skill" | `PUT …/skills/<slug>` with the SKILL.md markdown (+ assets), then `POST …/restart` |
-| "connect it to this MCP server" | `PUT …/mcp` with the full list of servers (it replaces; restarts by itself) |
-| "what does it have?" | `GET …?full=1` → prompt, model, files, skills, mcp (`?fields=` to read just some) |
-| "does it work? / test it" | `POST …/try {"text": "…"}` → the agent's answer (see Verify) |
+| "create a new agent" | `ghosty agents create --name <name> [--engine <engine>] [--model <model-id>] [--prompt-file PROMPT.md] [--env K=V,…] --json` → `id`. A model outside the engine answers 400 with the valid list |
+| "set its identity / persona / system prompt" | write it with `references/identity.md` to a file, `ghosty agents set <id> --prompt-file PROMPT.md`, then `ghosty agents restart <id>` only if `needsRestart` |
+| "let it see my Drive / use my connector" | `ghosty agents set <id> --connect google-drive` (owner only; the account must have it connected first). Files are the ones the owner picked in Conectores → Google Drive |
+| "delete this agent" | confirm with the user first, then `ghosty agents rm <id>` (owner only; `409` names the workspace where it is active) |
+| "switch it to another engine" | `ghosty agents set <id> --engine <engine> [--model <model-id>]` (the model belongs to the NEW engine) |
+| "change the model" | `ghosty agents get <id> --json` (lists `models`), then `ghosty agents set <id> --model <model-id>` (restarts by itself) |
+| "make it think more / less" | Ghosty · Lite: `ghosty agents set <id> --env GHOSTY_THINKING_EFFORT=off\|low\|medium\|high\|max`. Codex: `--env FLEET_EFFORT=none\|minimal\|low\|medium\|high\|xhigh\|max` |
+| "give it these files / documents / knowledge" | `ghosty files put <id> <name> --file <local>`, one per file |
+| "install / teach it a skill" | `ghosty skills add <id> <slug> --file SKILL.md` (or just `<slug>` from the catalog: `ghosty skills ls <id>`), then `ghosty agents restart <id>` only if `needsRestart` |
+| "connect it to this MCP server" | `ghosty mcp get <id> --json > servers.json`, add the server, `ghosty mcp set <id> --file servers.json` (replaces; restarts by itself) |
+| "what does it have?" | `ghosty agents get <id> --json` → prompt, model, files, skills, mcp |
+| "does it work? / test it" | `ghosty try <id> "…" --json` → the agent's answer (see Verify) |
+| "talk to it / ask it something" | `ghosty chat <id> "…" --json` → streams `chunk` lines, ends with `done` |
+| "test it as a WhatsApp customer / with a photo / with earlier context" | `ghosty try <id> "…" --waba --session <made-up phone> [--media FILE] [--history FILE --reset] --json` → `sent[]` (what it would send; nothing leaves) |
+| "replay these real conversations" | `ghosty try <id> --replay sample.json --out ./replay [--max N]`; read `./replay/replay.json`; `--resume` if it was cut |
+| "is it configured right? / why does it answer badly?" | `ghosty agents doctor <id> --json` → `checks[]` with `level` (ok/warn/error) and a `fix` command each; exit 1 = something to fix |
+| "why did it fail? / it didn't answer" | `ghosty turns ls <id> --errors --since 24h --json` → failed turns with their `error` |
+| "give it this database / what can it write" | `ghosty dbs ls <id>`, `ghosty dbs tables <id> <db>`, `ghosty dbs grant <id> <db> [--external-write t1,t2]` (tables it may write from WhatsApp/Messenger) |
+| "copy its data from EasyBits" | `ghosty dbs import <id> <db> --from easybits:<db-id> --dry-run` first (needs `EASYBITS_API_KEY`), show the plan, then run without `--dry-run` (`--yes` if replacing rows) |
+| "let it read / send this document" | `ghosty agents docs ls <id>`, `ghosty agents docs grant <id> "<name>" [--write] [--no-deliver]` |
+| "answer with voice notes" | `ghosty agents set <id> --voice elevenlabs:<voice-id>\|kokoro:em_santa --voice-replies auto` |
+| "answer this WhatsApp number" | confirm with the user (real customers), then `ghosty channels whatsapp enable <id> <number> --yes`; `--dry-run` shows the plan |
+| "save my ElevenLabs / MercadoPago key" | never put the key in a command: ask the user to run `ghosty credentials set <provider>` themselves (hidden prompt), or use `--from-env VAR` |
+| "remove this skill" | `ghosty skills rm <id> <slug> --yes` keeps a local copy and returns `restore`; `ghosty skills get <id> <slug>` to back one up first |
+| "how much have I used? / am I out of usage?" | `ghosty usage --json` → `plan.name`, `week.pct` / `month.pct` (0–1), `exhausted` |
+| "let people try it without an account / share a demo" | `ghosty agents demo <id> --slug <name> --on [--vence "YYYY-MM-DDTHH:MM"] [--welcome T] [--starter T] [--chips "a\|b"] --json` → `url`; no flags = status; `--rotate` if the link leaked, `--off` to stop |
+| "what files are in my account?" | `ghosty me files ls [--kind document] --json`; `me files upload <path>`, `me files rm <file-id>` |
+| "clean up the board / archive test cards" | `ghosty board archive <id> --integration X \| --column X \| --before 30d --dry-run` first, then with `--yes` after the user confirms (reversible) |
+| "which conversations does it have?" | `ghosty conversations ls <id> --json`; continue one with `ghosty chat <id> "…" --conversation <conv-id>` |
+| "what's in its database? / fix this row" | `ghosty dbs query <id> <db> "SELECT …" [--arg V]… --json` (read only); `--write` only for a change the user asked for |
+| "stop giving it this database" | `ghosty dbs revoke <id> <db>` (prints the `grant` that undoes it) |
+| "give an agent to each of MY customers (partner)" | not for a normal owner: see https://www.ghosty.studio/docs/cli/partners.md (`ghosty partner --help`) |
+| "have it do X every day / at 9 / remind me" | `ghosty schedule add <id> "…" --at ISO \| --in 30m [--every 12h --until ISO] [--title T]`; each run notifies the user's phone, an answer of exactly `OK` stays silent. `ghosty schedule ls|rm <id>` |
 
 Read `references/api.md` for exact request/response shapes before calling.
 
@@ -67,10 +125,11 @@ Read `references/api.md` for exact request/response shapes before calling.
 - **MCP `PUT` replaces the whole list.** `GET …/mcp` first and send back the existing servers plus
   the new one. Only `https://` URLs for HTTP servers; stdio servers need the binary to exist in the
   agent's machine (Node and Python are there).
-- **Engines without their own machine** (Claude, DeepSeek, Codex) accept `GET`/`PATCH` (identity, model) only; files, skills, MCP and restart answer `409 agente_sin_maquina`. Tell the user and stop; do not retry.
+- **Pool engines** (Claude, Codex, DeepSeek, Gemini) have their own machine too: files, skills and MCP work and enter on the next turn. Only `restart` answers `409 restart_no_aplica` there; skip it.
 - **Restart is not free**: it cuts a turn in progress. Batch changes, restart once at the end.
 - Files go to the agent's working directory; tell the user the agent can `ls` them. Max 10 MB each.
 - Never print the token back to the user or into logs.
+- **Destructive commands need `--yes`** when you run them (no terminal): `agents rm`, `files rm`, `skills rm`, `credentials rm`, `board archive`, `dbs import` over existing rows, `channels whatsapp enable`. Confirm with the user BEFORE adding it; prefer `--dry-run` first where it exists.
 
 ## Verify
 
@@ -86,10 +145,10 @@ exactly what changed, read the answer and tell the user whether it matches:
 | model | `¿Qué modelo eres?` → the label from `models` |
 
 ```bash
-curl -s -X POST "$B/try" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" \
-  -H "Content-Type: application/json" -d '{"text":"¿Quién eres y qué haces?","reset":true}'
+npx -y @ghostystudio/cli try <id> --reset --json
+npx -y @ghostystudio/cli try <id> "¿Quién eres y qué haces?" --json
 ```
 
-`reset: true` starts from a clean memory; use `session` to keep several test threads apart. A
+`--reset` starts from a clean memory; use `--session <name>` to keep several test threads apart. A
 machine that was asleep takes 5–15 s on the first call. Then tell the user in one line what
 changed and what the agent answered.

package/skills/ghosty-agent/references/api.md

@@ -5,9 +5,9 @@ Base: `https://www.ghosty.studio/api/v2/agents/{id}` · Auth: `Authorization: Be
 Full spec: https://www.ghosty.studio/openapi.yaml · Docs: https://www.ghosty.studio/docs/configurar
 
 ## GET /
-Returns `{ id, name, engine, hasMachine, model, models: [{id,label}], prompt, channels, webSearch, mcp }`.
-`hasMachine` (bool) says whether files/skills/MCP/restart exist for this engine.
-Add `?full=1` to also get `files: [{path,size}]` and `skills: [{slug,description,files}]`
+Returns `{ id, name, engine, hasMachine, needsRestart, model, models: [{id,label}], prompt, channels, webSearch, mcp, messengerPages: [{pageId,pageName}], starters, tools: { gs: {name: bool}, extensions: {name: bool} } }`.
+Every agent has its own machine and disk: files, skills and MCP work on all engines. `needsRestart` (bool) is true for ACP engines (Ghosty · Lite, Goose), where new skills enter after `POST /restart`; on pool engines they enter on the next turn. `hasMachine` is legacy and always `true`.
+Add `?full=1` to also get `files: [{path,size}]`, `skills: [{slug,description,files}]` and `extensions: [{name,enabled}]`
 (wakes the machine if asleep). Add `?fields=prompt,model` to get only those keys (`id` always).
 
 ```bash
@@ -15,7 +15,10 @@ curl -s "$B" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN"
 ```
 
 ## PATCH /
-Body: any of `{ "name", "model", "prompt", "webSearch": bool, "channels": { "teams": bool } }`.
+Body: any of `{ "name", "model", "prompt", "webSearch": bool, "channels": { "teams": bool, "web": bool, "whatsapp": bool, "messenger": bool }, "starters": ["…up to 5, ≤80 chars"], "tools": { "gs": { "<name>": bool }, "extensions": { "<name>": bool } } }`.
+`tools.gs` today: `programar_seguimiento` (schedule a future turn), `archivo_enviar` (send a file the agent produced — an https URL — to the person it is talking to: photo/audio/document on WhatsApp and Messenger, a link elsewhere) and `actualizar_identidad` (the agent rewrites or appends to its own prompt — it only works when the owner talks to it from Studio or the Mac app; from Messenger/WhatsApp/Teams the call is refused).
+`tools.canales` decides per channel: `{ "canales": { "messenger": { "actualizar_identidad": false } } }` (channels: `chat` = Studio/Mac app, `teams`, `whatsapp`, `messenger`, `programado`, `prueba`; the GET returns the effective matrix). By default `actualizar_identidad` is only on in `chat`.
+`tools` turns tools off (`false`) or back on (`true`) by name and merges with what is saved. `tools.gs` are the tools gs lends the agent (the GET lists them all with their state); `tools.extensions` are the machine's `config.yaml` extensions (`developer` = shell + files, `todo`, `analyze`, `easybits`…; `?full=1` returns the real list as `extensions`) and changing them restarts the machine. The veto is enforced: an off tool disappears from the list and is refused when called.
 Response: the same as GET plus `aplicado: ["set-prompt", …]` and, after a `prompt` change, `nota`
 telling whether a `restart` applies (machine) or the identity simply enters on the next
 conversation (no machine). `model` restarts the agent.
@@ -38,6 +41,9 @@ curl -s -X PUT "$B/files/precios-2026.pdf" -H "Authorization: Bearer $GHOSTY_AGE
 ## PUT /skills/{slug}  ·  DELETE /skills/{slug}  ·  GET /skills
 Body: `{ "markdown": "<SKILL.md content>", "assets": [{ "name": "scripts/x.py", "contentBase64": "…" }] }`.
 Max 25 MB total. Then `POST /restart` so the agent loads it.
+`GET /skills` also returns `community: [{slug, description, repo, url, license, installed}]` — a curated
+catalog of open-source skills (grill-me, caveman, ponytail, karpathy-guidelines, frontend-design,
+test-driven-development…). Install one with `PUT /skills/{slug}` and body `{ "fromCatalog": true }` (no markdown needed).
 
 ```bash
 jq -n --rawfile md SKILL.md '{markdown:$md}' | \
@@ -52,9 +58,35 @@ Body: `{ "servers": [ …full list… ] }`. Each server is one of:
 
 Names: `a-z 0-9 - _`, max 20 servers. The agent restarts automatically.
 
+## GET /whatsapp  ·  PUT /whatsapp
+Which WhatsApp numbers this agent answers. Numbers belong to the workspace and are paired from Sales
+(`salesUrl`); here you only choose who answers. `PUT {"numbers": ["<id>", …]}` leaves the agent
+answering exactly those (one number → one agent; unchecking mutes it, the pairing stays).
+
+```bash
+curl -s "$B/whatsapp" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN"
+```
+→ `{ numbers: [{id, label, mine, takenByOther}], hasSales, salesUrl }`
+
+## GET /bundle  ·  POST /bundle
+The whole agent as an Eve-style directory (`instructions.md`, `skills/<slug>/SKILL.md`, `knowledge/…`, `mcp.json`),
+as JSON: `{ "layout": "eve", "files": [{ "path", "contentBase64" }] }`. `POST` takes the same shape and imports
+it: `instructions.md` → prompt, `skills/x.md` or `skills/x/SKILL.md` → skills (a frontmatter is added when missing),
+`knowledge/…` → files. Eve's `tools/`, `channels/`, `schedules/` are not executed and come back in `ignorado`.
+
+```bash
+curl -s "$B/bundle" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" > agent.json
+```
+
+## PATCH / — connectors
+`{ "connectors": { "google-drive": {} } }` grants the agent access to that account connector; `null` removes it. Drive also takes `files` (ids) and `clientWrite`. Owner only: `403` with a `gat_` token.
+
+## DELETE /
+Deletes the agent and its machines. Owner only (`403` for an editor or a `gat_` token); `409` if a workspace has it active (the message names it). → `{ deleted: id }`.
+
 ## POST /restart
-→ `{ reiniciado: true }`. Cuts a running turn; disk survives. Only with `hasMachine: true`;
-otherwise `409 agente_sin_maquina`.
+→ `{ reiniciado: true }`. Cuts a running turn; disk survives. Only with `needsRestart: true`;
+otherwise `409 restart_no_aplica` (pool engines load new config on the next turn by themselves).
 
 ## POST /try
 Body: `{ "text": "…", "session"?: "a-z0-9_-", "reset"?: bool }`. One full turn to text, no stream,
@@ -70,5 +102,5 @@ curl -s -X POST "$B/try" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" \
 
 ## Errors
 `400` invalid body (message in `error`) · `404` unknown id/token · `405` wrong method ·
-`409 agente_sin_maquina` files, skills, MCP and restart need an engine with its own machine (Ghosty · Lite or Goose); `GET`/`PATCH` work on every engine ·
+`409 restart_no_aplica` only on `POST /restart` for pool engines (they load new config on the next turn; only Ghosty · Lite and Goose restart). Files, skills, MCP, `GET`/`PATCH` work on every engine: the agent's **bundle** (`instructions.md`, `skills/`, `knowledge/`) lives in Studio (`storage: "bundle"`) and is seeded into the worker's cwd on each turn when it changed; on machines (`storage: "box"`) it is also written to `/data/agent` and `/data/work` ·
 `413` too big · `502` saved but the machine did not take it (retry `POST /restart`).