vespin 0.2.0 → 0.3.0

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/README.md CHANGED
@@ -33,7 +33,7 @@ vespin login
33
33
  This opens your browser to sign in. On a machine with no browser, such as one
34
34
  you reach over SSH, run `vespin login --no-browser` and paste back the address
35
35
  your browser lands on. `vespin logout` signs you out, and you can revoke the
36
- CLI at any time under Settings › Vespin MCP › Connected.
36
+ CLI at any time under Settings › Vespin MCP & CLI › CLI.
37
37
 
38
38
  ## Examples
39
39
 
@@ -3,7 +3,7 @@ Third-party notices
3
3
 
4
4
  The vespin bundle includes the following third-party packages.
5
5
 
6
- @ai-sdk/gateway 4.0.109 (Apache-2.0)
6
+ @ai-sdk/gateway 4.0.146 (Apache-2.0)
7
7
  ------------------------------------
8
8
 
9
9
  Copyright 2023 Vercel, Inc.
@@ -20,7 +20,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20
20
  See the License for the specific language governing permissions and
21
21
  limitations under the License.
22
22
 
23
- @ai-sdk/provider 4.0.26 (Apache-2.0)
23
+ @ai-sdk/provider 4.0.38 (Apache-2.0)
24
24
  ------------------------------------
25
25
 
26
26
  Copyright 2023 Vercel, Inc.
@@ -37,7 +37,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
37
37
  See the License for the specific language governing permissions and
38
38
  limitations under the License.
39
39
 
40
- @ai-sdk/provider-utils 5.0.58 (Apache-2.0)
40
+ @ai-sdk/provider-utils 5.0.81 (Apache-2.0)
41
41
  ------------------------------------------
42
42
 
43
43
  @effect/platform-node 4.0.4 (MIT)
@@ -797,7 +797,7 @@ Apache License 2.0
797
797
 
798
798
  See the LICENSE file in the root of this repository.
799
799
 
800
- ai 7.0.135 (Apache-2.0)
800
+ ai 7.0.173 (Apache-2.0)
801
801
  -----------------------
802
802
 
803
803
  Copyright 2023 Vercel, Inc.
@@ -1092,7 +1092,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
1092
1092
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1093
1093
  SOFTWARE.
1094
1094
 
1095
- undici 8.11.2 (MIT)
1095
+ undici 8.12.4 (MIT)
1096
1096
  -------------------
1097
1097
 
1098
1098
  MIT License
@@ -1117,7 +1117,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
1117
1117
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1118
1118
  SOFTWARE.
1119
1119
 
1120
- ws 8.22.0 (MIT)
1120
+ ws 8.21.3 (MIT)
1121
1121
  ---------------
1122
1122
 
1123
1123
  Copyright (c) 2011 Einar Otto Stangvik <einaros@gmail.com>
@@ -1141,7 +1141,7 @@ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
1141
1141
  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
1142
1142
  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1143
1143
 
1144
- zod 4.5.4 (MIT)
1144
+ zod 4.6.7 (MIT)
1145
1145
  ---------------
1146
1146
 
1147
1147
  MIT License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vespin",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Vespin from your terminal: tasks, their descriptions, and coding agents, for people and scripts",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://vespin.dev",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: vespin
3
- description: Drive Vespin from a shell with the `vespin` command: create tasks, read and write their descriptions, start coding agents and wait on them, check out an agent's branch, and answer the inbox threads agents post. Load it when asked to work with Vespin tasks, their descriptions, agents, or inbox from a terminal, to script or pipe Vespin, or to wait on an agent and bring its branch local. Prefer Vespin's MCP server only when you have no shell.
3
+ description: "Drive Vespin from a shell with the `vespin` command: create tasks, read, write, and restore their descriptions, comment on them, read the pages agents show, start coding agents and wait on them, check out an agent's branch, share a cloud agent's port by preview link, answer, start, mark read, and set reminders on inbox threads, manage the workspace's members and invitations, read and keep the workspace's shared memory, make and run automations, and list the workspace's GitHub repositories, read their files, and check the GitHub connection. Load it when asked to work with Vespin tasks, their descriptions, agents, inbox, memory, automations, or the workspace's GitHub repositories from a terminal, to script or pipe Vespin, or to wait on an agent and bring its branch local. Prefer Vespin's MCP server only when you have no shell."
4
4
  ---
