vespin 0.0.0 → 0.1.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/LICENSE +201 -0
- package/NOTICE +88 -0
- package/README.md +75 -0
- package/THIRD_PARTY_NOTICES +1167 -0
- package/package.json +29 -9
- package/skills/vespin/SKILL.md +101 -0
- package/vespin.mjs +68854 -0
package/package.json
CHANGED
|
@@ -1,13 +1,33 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vespin",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
5
|
-
"
|
|
6
|
-
"
|
|
7
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Vespin from your terminal: tasks, plans, and coding agents, for people and scripts",
|
|
5
|
+
"license": "Apache-2.0",
|
|
6
|
+
"homepage": "https://vespin.dev",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/ReviewStage/vespin.git",
|
|
10
|
+
"directory": "apps/cli"
|
|
8
11
|
},
|
|
9
|
-
"
|
|
10
|
-
"
|
|
11
|
-
"
|
|
12
|
-
|
|
12
|
+
"bugs": "https://github.com/ReviewStage/vespin/issues",
|
|
13
|
+
"type": "module",
|
|
14
|
+
"bin": {
|
|
15
|
+
"vespin": "vespin.mjs"
|
|
16
|
+
},
|
|
17
|
+
"engines": {
|
|
18
|
+
"node": ">=20"
|
|
19
|
+
},
|
|
20
|
+
"files": [
|
|
21
|
+
"vespin.mjs",
|
|
22
|
+
"README.md",
|
|
23
|
+
"skills",
|
|
24
|
+
"LICENSE",
|
|
25
|
+
"NOTICE",
|
|
26
|
+
"THIRD_PARTY_NOTICES"
|
|
27
|
+
],
|
|
28
|
+
"keywords": [
|
|
29
|
+
"vespin",
|
|
30
|
+
"cli",
|
|
31
|
+
"coding-agents"
|
|
32
|
+
]
|
|
13
33
|
}
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vespin
|
|
3
|
+
description: Drive Vespin from a shell with the `vespin` command: create tasks, read and write their plans, 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, plans, 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.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# vespin
|
|
7
|
+
|
|
8
|
+
`vespin` is Vespin's command-line tool. It is never interactive when stdin is not a terminal, so you can run it from a shell tool.
|
|
9
|
+
|
|
10
|
+
## Setup
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npx vespin login # or: npm i -g vespin && vespin login
|
|
14
|
+
vespin whoami # who is signed in, and their workspaces
|
|
15
|
+
vespin workspace use acme # default workspace; or -w acme / VESPIN_WORKSPACE per command
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`login` opens a browser. Over SSH, or with no browser, run `vespin login --no-browser` and paste back the address the browser ends on; ask the person to do this, since only they can sign in. If `VESPIN_TOKEN` is set it is used first. Exit 3 means sign in again.
|
|
19
|
+
|
|
20
|
+
## Core loop
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
echo "Fix the login redirect" | vespin task create "Login redirect" --start --prompt -
|
|
24
|
+
vespin agent wait <agent-id> --timeout 1800 # exit code says how the turn ended
|
|
25
|
+
vespin agent checkout <agent-id> # fetch its branch and check it out here
|
|
26
|
+
```
|
|
27
|
+
|
|
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 plan (`-F plan.md`); `--prompt <file|->` hands it a prompt instead.
|
|
29
|
+
- To see the work live, use `vespin agent logs <id> --follow`. Without `--follow` it prints the transcript so far.
|
|
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.
|
|
32
|
+
|
|
33
|
+
Other commands:
|
|
34
|
+
|
|
35
|
+
| Command | What it does |
|
|
36
|
+
| --- | --- |
|
|
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
|
+
| `plan show <task>` · `plan edit <task> -F <file\|->` | Print the plan as Markdown; replace it whole |
|
|
39
|
+
| `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 |
|
|
40
|
+
| `agent list [<task>]` · `agent view <id>` | Agents, newest first; one agent's status |
|
|
41
|
+
| `agent send <id> -F <msg\|->` · `agent stop <id>` | Message an agent; stop its turn (what it pushed stays) |
|
|
42
|
+
| `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
|
+
`plan edit` replaces the whole plan, so run `plan show` first and edit that. Run `vespin <group> --help` for any flag not listed here.
|
|
46
|
+
|
|
47
|
+
## Conventions
|
|
48
|
+
|
|
49
|
+
- **Output:** stdout is JSON when piped or captured (what you get from a shell tool), or with `--json`; `-q` prints ids only, one a line. Notes and errors go to stderr, so stdout is the answer alone.
|
|
50
|
+
- **Input:** `-F -` (or `--prompt -`) reads stdin; only one flag may read stdin per command. Pass text through a pipe or file, never as a long argument.
|
|
51
|
+
- **Exit codes:** 0 ok, 1 refused (missing task, bad input, a limit), 2 usage, 3 not signed in, 4 network or server error, 5 the agent's turn failed or was stopped, 6 `--timeout` passed with the turn still running. `agent wait` and `--wait` use 5 and 6; their JSON says which.
|
|
52
|
+
- **Never wait on a prompt:** every id is an explicit argument. If a command needs a person (sign-in, an answer only they can give), stop and ask them.
|
|
53
|
+
|
|
54
|
+
## Anything without a command
|
|
55
|
+
|
|
56
|
+
`vespin api <GET|POST|PUT|PATCH|DELETE> <path> [-F <json|->]` calls any hosted procedure and prints its JSON:
|
|
57
|
+
|
|
58
|
+
```sh
|
|
59
|
+
vespin api GET /api/workspaces
|
|
60
|
+
echo '{"name":"Research"}' | vespin api POST /api/workspaces -F -
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## CLI or MCP
|
|
64
|
+
|
|
65
|
+
Use the CLI when you have a shell: scripting, piping and filtering output (`--json | jq`), waiting on an agent with `agent wait`, streaming with `agent logs --follow`, and checking out an agent's branch locally. It also knows your working folder's repository.
|
|
66
|
+
|
|
67
|
+
Use Vespin's MCP server when you have no shell, or can only call tools. `vespin mcp install claude-code|codex|cursor|vscode` connects an agent to it.
|
|
68
|
+
|
|
69
|
+
## Examples
|
|
70
|
+
|
|
71
|
+
Fan out two agents, wait on both, then check out the first:
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
a=$(echo "Add tests for the redirect" | vespin agent start ACME-42 -F - -q)
|
|
75
|
+
b=$(echo "Update the docs for the redirect" | vespin agent start ACME-42 -F - -q)
|
|
76
|
+
vespin agent wait "$a" && vespin agent wait "$b" && vespin agent checkout "$a"
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Edit a plan in a pipe:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
vespin plan show ACME-42 | sed 's/- \[ \] Tests/- [x] Tests/' | vespin plan edit ACME-42 -F -
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Answer the first unread thread:
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
t=$(vespin inbox list --unread -q | head -1)
|
|
89
|
+
vespin inbox view "$t" --json # read the ask
|
|
90
|
+
vespin inbox answer "$t" Approve
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
React to how a wait ended:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
vespin agent wait "$id" --timeout 600; case $? in
|
|
97
|
+
0) vespin agent checkout "$id" ;;
|
|
98
|
+
5) vespin agent logs "$id" | tail -50 ;;
|
|
99
|
+
6) vespin agent send "$id" -F - <<< "Status?" ;;
|
|
100
|
+
esac
|
|
101
|
+
```
|