ghosty-acp 0.0.4 → 0.0.5

package/README.md

@@ -180,3 +180,10 @@ flujo JSON-RPC, porque cualquier otra cosa ahí rompe al editor.
 | `cwd … → …` | Se remapeó la ruta del proyecto a una que el agente sí ve |
 
 Necesita Node 22 o superior. MIT.
+
+## Agent skills inside
+
+The package ships the Ghosty Studio agent skills under `skills/` (`ghosty-agent`, `ghosty-acp`,
+`ghosty-docs`, `ghosty-recipe`), in the [Agent Skills](https://agentskills.io) format. Tools that
+load skills from installed dependencies (e.g. TanStack Intent) pick them up; anyone else can
+install them with `npx skills add https://ghosty.studio` or `npx skills add blissito/ghosty-skills`.

package/package.json

@@ -1,13 +1,38 @@
 {
   "name": "ghosty-acp",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Conecta tu editor a un agente ACP remoto. Puente entre entrada/salida estándar y WebSocket, sin dependencias.",
   "type": "module",
-  "bin": { "ghosty-acp": "bridge.mjs" },
-  "files": ["bridge.mjs", "README.md"],
-  "engines": { "node": ">=22" },
-  "keywords": ["acp", "agent-client-protocol", "zed", "vscode", "neovim", "agent"],
+  "bin": {
+    "ghosty-acp": "bridge.mjs"
+  },
+  "files": [
+    "bridge.mjs",
+    "README.md",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "acp",
+    "agent-client-protocol",
+    "zed",
+    "vscode",
+    "neovim",
+    "agent",
+    "agent-skills",
+    "skills",
+    "ghosty"
+  ],
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/blissito/ghosty-studio.git", "directory": "packages/acp-bridge" },
-  "homepage": "https://www.ghosty.studio/docs/acp"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blissito/ghosty-studio.git",
+    "directory": "packages/acp-bridge"
+  },
+  "homepage": "https://www.ghosty.studio/docs/acp",
+  "scripts": {
+    "prepack": "rm -rf skills && cp -R ../../public/skills skills && rm -f skills/*.tar.gz skills/index.json skills/index.legacy.json"
+  }
 }

package/skills/README.md

@@ -0,0 +1,20 @@
+# Ghosty Studio agent skills
+
+Skills in the [Agent Skills](https://agentskills.io) format for coding agents (Claude Code, Cursor,
+Codex, Copilot…). Install one or all:
+
+```bash
+npx skills add blissito/ghosty-skills
+# or straight from the site (same skills, discovered via /.well-known/agent-skills):
+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-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 |
+
+This directory is mirrored from `public/skills/` in
+[blissito/ghosty-studio](https://github.com/blissito/ghosty-studio). Docs: https://www.ghosty.studio/docs/configurar

package/skills/ghosty-acp/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: ghosty-acp
+description: Connect a code editor (Zed, VS Code, JetBrains, Neovim) to a Ghosty Studio agent over ACP (Agent Client Protocol) using the ghosty-acp bridge and the agent token. Use when the user wants to talk to their Ghosty agent from their editor, pastes an acp.agents or agent_servers config, or mentions ghosty-acp or ACP with ghosty.studio.
+license: MIT
+compatibility: Node 22+ on the user's machine (npx downloads the bridge); network access to the agent's wss:// address
+metadata:
+  author: ghosty-studio
+  version: "1.0"
+---
+
+# Connect an editor to a Ghosty agent over ACP
+
+A Ghosty Studio agent runs on its own machine behind a WebSocket. Editors launch a
+**command** and speak ACP over stdio, so a bridge swaps the cable: `npx -y ghosty-acp <wss-url>`.
+It has no dependencies and carries no secret; the token travels in an environment variable.
+
+## What you need from the user
+
+Both come from Ghosty Studio → **Agentes → their agent → "Desde tu editor (ACP)"** (a collapsed
+section under the token card):
+
+- the agent's ACP address: `wss://acp-<agentId>.<host>/acp`
+- the token `gat_…` (the same token the `ghosty-agent` skill uses)
+
+Never put the token in `args`: any process on the machine can read another process's
+arguments. It goes in `env.GHOSTY_ACP_TOKEN`.
+
+## Write the config for their editor
+
+**Zed** — `Settings → settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Ghosty": {
+      "type": "custom",
+      "command": "npx",
+      "args": ["-y", "ghosty-acp", "wss://acp-AGENT.../acp"],
+      "env": { "GHOSTY_ACP_TOKEN": "gat_…" }
+    }
+  }
+}
+```
+
+**VS Code** — install the *ACP Client* extension, then `settings.json`:
+
+```json
+{
+  "acp.agents": {
+    "Ghosty": {
+      "command": "npx",
+      "args": ["-y", "ghosty-acp", "wss://acp-AGENT.../acp"],
+      "env": { "GHOSTY_ACP_TOKEN": "gat_…" }
+    }
+  }
+}
+```
+
+Do not use VS Code's "Add Agent" wizard: it asks for command and args only, never the env
+var, and the agent ends up without its key.
+
+**JetBrains / Neovim** use the same triple (command, args, env) in their own ACP client
+settings. `GHOSTY_ACP_CWD` optionally sets the remote working directory.
+
+## When it does not connect
+
+| Symptom | Meaning | Do |
+|---|---|---|
+| `rejected (1006)` right away | token mismatch (rotated?) | ask the user to copy the block again from the panel |
+| slow first start (5–15 s) | the agent's machine was asleep; the first connection wakes it | wait, do not change anything |
+| `preview host not found` | the machine was recycled; the platform recreates it on demand | retry once after ~5 s |
+| `already serving N conversations` | every open session takes a slot | close a session in another client |
+
+## Rules
+
+- Node 22+ is required for `npx -y ghosty-acp`; check `node -v` if it fails to start.
+- Read `ghosty-acp` in the user's editor config as the bridge, not as this skill.
+- Never print the token back or commit the settings file with it inside.