5
5
 
6
6
  # vespin
@@ -28,21 +28,82 @@ vespin agent checkout <agent-id> # fetch its branch and check it ou
28
28
  - `task create` takes the repository from this folder's `origin` (override with `-R owner/name`). With `-q` it prints the task id, then the agent id. `--start` hands the agent the description (`-F description.md`); `--prompt <file|->` hands it a prompt instead.
29
29
  - To see the work live, use `vespin agent logs <id> --follow`. Without `--follow` it prints the transcript so far.
30
30
  - `agent checkout` must run inside a clone of the task's repository. `agent view <id>` prints the branch, pull request, and checks.
31
- - Tasks are named by id, number, or key (`ACME-42`). Agents and threads are named by id.
31
+ - Tasks are named by id, number, or key (`ACME-42`). Agents, threads, comment threads, and pages are named by id.
32
32
 
33
33
  Other commands:
34
34
 
35
35
  | Command | What it does |
36
36
  | --- | --- |
37
37
  | `task list [--mine] [--status s]` · `task view <task>` · `task update <task> [--status] [--priority] [--assignee] [--name]` | Find, read, and change tasks; `--status done` marks one done |
38
+ | `task relate <task> --blocked-by\|--blocks\|--sub-task\|--parent <other> [--from kind]` | Move a relation between two tasks to another kind in one step, such as a blocker made a sub-task; `--from` defaults to the other side, turning the relation around |
39
+ | `task update <task> [--parent <task\|none>] [--blocked-by <task>] [--blocks <task>] [--remove-blocked-by <task>] [--remove-blocks <task>] [--section <section\|none>]` | Put a task under a parent or back at the top; add or take away the tasks it waits on and that wait on it (each flag again for each task); keep it in one of your sidebar sections |
40
+ | `workspace list` · `workspace use <workspace>` · `workspace create <name>` | Your workspaces, the default marked; make one the default; create one with you as its owner (the default stays until you `use` it) |
41
+ | `workspace members` · `workspace remove <member> [--yes]` · `workspace role <member> admin\|member` | The workspace's members (account id, role, name, email) and who left it; remove one, named by account id or email (the owner removes an admin or a member, an admin a member alone; it asks first, so pass `--yes` when piped); make one an admin or an admin a member (owner only) |
42
+ | `workspace invitations` · `workspace invite <email> [--role member\|admin]` · `workspace uninvite <invitation>` | The pending invitations, each with its id and accept link (`--json`); invite an address, emailed where the service sends mail, which prints the accept link to hand on (owners and admins; only the owner invites an admin); cancel one by id |
43
+ | `workspace rename <name>` · `workspace slug <slug>` | Rename the workspace (owners and admins; never your first workspace, named for you), its links unchanged; change its slug, the first step of its links, which only its owner may (links under the old slug still open it) |
44
+ | `workspace photo <file>` · `workspace photo --remove` | Set the workspace's photo from a PNG, JPEG, or WebP of at most 100,000 bytes, or remove it; its owner or an admin may |
45
+ | `workspace leave` · `workspace transfer <member>` · `workspace delete` (each `--yes` without a terminal) | Leave the workspace (anyone but its owner); hand it to one of its admins, by account id or email, becoming an admin; delete it and everything in it. The last two are the owner's alone and never your first workspace. Each asks first; run them only when the member asks |
46
+ | `section list` · `section create <title> [--emoji e]` · `section delete <section>` | Your sidebar sections in the workspace, with the tasks in each; make one; delete one (its tasks go back under Tasks). A section is named by id or title |
47
+ | `task cat <task> <path> [--commit sha]` · `task ls <task> [path] [-r]` | Read a file or list a folder of the task's repository as GitHub holds it, at the default branch's head or a commit (`cat`), never an agent's unpushed work in its sandbox |
48
+ | `task delete <task> [--yes]` | Delete a task for good, as the app's Permanently delete does: its agents are stopped first, then it goes with its description and their transcripts. It asks at a terminal; piped or from a coding agent it needs `--yes`, so delete only when the person asked |
49
+ | `task follow <task> [--member <who>]` · `task unfollow <task> [--member <who>]` | Follow or stop following a task yourself, or add or remove teammates as its followers (each `--member` again for each, by email, name, or id); an added follower's machines start off, and the assignee can't be removed. Who follows is the person's own choice, so change it only when they asked |
38
50
  | `description show <task>` · `description edit <task> -F <file\|->` | Print the description as Markdown; replace it whole |
