ghosty-acp 0.0.59 → 0.0.60
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -5,7 +5,7 @@ license: MIT
|
|
|
5
5
|
compatibility: Needs Node 22+ (for npx @ghostystudio/cli) or curl, and network access to https://www.ghosty.studio
|
|
6
6
|
metadata:
|
|
7
7
|
author: ghosty-studio
|
|
8
|
-
version: "1.
|
|
8
|
+
version: "1.80"
|
|
9
9
|
---
|
|
10
10
|
|
|
11
11
|
# Configure a Ghosty Studio agent
|
|
@@ -108,22 +108,30 @@ legacy and always `true`.)
|
|
|
108
108
|
| "turn off / on this skill" | `ghosty skills disable\|enable <id> <slug>` (its own or one of Ghosty's; `skills ls` shows `on`) |
|
|
109
109
|
| "something in Ghosty is broken and I can't fix it", "talk to Ghosty / support" | `ghosty support open --title "<short>" --body "<what, when, what was tried>"` — support answers BY EMAIL; replying to that email adds to the case. `ghosty support ls` / `show <id>` / `reply <id> --body …` to follow up. The case carries the account and agents' recent errors; never paste secrets |
|
|
110
110
|
| "archive / pause this agent for good", "I don't use this agent anymore" | prefer archiving over deleting: `ghosty agents archive <id>` (stops answering everywhere, hidden, nothing deleted; deleted automatically after 7 days). `ghosty agents restore <id>` brings it back as it was; `ghosty agents ls --archived` lists them |
|
|
111
|
+
| "rotate / revoke the agent token", "the gat_ token leaked" | owner session only (a `gat_` token can't rotate itself): `ghosty agents token rotate <id> --yes` prints the new token ONCE on stdout — hand it to the user to store, never echo it into logs; `token revoke <id> --yes` closes the editor channel. On ACP engines it cuts the turn in flight |
|
|
112
|
+
| "teach it a rule for everyone", "from now on don't offer X", "add / turn off a promo" | `ghosty agents memory ls <id> --json`; rule: `memory add <id> "…" [--scope wa]` (travels in every conversation, also with customers), `memory edit <id> <rule-id> "…"`, `memory rm <id> <id>`; promo: `memory add <id> --promo --title T --details D [--from YYYY-MM-DD] [--until YYYY-MM-DD]`, `memory enable|disable <id> <promo-id>`. Personal preferences of the user go in `me memories` instead |
|
|
113
|
+
| "give / hand over this agent to someone", "move it to another workspace" | `ghosty agents transfer <id> --to EMAIL [--workspace THEIR-SLUG] --dry-run`, show the plan and warnings (missing provider key), confirm with the user, then without `--dry-run` + `--yes`. Between the user's own workspaces: `--workspace SLUG|none` (none = personal; `--force` only if they accept cutting a running turn). Owner session, never the `gat_` token |
|
|
114
|
+
| "connect WhatsApp Business / Messenger" | it's Meta's sign-in in the browser: `ghosty channels whatsapp connect <id>` (or `messenger connect`) opens the agent's Channels page; `--json` gives the URL to pass to the user |
|
|
115
|
+
| "pay / upgrade the plan / invoices / change the card" | `ghosty plan open [workspace]` opens the plan page (Stripe); without a workspace (or `personal`) the personal plan at /c/uso; `--json` gives the URL |
|
|
111
116
|
| "delete this agent" | offer `archive` first (reversible for 7 days); if they still want it gone, confirm, then `ghosty agents rm <id>` (owner only; `409` names the workspace where it is active) |
|
|
112
117
|
| "switch it to another engine" | `ghosty agents set <id> --engine <engine> [--model <model-id>] --dry-run` first (says what is forgotten and which machine is replaced; `ok:false` if it is busy), then the same without `--dry-run`. The model belongs to the NEW engine; each conversation keeps its history (gs passes it on its first turn) |
|
|
113
118
|
| "change the model" | `ghosty agents get <id> --json` (lists `models`), then `ghosty agents set <id> --model <model-id>` (restarts by itself) |
|
|
119
|
+
| "let it search the web", "suggestions in its chat", "treat Teams as customers", "turn off its developer extension", "let it email anyone" | `ghosty agents set <id> --web-search on`, `--chat-starters "a\|b"` (its OWN chat; the web widget's are `agents embed --starters`), `--channel-roles teams=equipo\|cliente,programado=…` (personal WhatsApp: per group with `channels wa groups set --role`), `--extensions developer=off` (Lite/Goose box), `--email-any on\|off` (owner only) |
|
|
114
120
|
| "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` |
|
|
115
121
|
| "give it these files / documents / knowledge" | `ghosty files put <id> <name> --file <local>`, one per file |
|
|
116
122
|
| "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` |
|
|
117
|
-
| "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). One key per end user of another product: header `"Authorization": "Bearer ${turn.token}"` (http only, not ACP); each `message-stream` turn then needs `turnToken` |
|
|
123
|
+
| "connect it to this MCP server" | remote https server: `ghosty mcp connect <id> --name <n> --url <https-url> [--from-env VAR] --json` (with a token: the NAME of an env var; without one, if it returns `authorizeUrl` give that link to the user — gs adds the server when they authorize; `--no-open` on a remote box). Any other shape (stdio, several at once): `ghosty mcp get <id> --json > servers.json`, add the server, `ghosty mcp set <id> --file servers.json` (replaces; restarts by itself). One key per end user of another product: header `"Authorization": "Bearer ${turn.token}"` (http only, not ACP); each `message-stream` turn then needs `turnToken` |
|
|
118
124
|
| "what does it have?" | `ghosty agents get <id> --json` → prompt, model, files, skills, mcp |
|
|
119
125
|
| "does it work? / test it" | `ghosty try <id> "…" --json` → the agent's answer (see Verify) |
|
|
120
|
-
| "talk to it / ask it something" | `ghosty chat <id> "…" --json` → streams `chunk` lines, ends with `done` |
|
|
126
|
+
| "talk to it / ask it something" | `ghosty chat <id> "…" --json` → streams `chunk` lines, ends with `done`. A `permission` line (Lite/Goose) means the turn is STOPPED: ask the user, then `ghosty conversations permission <id> <conv> allow\|deny --id <permission-id>` |
|
|
127
|
+
| "this chat is too long, start fresh", "use another model in this chat", "share this chat", "what are its subagents doing / stop one" | `ghosty conversations continue <id> <conv> --json` (→ new `id`; the agent gets the end of the old one) · `conversations model <id> <conv> <model-id>` · `conversations share <id> <conv> --json` (→ `url`, read-only, shows later messages too; `--off` closes it) · `conversations subagents <id> <conv> [stop <task-id>]` |
|
|
121
128
|
| "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, tools included: `kind` text/voice/file/rich with `rich` ubicacion/cita/boton/contacto/reaccion; nothing leaves). A customer attachment exactly as Formmy delivers it: add `--as-formmy` → `media.copied` |
|
|
122
129
|
| "show me this customer's chat on the board / did the attachment arrive?" | `ghosty cards ls <id> [--q name-or-phone] --json`, then `ghosty cards show <id> <folio\|phone> [--limit 50] --json` → `messages[]` with `role`, `content`, `mediaType`, `mediaCopied` |
|
|
123
130
|
| "replay these real conversations" | `ghosty try <id> --replay sample.json --out ./replay [--max N]`; read `./replay/replay.json`; `--resume` if it was cut |
|
|
124
131
|
| "is it configured right? / why does it answer badly?" | `ghosty agents doctor <id> --json` → `info` (model, effort, native subagents, answers /c, box for staff) and `checks[]` with `level` (ok/warn/error) and a `fix` command each; exit 1 = something to fix |
|
|
125
132
|
| "did it forget the conversation? / did it start from scratch?" | `ghosty turns ls <id> --session <conversation> --json` → each turn's `sdk.resumed` (false + `freshReason` orphan/stale/replaced = it lost its memory; `new` = first turn). Claude agents only |
|
|
126
133
|
| "try my public demo as a visitor / does it remember after a box change?" | `ghosty demos try <slug> "…"` (same thread across runs; `--new` for a new visitor); memory across boxes: second message with `--recycle-between --agent <id>`. It counts against the demo's caps |
|
|
134
|
+
| "what is it doing in the background? / is my video ready?" | `ghosty turns jobs <id> --json` → `tasks[]` (`kind` video/audio/captions/download, `state`, `url` when done, `delivered`); stop them with `turns cancel`. Something that repeats on a clock is `ghosty schedule add <id> "…" --every 12h --until …` |
|
|
127
135
|
| "stop it / it keeps working in the background" | `ghosty turns cancel <id> <conversation-id> --json` → `detenido` + `background` (video jobs, subagents, wake-ups canceled: nothing more is delivered) |
|
|
128
136
|
| "test it with this photo / PDF" | `ghosty try <id> "…" --media FILE` (repeatable) or `ghosty chat <id> "…" --media FILE`; as a WhatsApp customer add `--waba --session <phone>` |
|
|
129
137
|
| "do X to all agents that…" (staff) | `ghosty agents ls --sponsor <email> \| --owner <email> [--engine E] --ids`, then `xargs -I{} ghosty agents set {} … --dry-run` first |
|
|
@@ -190,13 +198,14 @@ legacy and always `true`.)
|
|
|
190
198
|
| "download / export / back up this database", "give me the table in Excel" | `ghosty dbs export <id> <db>` → `<db>.sqlite` (whole database); one table as CSV: `ghosty dbs export <id> <db> --table <t>` (`--out` to choose the path). On the web: /app/datos?tab=dbs → the database → **.sqlite** / **table.csv** |
|
|
191
199
|
| "use my browser / do it in my Chrome" | install Ghosty for Chrome (https://www.ghosty.studio/chrome), stay signed in to ghosty.studio and open /c: it pairs alone. In personal chats and scheduled tasks the agent gets `browser_*` tools (never in customer channels); never types passwords. Guide: https://www.ghosty.studio/docs/navegador |
|
|
192
200
|
| "what do my agents remember about me?" / "make it remember X" | `ghosty me memories ls --json`; `me memories add "X"` (app-wide, all agents), `edit <id> "…"`, `rm <id>` (only travels in personal chats) |
|
|
201
|
+
| "the doc the agent wrote" (a `/app/docs/<id>` link): read it, PDF, check spelling, read it aloud, go back a version | `ghosty me docs ls --json`; `me docs get <doc|link> --json` (blocks + versions); `me docs export <doc> --format md` (stdout) or `--format pdf --out F.pdf`; `me docs check <doc> [--language en-US] --json`; `me docs tts <doc> --block N [--segment S] --out F.wav`; `me docs restore <doc> <n>`; `--rev N` for an older version. Not the same as `agents docs` (files an agent reads) |
|
|
193
202
|
| "pause / resume this conversation", "stop the bot with this customer", "take it out of operator-only" | `ghosty cards pause <id> <folio\|phone> --mode 30min\|2h\|24h\|until_tomorrow\|permanent` (permanent = escalated, operator only) / `ghosty cards resume <id> <card>` (also lifts operator-only; it does NOT answer by itself). Both are logged |
|
|
194
203
|
| "answer the ones left pending", "detonate pending replies", "ask the bot to reply to this customer" | list first: `ghosty cards pending <id> [--since 2026-10-06T02:13Z\|12h] --json` → `cards[].flags` (paused, escalated, window_closed, reaction, not_whatsapp, no_agent: those are NEVER answered). Show the user how many would be answered (`--reply --dry-run`), and only after they confirm: `ghosty cards pending <id> --since … --reply --yes` (real customers get messages). One card: `ghosty cards reply <id> <card> [--directive "…"] --yes`. Never on a production conversation without the user's explicit OK |
|
|
195
204
|
| "who was answering this number?", "which numbers/pages were left without an agent?" | `ghosty channels whatsapp integrations <id> --json` → `lastAnswer {agentName, at}` per number; `--orphans` lists only numbers nobody answers today that had turns (`channels messenger ls <id> --orphans` for pages). Give it back with `ghosty channels whatsapp enable <that-agent> <number> --dry-run`, then `--yes` after the user confirms |
|
|
196
205
|
| "change this paragraph / section of the prompt", "patch the prompt", "add this to the prompt" | write `{"edits":[{"what":"hours","find":"9 to 6","replace":"9 to 7"}]}` to a file and run `ghosty agents set <id> --prompt-patch edits.json --dry-run` (prints the diff), then without `--dry-run`. Append: `--prompt-append extra.md`. Applies on the server's CURRENT prompt (never `get --prompt-out` + `set --prompt-file` for a small change: it overwrites concurrent edits). An edit that doesn't find its place → 409, nothing changes |
|
|
197
206
|
| "who changed this?", "audit log", "what happened to this agent's channels?", "who logged in as whom" | `ghosty audit ls [--workspace slug] [--agent id] [--actor email] [--action agent\|channel\|card\|factory\|workspace] [--since 24h] --json` (staff see all; others only their workspaces/agents) |
|
|
198
207
|
| "why did this run take so long?", "what did run N cost?", "where did @build spend its time?" | `ghosty factory runs show <n> --timing --workspace <slug> --json` (each role's turns with minutes, model, USD; clock split working / waiting for a person / other; commands ≥ 60 s). Long commands without output usually mean a hung test or a missing service in the work box |
|
|
199
|
-
| "why did run N fail / get stuck?", "what should we change so it doesn't happen again?" | `ghosty factory runs why <n> --workspace <slug> --json` (category, impact, critical step with evidence, typed actions: role_rules → `.ghosty/factory.md`, repo_setup, skill, prompt; `--refresh` redoes it). Stuck patterns per step are in `runs show <n> --timing` |
|
|
208
|
+
| "why did run N fail / get stuck?", "what should we change so it doesn't happen again?" | `ghosty factory runs why <n> --workspace <slug> --json` (category — `approved_unmet_criterion` first when a plan criterion like "in the preview" was approved without evidence, see `acceptance[]` —, impact, critical step with evidence, typed actions: role_rules → `.ghosty/factory.md`, repo_setup, skill, prompt; `--refresh` redoes it). Stuck patterns per step are in `runs show <n> --timing` |
|
|
200
209
|
| "how is the factory doing?", "cost per merged PR", "merge rate" | `ghosty factory runs stats --since 30d [--repo owner/repo] --workspace <slug> --json` |
|
|
201
210
|
| "list / show / rename a factory run", "who is @build?" | `ghosty factory runs ls --workspace <slug> [--room R]` (with time and cost), `ghosty factory runs show <n> --workspace <slug> [--full]`, `ghosty factory runs rename <n> "Title" --workspace <slug> --dry-run` then `--yes`; `ghosty agents ls --handle build [--workspace <slug>]` |
|
|
202
211
|
| "clean up the board / archive test cards" | `ghosty cards archive <id> --integration X \| --column X \| --before 30d --dry-run` first, then with `--yes` after the user confirms (reversible) |
|
|
@@ -16,6 +16,7 @@ curl -s "$B" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN"
|
|
|
16
16
|
|
|
17
17
|
## PATCH /
|
|
18
18
|
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 } } }`.
|
|
19
|
+
Also `"channelRoles": { "teams": "equipo"|"cliente", "programado": … }` (who talks on that channel; the rest are fixed) and `"email": { "anyFromClients": bool }` (owner only: `enviar_correo` to any address from customer channels). CLI: `agents set --web-search --chat-starters --channel-roles --extensions --email-any`.
|
|
19
20
|
`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).
|
|
20
21
|
`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`.
|
|
21
22
|
`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.
|
|
@@ -58,6 +59,10 @@ Body: `{ "servers": [ …full list… ] }`. Each server is one of:
|
|
|
58
59
|
|
|
59
60
|
Names: `a-z 0-9 - _`, max 20 servers. The agent restarts automatically.
|
|
60
61
|
|
|
62
|
+
## POST /mcp/connect
|
|
63
|
+
Adds ONE remote server by its URL without rewriting the list (same name = replaced). Body `{ "name": "notion", "url": "https://…", "token"?: "…" }`.
|
|
64
|
+
With `token` it is saved with `Authorization: Bearer <token>` → `{ ok, added }`. Without it gs probes the URL: open server → `{ ok, added }`; OAuth server → `{ authorizeUrl }` (the person opens it; on callback gs adds the server and refreshes its token through its proxy). CLI: `ghosty mcp connect <id> --name … --url … [--from-env VAR]`.
|
|
65
|
+
|
|
61
66
|
## GET /whatsapp · PUT /whatsapp
|
|
62
67
|
Which WhatsApp numbers this agent answers. Numbers belong to the workspace and are paired from Sales
|
|
63
68
|
(`salesUrl`); here you only choose who answers. `PUT {"numbers": ["<id>", …]}` leaves the agent
|
|
@@ -90,6 +95,26 @@ Raw image (`content-type: image/png|jpeg|webp`, ≤ 10 MB) or `{ "url": "https:/
|
|
|
90
95
|
## DELETE /
|
|
91
96
|
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). `?fromWorkspace=1` turns it off in every Teams first, then deletes (owner or Ghosty staff). → `{ deleted: id, unbound?: [slug] }`.
|
|
92
97
|
|
|
98
|
+
## POST /token/rotate · POST /token/revoke
|
|
99
|
+
Owner session only (`403` with a `gat_` token, an editor or a shared admin). `rotate` → `{ agentId, token }`: the new `gat_` token, shown ONCE; the old one stops working. `revoke` → `{ agentId, revoked: true, hadToken }`: the editor channel closes. On ACP engines both restart the relay and cut the turn in flight; `502` = it couldn't reach the box and nothing changed. CLI: `ghosty agents token rotate|revoke`.
|
|
100
|
+
|
|
101
|
+
## GET|POST|DELETE /memory
|
|
102
|
+
Rules its team taught it and its promos (the agent page → Memory). `GET` → `{ notes: [{ id, scope, content, source, createdAt }], promos: [{ id, title, details, imageUrl, validFrom, validUntil, active, live }] }` (`scope` `""` = every channel; `live` = offered today, CDMX). `POST { content, scope?, replaces? }` → `{ note }` (`replaces` edits that rule; without `scope` it keeps its channel). `POST { promo: { id?, title?, details?, validFrom?, validUntil?, active?, imageUrl? } }` → `{ promo, created, warning? }` (`201` when created; with `id` only the given fields change). `DELETE { id }` → `{ deleted, kind: note|promo }`. Works with the `gat_` token too. CLI: `ghosty agents memory`.
|
|
103
|
+
|
|
104
|
+
## POST /transfer
|
|
105
|
+
Owner (or Ghosty staff) session, never `gat_`. `{ to: email, workspace?: their-slug, dryRun? }` hands the agent over with its box, memory and files → `{ kind: "transfer", to, workspace, workspaces, warnings, transferred? }`. `{ workspace: slug|"none", dryRun?, force? }` moves it between your workspaces → `{ kind: "move", from, to, warnings, steps, failed }`. Always `dryRun: true` first and show it; `400` with a readable reason (no account, plan limit, model over the plan, @handle taken, busy box). CLI: `ghosty agents transfer`.
|
|
106
|
+
|
|
107
|
+
## GET|POST|DELETE /teams-schedule
|
|
108
|
+
A turn at a set time in a Ghosty Teams room or thread: it answers there as if mentioned. `GET ?workspace=slug` → `{ scheduled: [...] }`; `POST { workspace, channel, parentId?, text, dueAt (ISO) }` → `{ id, channel, parentId, dueAt }`; `DELETE { workspace, id }` → `{ ok }`. The agent must be active in that workspace's Teams and the caller a member; never with a `gat_` token (`403`). CLI: `ghosty schedule add|ls|rm <id> … --teams <ws>#<room>[/<thread>]`.
|
|
109
|
+
|
|
110
|
+
## Your conversations (`/api/v2/me/agents/{id}/…`, owner session, not `gat_`)
|
|
111
|
+
`GET /tasks` → `{ tasks: [{ id, kind: download|audio|video|captions, label, state: running|done|failed, startedAt, endedAt, elapsedMs, url?, error?, sessionId?, delivered, wakePending? }], running }`: background jobs from your personal chats, last 24 h (read-only; stop with `POST /conversations/{sid}/cancel`). CLI: `ghosty turns jobs <id>`.
|
|
112
|
+
`GET /schedule` → pending scheduled turns and recent runs; schedule and cancel per conversation (`/conversations/{sid}/schedule[/{id}]`). CLI: `ghosty schedule`.
|
|
113
|
+
`POST /conversations/{sid}/continue` → `{ id }` (new linked thread) · `POST …/model { value }` · `POST …/permission { id, optionId }` → `{ resuelto }` · `POST|DELETE …/share` → `{ compartida, slug }` (`/s/{slug}`) · `GET …/subagents` (SSE: `snapshot` first) · `POST …/subagents/{taskId}/stop`. CLI: `ghosty conversations continue|model|permission|share|subagents`.
|
|
114
|
+
|
|
115
|
+
## Editable docs (`/api/v2/me/docs/{id}`, account session with `files`)
|
|
116
|
+
The docs an agent delivers in a chat (link `/app/docs/{id}`). `GET [?v=n]` → `{ id, title, sessionId, agentId, version: { n, author, envelope }, latest, versions }` · `PUT { blocks }` → `{ versionId }` · `POST { restore: n }` → `{ versionId }` · `GET /export?format=pdf|md[&v=n]` (bytes) · `GET /check[?v=n&lang=es]` (NDJSON: `{total}` then `{id, hash, matches}` per block; offsets are inside each block's text) · `GET /tts?i=<block>[&s=<sentence>][&v=n]` (audio; `X-Seg-Count` = sentences in the block; `204` = no text). CLI: `ghosty me docs`.
|
|
117
|
+
|
|
93
118
|
## Workspace (not under /agents/{id})
|
|
94
119
|
`GET /api/v2/engines` → valid engines and models. `GET /api/v2/workspaces/{slug}/usage?days=14` → turns, tokens and no-balance messages per agent/day (owner or staff). `GET|POST /api/v2/workspaces/{slug}/bags`, `PATCH|DELETE …/bags/{bag}` (writes: staff). `POST /api/v2/workspaces/{slug}/renew {until}` and `…/rename {to}` (staff; `dryRun: true` first).
|
|
95
120
|
|