package/skills/ghosty-agent/SKILL.md

@@ -0,0 +1,62 @@
+---
+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.
+license: MIT
+compatibility: Needs curl or any HTTP client and network access to https://www.ghosty.studio
+metadata:
+  author: ghosty-studio
+  version: "1.1"
+---
+
+# Configure a Ghosty Studio agent
+
+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)
+
+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:
+
+```bash
+export GHOSTY_AGENT_ID="<id>"
+export GHOSTY_AGENT_TOKEN="gat_…"
+```
+
+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).
+
+## What you can do
+
+| User asks | Do |
+|---|---|
+| "set its identity / persona / system prompt" | `PATCH` with `{"prompt": "..."}` then `POST …/restart` |
+| "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 |
+
+Read `references/api.md` for exact request/response shapes before calling.
+
+## Rules
+
+- **Read before write.** `GET` first; `PATCH` only the fields the user asked to change.
+- **Write the prompt in the user's language** and in second person ("Eres…", "You are…"). Keep it
+  under ~3,000 characters: it is prepended to every conversation.
+- **Skills follow the Agent Skills format**: a `SKILL.md` with YAML frontmatter `name` and
+  `description`, body in markdown. Slug = lowercase, digits and hyphens.
+- **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.
+- **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.
+
+## After changes
+
+Tell the user in one line what changed and suggest a test message for the agent, e.g.
+"Ask it: *¿qué archivos tienes en tu workspace?*".

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

@@ -0,0 +1,58 @@
+# Ghosty Studio — agent configuration API
+
+Base: `https://www.ghosty.studio/api/v2/agents/{id}` · Auth: `Authorization: Bearer gat_…`
+(agent token) or an owner OAuth2 bearer with `agents:write`. JSON unless noted.
+Full spec: https://www.ghosty.studio/openapi.yaml · Docs: https://www.ghosty.studio/docs/configurar
+
+## GET /
+Returns `{ id, name, engine, model, models: [{id,label}], prompt, channels, webSearch, mcp }`.
+Add `?full=1` to also get `files: [{path,size}]` and `skills: [{slug,description,files}]`
+(wakes the machine if asleep).
+
+```bash
+curl -s "$B" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN"
+```
+
+## PATCH /
+Body: any of `{ "name", "model", "prompt", "webSearch": bool, "channels": { "teams": bool } }`.
+Response: the same as GET plus `aplicado: ["set-prompt", …]`. `model` restarts the agent.
+
+```bash
+curl -s -X PATCH "$B" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"Eres Nora, asistente de la clínica Dental Sur. Contestas en español, corto, y nunca das diagnósticos."}'
+```
+
+## PUT /files/{path}  ·  DELETE /files/{path}  ·  GET /files[/dir]
+Raw bytes in the body (no multipart, no base64). Max 10 MB. `path` is relative, no `..`.
+
+```bash
+curl -s -X PUT "$B/files/precios-2026.pdf" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" \
+  -H "Content-Type: application/pdf" --data-binary @precios-2026.pdf
+```
+→ `{ path, bytes, en: "/data/work/precios-2026.pdf" }`
+
+## 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.
+
+```bash
+jq -n --rawfile md SKILL.md '{markdown:$md}' | \
+curl -s -X PUT "$B/skills/cotizaciones" -H "Authorization: Bearer $GHOSTY_AGENT_TOKEN" \
+  -H "Content-Type: application/json" -d @-
+```
+
+## GET /mcp  ·  PUT /mcp
+Body: `{ "servers": [ …full list… ] }`. Each server is one of:
+- `{ "name": "notion", "type": "http", "url": "https://mcp.notion.com/mcp", "headers": { "Authorization": "Bearer …" } }`
+- `{ "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data/work"], "env": {} }`
+
+Names: `a-z 0-9 - _`, max 20 servers. The agent restarts automatically.
+
+## POST /restart
+→ `{ reiniciado: true }`. Cuts a running turn; disk survives.
+
+## 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 ·
+`413` too big · `502` saved but the machine did not take it (retry `POST /restart`).