51
+ | `description history <task> [--before <r>]` · `description show <task> --revision <r>` · `description restore <task> <r>` | List the description's revisions, newest first, 50 a page (`--before` the revision it printed for older ones); print it as it stood after one; put one back, kept as a new revision, so restoring the one before undoes it |
52
+ | `comment list <task> [--page <id>] [--status open\|resolved\|all]` | Comment threads on the description, or on one of its pages; open ones unless asked |
53
+ | `comment add <task> --on "<words>" -F <msg\|->` · `comment reply <task> <thread> -F <msg\|->` · `comment resolve <task> <thread>` · `comment reopen <task> <thread>` | Start a thread on words copied exactly from the description (as much as stands there once); reply, which is sent to the agents in the thread and to each of the task's agents the words mention as a link, `[@<title>](https://vespin.dev/<workspace>/agent/<agent-id>)` (a bare `@name` asks no one). The comment is posted all the same where an agent cannot take it: the JSON's `unsent` lists those already in the thread (an archived one, say), never a newly mentioned one, so an empty `unsent` does not prove delivery (`-q` prints the thread id alone); resolve or reopen it |
54
+ | `page list --task <task>` · `page show <page> --task <task> [--version n]` | Pages agents showed on a task; one version's HTML (the newest by default) |
39
55
  | `agent start <task> [-F prompt] [--model m --effort e] [--branch b] [--cloud\|--on <device>] [--follow\|--wait]` | Start an agent; `vespin models` lists `--model` and `--effort` values |
56
+ | `agent continue <id> [-F note] [--at <message-id>] [--model m --effort e] [--cloud\|--on <device>] [--follow\|--wait]` | Continue an agent as the app's Continue does: it is stopped, and a new agent on its task is handed its brief and transcript, then the note. The new agent runs as you, on your own Claude or ChatGPT plan, so a teammate's agent is handed over to you. `--at` forks at one of its assistant messages instead (ids from `agent logs --json`), and it goes on. It runs on the agent's model and where it runs unless you name them |
40
57
  | `agent list [<task>] [--offset n]` · `agent view <id>` | Agents, newest first, the workspace's 50 a page (`--offset` the `nextOffset` it printed); one agent's status |