package/skills/ghosty-docs/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: ghosty-docs
+description: Read the Ghosty Studio documentation from an agent without scraping — every page as raw markdown, llms.txt, the docs MCP server (search_docs, read_doc, list_docs, openapi) and the OpenAPI spec. Use when the user asks how something works in Ghosty Studio, Ghosty Teams or ghosty.studio, or before calling its API.
+license: MIT
+compatibility: Network access to https://www.ghosty.studio
+metadata:
+  author: ghosty-studio
+  version: "1.0"
+---
+
+# Read the Ghosty Studio docs
+
+Ghosty Studio publishes its documentation for agents first. Never scrape the HTML: every
+page has a machine-readable twin.
+
+## Pick the cheapest source
+
+| Need | Fetch |
+|---|---|
+| The map of every page (title + URL) | `https://www.ghosty.studio/llms.txt` |
+| Everything at once (large) | `https://www.ghosty.studio/llms-full.txt` |
+| One page as markdown | append `.md` to its URL: `https://www.ghosty.studio/docs/configurar.md` (English: `/en/docs/configure.md`) |
+| A page when you only have the HTML URL | `GET` it with `Accept: text/markdown` — the server negotiates and returns markdown |
+| The public API contract | `https://www.ghosty.studio/openapi.yaml` (OpenAPI 3.1) |
+
+Spanish is the source language (`/docs/...`); English lives under `/en/docs/...`. Both are
+kept in sync; prefer the user's language.
+
+## Use the MCP server when you can
+
+`https://www.ghosty.studio/mcp/docs` is a Streamable HTTP MCP server, no auth, JSON-RPC over
+`POST`. Tools:
+
+- `search_docs { query, locale? }` — lexical search, up to 8 pages with slug and snippet. Call this first.
+- `read_doc { slug, locale? }` — a whole page as markdown (slug like `api/autenticacion`).
+- `list_docs { locale? }` — all pages grouped by section.
+- `openapi {}` — the OpenAPI YAML.
+
+Claude Code: `claude mcp add --transport http ghosty-docs https://www.ghosty.studio/mcp/docs`.
+
+Without MCP, the same tools in plain HTTP:
+
+```bash
+curl -s https://www.ghosty.studio/mcp/docs -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"whatsapp"}}}'
+```
+
+## Rules
+
+- Search, then read one page. Do not read `llms-full.txt` for a single question.
+- Quote the page URL you used when you answer; the user may want to open it.
+- JSON field names in the API (`agentes`, `enCola`, `reemplazoAnterior`…) are the contract and
+  are the same in both languages: do not translate them.
+- To *change* an agent (identity, files, skills, MCPs) use the `ghosty-agent` skill, which has
+  the token flow. This skill is read-only.