41
- | `agent send <id> -F <msg\|->` · `agent stop <id>` | Message an agent; stop its turn (what it pushed stays) |
58
+ | `agent send <id> [--queue [--message-id <uuid>]] -F <msg\|->` · `agent stop <id>` | Message an agent, or with `--queue` queue it behind the turn under way and any messages queued before it, to go once they are over (your own agents only; a paused queue sends nothing until `agent queue resume`); `--message-id` names the queued message with a UUID you mint, so a script can address it even where the send's answer was lost (a retry under it queues nothing more only while that message still waits); stop its turn (what it pushed stays) |
59
+ | `agent queue <id>` · `agent queue resume <id>` · `agent queue hold\|release\|delete <id> <message>` · `agent queue edit <id> <message> -F <msg\|->` · `agent queue steer <id> <message> [-F <msg\|->]` · `agent queue reorder <id> <message…>` | List what waits in an agent's queue (`-q` the message ids, in order), and change it as the app's queue controls do, your own agents only: resume a paused queue; hold a message so the queue stops at it, or release it; delete it; write it again (its files dropped); send it now into the turn under way, optionally in new words (its files dropped); or name every message in a new order |
60
+ | `agent update <id> --title t` · `--model m --effort e` · `--pin`/`--unpin` · `--archive [--reason r]`/`--unarchive` · `--disabled-servers a,b` | Change an agent, one change a call: rename it (empty clears), move it to another model from its next step, pin it in your sidebar, archive it (stopping a turn still running) or bring it back, or replace the MCP servers switched off for it (`""` switches all on) |
61
+ | `agent rewind <id> <message-id>` | Take an agent back to just before one of the lines sent to it (ids from `agent logs --json`), stopping it first; that line and everything after it are dropped, and its checkout stays as it is |
62
+ | `agent delete <id> [--yes]` | Delete an agent for good, stopping it first; its branch and pull request on GitHub stay. It asks at a terminal, and needs `--yes` anywhere else, so only pass `--yes` when the person asked for the delete |
63
+ | `agent wake <id>` | Resume a cloud agent's stopped sandbox and start its runner, so its next message, shell, or shared port answers at once; prints where the sandbox stands |
64
+ | `agent logs <id> [--worker <call-id>] [--call <call-id>]` | The whole transcript; `--worker` reads one of its workers' instead, by the `toolCallId` of the call that started it, and `--call` prints one call whole, its input and output (ids from `agent logs --json`) |
65
+ | `agent diff <id> [--stat] [--number n]` | The diff of an agent's pull request as GitHub holds it, every file's patch; `--stat` one line a file, `-q` the paths; `--number` another pull request of its repository |
66
+ | `agent pr <id> ready\|draft\|merge\|auto-merge [--method merge\|squash\|rebase] [--head sha] [--off] [--number n]` | Change the pull request on GitHub as you: mark it ready, turn it back into a draft, merge it now, or turn auto-merge on (`--off` turns it off). A merge is made against the head as it stands now unless `--head` pins the one you reviewed, by the first method the repository allows unless `--method` names one |
67
+ | `pr view <pr\|agent> [--checks] [--conversation] [--stat] [--diff] [--number n]` | Any pull request of a repository your workspace reaches, named `owner/name#n` or by its GitHub link, or an agent's by its id (`--number` another of its repository): its overview and description, or the parts named: its checks and deployments, its comments and reviews with their threads, its files one a line with which you marked viewed, every file's patch |
68
+ | `pr viewed <pr\|agent> <path…> [--unmark] [--number n]` | Mark files of a pull request viewed on GitHub as you, as its Viewed box does, or unmark them; name it as `pr view` does |
69
+ | `pr chapters <pr\|agent> [--generate] [--number n]` | A pull request's chapters, the story of its diff in reading order, as its Pull request tab shows them. Name it by its GitHub link or `owner/name#n` (in the workspace `-w` names), or by an agent's id for its own pull request (`--number` another of its repository). `--generate` makes them for the head now: one model call on your own API key, which costs money and takes a minute or more, so read first and generate only where none stand or they are stale |
70
+ | `agent ports <id>` | Ports a server listens on in a cloud agent's sandbox, and the one shared by link; none unless the sandbox is running |
71
+ | `agent share <id> <port>` · `agent share <id>` · `agent share <id> --stop` | Share a port by public link (replacing any shared before), print the link shared now, or close it; `-q` prints the link alone |
72
+ | `agent forward <id> [port…] [--local <port>]` | Serve a cloud agent's ports on `localhost` (the ones it listens on now, or those named) until Ctrl-C or its sandbox stops; a local port that will not listen is refused, so pick another with `--local` |
73
+ | `agent tabs <id>` · `agent tabs open <id> <address>` · `agent tabs take <id> <tab>` · `agent tabs hand-back <id> <tab>` | A cloud agent's browser tabs, each by id, who drives it, title, and address (never the page itself); open a page in its browser, such as a sign-in for a person to finish; take a tab over so the agent leaves it alone (it lapses a minute after the last `take`, which renews it); hand it back. `open` takes the new tab over for you |
42
74
  | `inbox list [--unread]` · `inbox view <thread>` | Threads agents posted, and one thread with its open ask |