package/skills/ghosty-recipe/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ghosty-recipe
+description: Write, review or convert a Ghosty Studio agent recipe (the portable .recipe.yaml with title, instructions, model and channels) so it can be uploaded in "Nuevo agente → Plantilla". Use when the user wants to create a Ghosty agent from a spec, turn a persona or job description into an agent, export/share an agent, or mentions a Ghosty recipe or recipe.yaml.
+license: MIT
+compatibility: No network needed to write a recipe; uploading it happens in the Ghosty Studio panel
+metadata:
+  author: ghosty-studio
+  version: "1.0"
+---
+
+# Ghosty agent recipes
+
+A recipe is a YAML file that fully describes an agent **without secrets**: who it is, how it
+talks, which model, which channels. It is what Ghosty Studio exports from an agent
+(`/app/agents/<id>/recipe.yaml`) and what "Nuevo agente → Plantilla → sube una receta"
+imports. The format is Goose-compatible plus an `x-ghosty` block.
+
+## Write one
+
+```yaml
+version: "1.0.0"
+title: Nora, recepción de Dental Sur           # ≤ 60 chars, shown as the agent's name
+description: Agenda citas y resuelve dudas de la clínica por WhatsApp.   # ≤ 200 chars, one line
+instructions: |
+  Eres Nora, asistente de la clínica Dental Sur.
+
+  ## Cómo hablas
+  Español de México, corto, sin diagnósticos.
+
+  ## Qué sabes hacer
+  - Agendar, mover y cancelar citas.
+  - Explicar precios de la lista que tienes en tu workspace.
+
+  ## Qué NO haces
+  - No das diagnósticos ni recetas.
+
+  ## Cuándo preguntas
+  Sólo cuando la respuesta cambia el resultado.
+settings:
+  goose_model: claude-sonnet-5
+x-ghosty:
+  engine: ghosty-lite
+  channels: { teams: true, whatsapp: true }
+```
+
+Field-by-field rules are in `references/schema.md`. Read it before validating a recipe.
+
+## Rules
+
+- **`title` is required**; everything else is optional but a recipe without `instructions` is
+  useless. Write instructions in the user's language and in second person.
+- **Never a colon followed by a space inside `description`** unless the value is quoted
+  (`description: "Ventas: WhatsApp"`): unquoted it is a YAML parse error and the whole
+  recipe is skipped.
+- Structure `instructions` with the four headings the house templates use: *Cómo hablas*,
+  *Qué sabes hacer*, *Qué NO haces*, *Cuándo preguntas* (plus *Formato* for Teams agents).
+  Keep it under ~3,000 characters: it is prepended to every conversation.
+- Engines: `ghosty-lite` or `goose` when the agent needs its own machine (files, skills,
+  MCPs); `claude`, `codex`, `deepseek` for prompt-only agents. Models must be one the engine
+  offers (`claude-sonnet-5`, `claude-opus-5`, `claude-haiku-4-5-20251001`…); when unsure,
+  omit `settings` and let the panel pick.
+- No tokens, keys, phone numbers or URLs with credentials in a recipe: it is meant to be
+  pasted in an email.
+- Prefer converting what the user already has (a job description, an old system prompt)
+  over inventing; ask only for what changes the result.
+
+## Deliver
+
+Give the YAML in a fenced block and tell the user: save it as `<name>.recipe.yaml`, then in
+Ghosty Studio → **Agentes → Nuevo agente → Plantilla → sube una receta**. To tune it after
+creation, use the `ghosty-agent` skill (needs the agent token).

package/skills/ghosty-recipe/references/schema.md

@@ -0,0 +1,30 @@
+# Recipe schema (v1.0.0)
+
+Source of truth: `parseRecipe` in Ghosty Studio. Unknown keys are ignored, never rejected.
+
+| Key | Type | Required | Notes |
+|---|---|---|---|
+| `version` | string | no | defaults to `"1.0.0"` |
+| `title` | string | **yes** | trimmed, cut at 60 chars; becomes the agent's name |
+| `description` | string | no | trimmed, cut at 200 chars; one line, quote it if it contains `: ` |
+| `instructions` | string | no | the system prompt; use a block scalar (`|`) |
+| `settings.goose_provider` | string | no | Goose-compatible; usually omitted |
+| `settings.goose_model` | string | no | model id; must exist for the chosen engine |
+| `extensions` | list | no | Goose extensions; kept as-is, Ghosty ignores them today |
+| `x-ghosty.engine` | string | no | `ghosty-lite` · `goose` · `claude` · `codex` · `deepseek` |
+| `x-ghosty.model` | string \| null | no | same as `settings.goose_model`; the panel reads either |
+| `x-ghosty.channels` | object | no | `{ teams?: bool, web?: bool, whatsapp?: bool }`; default `{ teams: true }` |
+| `x-ghosty.creatorVersion` | string | no | written by exports; do not set by hand |
+
+## Validation checklist
+
+1. Parses as YAML (no unquoted `: ` in scalars, consistent indentation, block scalar for `instructions`).
+2. `title` present and non-empty.
+3. `instructions` in second person, in the user's language, with the four headings.
+4. No secrets.
+5. If `settings.goose_model` is set, it is a real model id for that engine.
+
+## Exporting an existing agent
+
+`GET https://www.ghosty.studio/app/agents/<id>/recipe.yaml` (logged-in browser) downloads
+`<name>.recipe.yaml` with the same shape, secrets stripped.