43
- | `inbox answer <thread> <option>` · `inbox answer <thread> -F <json\|->` · `inbox reply <thread> -F <msg\|->` · `inbox close <thread>` | Answer a decide's option, `done` for a to-do, or a form as JSON by field; write on the thread; close it |
44
-
45
- `description edit` replaces the whole description, so run `description show` first and edit that; piped, `show` prints JSON, so take its `body` (`jq -r .body`). Run `vespin <group> --help` for any flag not listed here.
75
+ | `inbox answer <thread> <option>` · `inbox answer <thread> -F <json\|->` · `inbox reply <thread> -F <msg\|->` · `inbox close <thread>` | Answer a decide's option, `done` for a to-do, or a form as JSON by field (`inbox answer <thread>` alone acknowledges a notice, a thread that asks nothing, which tells its agent you saw it); write on the thread; close it, which tells its agent you do not want what it asked |
76
+ | `inbox read <thread>` · `inbox unread <thread>` · `inbox read-all` | Mark a thread read, or unread until you read it again; mark every thread of the workspace read. Yours alone; no agent hears of it |
77
+ | `inbox remind <thread> <when>` (or `snooze`) · `inbox remind <thread> --clear` | Keep a thread out of your inbox until `tomorrow`, `fri 3pm`, or `nov 12 9:30am` (a day alone at 9 AM, in your zone); end the reminder |
78
+ | `inbox start <agent> [-t <title>] -F <msg\|->` | Start a thread with an agent; it reaches the agent as your message, and it answers on the thread |
79
+ | `preferences` · `preferences set --model m --effort e [--context-window standard\|long]` | Your default model, effort, and context window, which an agent start naming none runs on; change it (`vespin models` lists the choices). The default is yours, the same in every workspace |
80
+ | `memory list` · `memory search [words…]` · `memory save <text…> [--replaces <id>]` · `memory forget <id>` | The workspace's shared memory: every memory, the few some words find, one kept as your words (or `-F <file\|->`; `--replaces` corrects one in place), one forgotten for good. Search and save are refused while the workspace has Memory off |
81
+ | `automation list [--task <task>]` · `automation view <id>` | Automations you may read, and one with its prompt and newest runs |
82
+ | `automation create <name> --prompt <file\|-> (--cron <expr> [--timezone tz] \| --github <event> [--label l] [--branch b] \| --sentry <event> \| --trigger <json>) [-R owner/name…] [--task <task>] [--model m --effort e] [--scope personal\|workspace]` | Make an automation that starts an agent on its prompt each time it fires; `--cron` is read in this machine's time zone unless `--timezone` names one. A webhook trigger is made only in the app, which shows its secret once |
83
+ | `automation update <id> [--name] [--prompt] [--enable\|--disable] [trigger flags] [-R…] [--model m --effort e] [--scope]` · `automation run <id>` · `automation delete <id>` | Change one (what you leave out stands), run one now (`-q` prints the agent it started), delete one |
84
+ | `env list` · `env set <NAME>` · `env delete <NAME> [--yes]` | The workspace's environment variables, which every cloud agent in it is handed: their names (never a value); set one, its value read from stdin alone (`printf %s "$TOKEN" \| vespin env set NPM_TOKEN`) and never shown again; delete one. Set one only with a value the person gave you for that variable. Setting and deleting take an owner or admin; `delete` piped needs `--yes` |
85
+ | `integrations list` · `integrations connect <provider> [--account <connection>] [--add] [--no-browser]` | Your integrations' accounts, each by its connection name (`notion`, `notion-2`) and where it stands; begin connecting one, which prints the sign-in link (and opens it at a terminal): nothing is connected until the person signs in there, so hand a coding agent's link to them |
86
+ | `integrations tools <connection>` | The tools an account offers your agents, each by its name and what it does, or why its server listed none |
87
+ | `integrations rename <connection> <label>` · `integrations disconnect <connection> [--yes]` | Name an account; disconnect it, which takes its tools from your agents and revokes its grant. It asks at a terminal; piped or from a coding agent it needs `--yes`, so disconnect only when the person asked |
88
+ | `sentry list` · `sentry disconnect <installation> [--yes]` | The Sentry organizations linked to the workspace; disconnect one (owners and admins), so its issues and alerts start no automation. Linking one takes the app |
89
+ | `mcp clients` · `mcp revoke <client> [--yes]` | The coding agents you allowed on Vespin's MCP server, each by its client id; revoke one, which deletes your consent and its tokens, so it must sign in again. It asks at a terminal; piped or from a coding agent it needs `--yes`, so revoke only when the person asked, and never the client you are running in unless they mean to cut it off |
90
+ | `agent shells <id>` · `agent shell <id> [<shell>] [--title t]` | An agent's Terminal tab shells; open a new one, or attach to one, in this terminal (Ctrl-] detaches). `shell` is interactive and refuses to run piped, so a coding agent hands it to the person |
91
+ | `repo list` · `repo add <owner/name>` · `repo remove <owner/name>` | The GitHub repositories you can choose for a task in the workspace, each marked `app` (the workspace's installation) or `token` (added on a member's own GitHub token), and those your token may add; add one on your token, or remove one added on a token (its adder or an owner or admin) |
92
+ | `repo cat <owner/name> <path> [--commit sha]` · `repo ls <owner/name> [path] [-r]` · `repo skills <owner/name>` | Read a file or list a folder of a repository the workspace reaches, as GitHub holds it at the default branch's head (or a commit, for `cat`), with no task naming it; the skills an agent may load by name there, the repository's then your installed ones |
93
+ | `repo issue <owner/name> <number>` | The title, state, and link of an issue or pull request by its number |
94
+ | `slack show` · `slack set [--notifications on\|off] [--repo <owner/name\|none>] [--channel <channel> [--join\|--leave]]` · `slack disconnect [--yes]` | The workspace's Slack bot: its team, your notifications, the repository Slack starts work in, and (to an owner or admin) its channels. `set` changes your notifications, the workspace's repository, or with `--channel` (id or name) puts the bot in a public channel or takes it out, and `--repo` sets that channel's own. `disconnect` asks first unless `--yes`, which a script must pass; connecting the bot is done in the app |
95
+ | `repo pins` · `repo pin <owner/name>` · `repo unpin <owner/name>` | The repositories you pinned in your sidebar, newest first; pin or unpin one |
96
+ | `skills list` · `skills view <skill>` · `skills install <source> [--preview] [--scope personal\|workspace] [--skill name] [--name n --description d] [--yes]` · `skills remove <skill> [--yes]` | The skills installed for your agents (the workspace's, then yours); read one's `SKILL.md`; install from a GitHub repository, a folder link, an `npx skills add` line, or a skill's text (`-` on stdin): it prints the preview first, then asks, so pass `--yes` when piped, and `--preview` installs nothing; remove one, which asks the same. A skill is named by id or name. Installing hands outside instructions to every agent the scope reaches, so show the person the preview first |
97
+ | `keys list` · `keys set <anthropic\|openai> [--plan]` · `keys remove <provider> [--plan] [--id id] [--yes]` · `keys for-agents <provider> on\|off [--id id]` | Your own provider keys and plans, which pay for your agents: which are set and how each stands (never a key); add an API key from stdin, checked with the provider first, or with `--plan` your Claude plan as `claude setup-token` printed it (a ChatGPT plan connects in the app alone); remove one (the first unless `--id`, which `list` prints); whether your plan pays for agents by default |
98
+ | `github status` | Whether your GitHub account is connected to Vespin, and its login; connecting is done in Vespin's Settings. Your token is never printed |
99
+ | `github token show` · `github token set` · `github token remove [--yes]` | Your own classic GitHub token: the login it belongs to, its status, and expiry (never the token); save one from stdin, replacing the one set, which GitHub checks first; remove it |
100
+ | `setup show [--repo owner/name]` · `setup edit [--repo owner/name] -F <file\|->` | The workspace's cloud sandbox setup: its install script (run once in each build of a repository's base snapshot), each repository's setup script (run once in each new agent sandbox after its checkout), and each repository's run actions. `edit` replaces the install script, or with `--repo` that repository's setup script, whole; an empty script removes it. Saving takes an owner or admin |
101
+ | `setup actions [--repo owner/name]` · `setup actions add --repo owner/name --label l --command c [--default] [--position n]` · `setup actions edit <id> [--label l] [--command c] [--default\|--no-default] [--position n]` · `setup actions remove <id>` | A repository's run actions, the commands a member runs in its cloud agents' sandboxes from the Run menu: list them with their ids, or add, change, move, or remove one. Each change edits the list as it stands, so it never undoes another made meanwhile; an icon is `--emoji` or `--glyph` with `--color`. Saving takes an owner or admin |
102
+ | `agent run <id> <action-id> [--stop]` | Run one of a cloud agent's repository's run actions in its sandbox, in a shell of its own, or interrupt it; a stopped sandbox is refused, so `agent wake` it first |
103
+
104
+ A key or token is read from stdin alone, never from an argument, and no command prints one back; Vespin's MCP server has no tool for either. Pipe one in only where the person handed it to you; otherwise ask them to run `keys set` or `github token set` themselves. `keys remove` and `github token remove` ask at a terminal; piped they need `--yes`, so remove only when the person asked.
105
+
106
+ `description edit` replaces the whole description, so run `description show` first and edit that; piped, `show` prints JSON, so take its `body` (`jq -r .body`). `setup edit` is the same: take `setup show --repo owner/name`'s `.script`, or `setup show`'s `.install.script`. Run `vespin <group> --help` for any flag not listed here.
46
107
 
47
108
  ## Conventions
48
109
 
@@ -82,6 +143,23 @@ Edit a description in a pipe:
82
143
  vespin description show ACME-42 | jq -r .body | sed 's/- \[ \] Tests/- [x] Tests/' | vespin description edit ACME-42 -F -
83
144
  ```
84
145
 
146
+ Hand someone a preview of the server a cloud agent runs on port 3000 (its sandbox must be running):
147
+
148
+ ```sh
149
+ vespin agent ports "$id" # what listens, and what is shared
150
+ url=$(vespin agent share "$id" 3000 -q) # the public link; anyone holding it can open it
151
+ vespin agent share "$id" --stop # close it when done
152
+ ```
153
+
154
+ Review an agent's pull request, then merge it once its checks pass, against the head you read:
155
+
156
+ ```sh
157
+ vespin agent diff "$id" --stat # the files it changes
158
+ vespin agent diff "$id" | less # every patch
159
+ head=$(vespin agent diff "$id" --json | jq -r .pullRequest.headSha)
160
+ vespin agent pr "$id" auto-merge --head "$head" # refused if it pushed since
161
+ ```
162
+
85
163
  Answer the first unread thread:
86
164
 
87
165
  ```sh
@@ -90,6 +168,15 @@ vespin inbox view "$t" --json # read the ask
90
168
  vespin inbox answer "$t" Approve
91
169
  ```
92
170
 
171
+ Continue an agent whose turn failed or was stopped (exit 5 alone, since continuing stops it), with a note, and wait on the new one:
172
+
173
+ ```sh
174
+ status=0; vespin agent wait "$id" || status=$?
175
+ if [ "$status" -eq 5 ]; then
176
+ next=$(echo "Pick up where it stopped" | vespin agent continue "$id" -F - -q) && vespin agent wait "$next"
177
+ fi
178
+ ```
179
+
93
180
  React to how a wait ended:
94
181
 
95
182
  ```sh
@@ -99,3 +186,10 @@ vespin agent wait "$id" --timeout 600; case $? in
99
186
  6) vespin agent send "$id" -F - <<< "Status?" ;;
100
187
  esac
101
188
  ```
189
+
190
+ Read a pull request's chapters, generating them only where none stand yet:
191
+
192
+ ```sh
193
+ state=$(vespin pr chapters acme/app#42 --json | jq -r .pullRequest.chapters.status)
194
+ [ "$state" = none ] && vespin pr chapters acme/app#42 --generate # slow; spends your API key
195
+ ```