@awebai/oats 0.69.9 → 0.69.11
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 +1 -1
- package/bin/oats.mjs +1 -1
- package/docs/capabilities.md +27 -5
- package/docs/capability-manifest.schema.json +8 -0
- package/docs/configuration.md +1 -1
- package/docs/desktop-cli-api.md +3 -1
- package/docs/integrations.md +13 -2
- package/docs/oats-local.schema.json +2 -2
- package/docs/oats-membership.schema.json +1 -1
- package/docs/oats-workspace.schema.json +7 -3
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.10.md +66 -0
- package/docs/release-notes/v0.69.11.md +107 -0
- package/docs/schedules.md +25 -6
- package/docs/souls-and-instances.md +2 -1
- package/docs/upgrading.md +15 -5
- package/docs/workspaces.md +20 -5
- package/lib/instance-resolution.mjs +1 -1
- package/lib/kernel-features.mjs +1 -1
- package/lib/resolve.mjs +51 -8
- package/lib/schedule.mjs +69 -28
- package/lib/workspace.mjs +10 -1
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +684 -385
|
@@ -3,131 +3,274 @@ name: oats-getting-started
|
|
|
3
3
|
description: >-
|
|
4
4
|
The way into OATS (Open Agent Team Specification) for a person who has only
|
|
5
5
|
a coding agent. Asks about their project, installs OATS, OATS Desktop and
|
|
6
|
-
the messaging CLI,
|
|
7
|
-
|
|
8
|
-
this machine to an existing workspace),
|
|
9
|
-
expert, which does the rest, and opens the
|
|
6
|
+
the messaging CLI, creates the workspace's messaging account and team (with
|
|
7
|
+
no sign-in, or on the person's own account if they sign in), writes a new
|
|
8
|
+
workspace's skeleton (or joins this machine to an existing workspace),
|
|
9
|
+
spawns the workspace's setup expert, which does the rest, and opens the
|
|
10
|
+
Desktop on it. Offers the TUI.
|
|
10
11
|
Use for "get started with OATS", "set up / install / adopt OATS", "set up
|
|
11
12
|
OATS for this project", "join our OATS workspace", or when someone gives
|
|
12
|
-
you this file or its URL.
|
|
13
|
+
you this file or its URL. Download this file whole (`curl -fsSL
|
|
14
|
+
https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md`)
|
|
15
|
+
and follow it as written: a summary of it is not the procedure.
|
|
13
16
|
---
|
|
14
17
|
|
|
18
|
+
**Read this whole file, never a summary of it.** If you only have a summary
|
|
19
|
+
(a web fetch that summarises, say), download it whole with
|
|
20
|
+
`curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md`
|
|
21
|
+
and follow it as written.
|
|
22
|
+
|
|
15
23
|
# Getting started with OATS
|
|
16
24
|
|
|
17
25
|
You are the person's own coding agent. This skill takes them from nothing to
|
|
18
26
|
a running **setup expert**: an OATS agent of their workspace that does the
|
|
19
|
-
rest of the setup with them (their repositories, their own coordination
|
|
20
|
-
|
|
27
|
+
rest of the setup with them (their repositories, their own coordination
|
|
28
|
+
and knowledge capabilities, a tracker they already use, their first
|
|
29
|
+
agents). You ask, install,
|
|
21
30
|
write a few files and spawn it. Then you are done.
|
|
22
31
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
`oats
|
|
28
|
-
`<workspace>-oats-setup-expert`.
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
the
|
|
35
|
-
and the steward gets a global aweb address. Steps 1, 5, 7, 8 and 9 say what
|
|
32
|
+
A **workspace** is one Git repository declaring which repositories belong to
|
|
33
|
+
an organisation and which packages it trusts. A **soul** is a durable agent
|
|
34
|
+
role defined in Git; an **instance** is a soul at work, in its own home and
|
|
35
|
+
terminal. A new workspace's setup expert is `oats.framework`'s soul
|
|
36
|
+
`oats-setup-expert` (capabilities `oats.setup` and `oats.onboarding`),
|
|
37
|
+
spawned as `<workspace>-oats-setup-expert`.
|
|
38
|
+
|
|
39
|
+
**A machine found-list** is a JSON file in your prompt whose
|
|
40
|
+
`machine.platform` is set (oats-omarchy's installer writes one). The
|
|
41
|
+
workspace you make is then this machine's own, its setup soul is the
|
|
42
|
+
machine's steward, `oats.machine/steward`, in place of the setup expert, and
|
|
43
|
+
the steward gets a global aweb address; steps 1, 5, 7, 8 and 9 say what
|
|
36
44
|
changes. When the found-list lists a deployment whose `steward` is `true`,
|
|
37
|
-
this machine already has its workspace and steward
|
|
45
|
+
tell the person this machine already has its workspace and steward, and
|
|
38
46
|
stop. Wherever a later step says to ask the
|
|
39
47
|
person, on a machine found-list you tell them what happened, as it is, and
|
|
40
48
|
stop instead: the person answers nothing after step 1.
|
|
41
49
|
|
|
42
50
|
**How to work.**
|
|
43
51
|
- **Ask first, then run.** Ask everything in one round (step 1), then run the
|
|
44
|
-
steps yourself and read back what each did.
|
|
52
|
+
steps yourself and read back what each did. Touch nothing you were not
|
|
53
|
+
asked to (see "Never").
|
|
54
|
+
- **The time budget.** The whole setup should take a few minutes, and only
|
|
55
|
+
seconds of the person's time: their answers, a login to approve, a secret
|
|
56
|
+
to type. Don't wait more than about a minute for the Desktop's background
|
|
57
|
+
download once the CLI is installed: if it hasn't verified by then, go on
|
|
58
|
+
without the Desktop and record that in the hand-over (the person can
|
|
59
|
+
install it later with the setup expert, through `/oats-upgrade`).
|
|
60
|
+
- **Talk to a newcomer, in everyday words.** They may not know what a
|
|
61
|
+
repository, Git, a terminal or a command is. Talk about their projects,
|
|
62
|
+
code and folders: "your agents' shared setup" (the workspace), "the setup
|
|
63
|
+
assistant" (the setup expert), "the group your agents talk in" (the team),
|
|
64
|
+
"the folder where your agents live" (`D`), and GitHub as "where your code
|
|
65
|
+
is kept online, so your agents and your colleagues can reach it". Unless
|
|
66
|
+
they ask or use the word first, don't say repository, workspace file,
|
|
67
|
+
soul, instance, root, harness, readiness, deployment, capability, CLI or
|
|
68
|
+
token, and don't show a file path, a command, an error code or raw output,
|
|
69
|
+
except the name the Desktop shows for the setup expert, which they click.
|
|
70
|
+
When a command fails, say in one sentence what it means and what you do
|
|
71
|
+
next. Keep a check's output and exit status for yourself
|
|
72
|
+
(`2>&1; echo "exit=$?"`), and don't show an expected failure as an error.
|
|
73
|
+
Before a step that takes over half a minute, say what it does and about
|
|
74
|
+
how long it takes.
|
|
75
|
+
- **One yes covers the changes to their computer.** Step 1's message lists
|
|
76
|
+
them in plain words, and their yes covers every one: don't ask again step
|
|
77
|
+
by step. The list, from step 2's checks: the tools you install (on Linux
|
|
78
|
+
per user, under `~/.local`; on macOS with Homebrew), the line that puts
|
|
79
|
+
them on their PATH in their shell's startup file (`~/.local/bin` on Linux;
|
|
80
|
+
on macOS, Homebrew's `brew shellenv` line, only when Homebrew is new), the
|
|
81
|
+
aweb channel plugin in Claude (Claude only) or pi's aweb extension,
|
|
82
|
+
without its skills (pi only), the folder where their agents
|
|
83
|
+
live (`D`, spelled out) marked as trusted by their coding agent, OATS
|
|
84
|
+
Desktop with its app-launcher entry, each system package step 2 found
|
|
85
|
+
missing, with what it is for, Git told to use their GitHub login (`gh auth
|
|
86
|
+
setup-git`, in `~/.gitconfig`), on Linux npm's per-user folder (in
|
|
87
|
+
`~/.npmrc`), and, for a new workspace whose host step 6 creates, the
|
|
88
|
+
private repository `<owner>/<repo>` on GitHub, or, when the host is an
|
|
89
|
+
existing repository (a monorepo), the two setup files committed and
|
|
90
|
+
pushed straight to `<owner>/<repo>`'s default branch, which runs its
|
|
91
|
+
automatic checks or deploys if it has any (or a pull request, step 7).
|
|
92
|
+
Name each change by what and where, not by kind: a permission check that
|
|
93
|
+
reads the conversation lets a step through only when their yes named it.
|
|
94
|
+
Run each change on the list as its own command, never batched with other
|
|
95
|
+
changes, so that check sees it by the name their yes gave it (a fenced
|
|
96
|
+
block below that makes one change on the list counts as one).
|
|
97
|
+
Never run `sudo` for something that was not on that list, even where no
|
|
98
|
+
password is asked; if they say no to a system package, tell them what will
|
|
99
|
+
not work without it.
|
|
100
|
+
- **When your harness's permission check stops a step on the list** and
|
|
101
|
+
asks the person to approve, tell them it is one of the changes they said
|
|
102
|
+
yes to. If it refuses the step outright, never run it another way
|
|
103
|
+
(another shell, a script, a window you open), and never split it into
|
|
104
|
+
pieces or re-run its parts, `sudo` included: ask the person once, naming
|
|
105
|
+
the change, whether you may make it, and try again once on their yes.
|
|
106
|
+
Still refused: tell them in one sentence which change is missing and what
|
|
107
|
+
won't work without it, and go on where you can. Never ask them to type a
|
|
108
|
+
command with `!`.
|
|
45
109
|
- **Secrets.** The person types only what you must never hold: passwords,
|
|
46
|
-
tokens and logins
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
password, an aweb invite token)
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
- Run each fenced block below as one command.
|
|
56
|
-
- When a later block needs a value an earlier one found (`V`, `ARCH`, a
|
|
57
|
-
path, the team id `T`), write that value in literally.
|
|
110
|
+
tokens and logins, by a browser device flow you start (GitHub, step 3; the
|
|
111
|
+
messaging login, step 5, only for the team on their own aweb account) or
|
|
112
|
+
by the exact command in their own terminal, which you open for them (a
|
|
113
|
+
`sudo` or Homebrew password, an aweb invite token; below). Never ask for a
|
|
114
|
+
secret in the conversation or write one to a file ("Never").
|
|
115
|
+
- **Your shell may keep nothing between commands** (many harnesses start
|
|
116
|
+
each command in a new shell, in the same starting folder). Run each fenced
|
|
117
|
+
block below as one command, and write in literally any value an earlier
|
|
118
|
+
one found (`V`, `ARCH`, a path, the team id `T`).
|
|
58
119
|
- **Sandboxes.** If your harness sandboxes commands, these steps need network
|
|
59
120
|
access and writes in the home folder: ask the person to approve them.
|
|
60
121
|
Starting the Desktop and opening a terminal also run outside the sandbox.
|
|
61
|
-
- **Their own terminal, opened by you.**
|
|
62
|
-
|
|
63
|
-
|
|
122
|
+
- **Their own terminal, opened by you.** Write the command to a file
|
|
123
|
+
(`mktemp`; it holds no secret) after a first line
|
|
124
|
+
`export PATH="<node dir>:<oats dir>:<harness dir>:$HOME/.local/bin:$PATH"`,
|
|
64
125
|
with the folders `command -v node`, `command -v oats` and `command -v
|
|
65
|
-
<harness>` print written in (a window may load no shell startup file,
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
that runs it, with `F` the file's path written in:
|
|
126
|
+
<harness>` print written in (a window may load no shell startup file), and
|
|
127
|
+
a last line `printf '\nDone: close this window.\n'; read -r _`. Then open
|
|
128
|
+
a window that runs it, with `F` the file's path written in:
|
|
69
129
|
- **macOS:** `osascript -e 'tell application "Terminal" to do script "sh F"'`.
|
|
70
130
|
The first time, macOS may ask the person to let you control Terminal.
|
|
71
131
|
- **Linux:** `systemd-run --user --collect --quiet -p KillMode=process -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY xdg-terminal-exec sh "F"`,
|
|
72
132
|
or `x-terminal-emulator -e sh "F"` in place of `xdg-terminal-exec` where
|
|
73
133
|
only that exists. Through `systemd-run` the window gets their desktop
|
|
74
|
-
session's environment, not yours.
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
134
|
+
session's environment, not yours. If `systemd-run` fails (for example
|
|
135
|
+
"Failed to connect to bus", when there is no user session bus), start
|
|
136
|
+
the terminal directly, detached, before you give them a command to type:
|
|
137
|
+
`setsid -f xdg-terminal-exec sh "F" </dev/null >/dev/null 2>&1`, or
|
|
138
|
+
`setsid -f x-terminal-emulator -e sh "F" </dev/null >/dev/null 2>&1`.
|
|
139
|
+
It uses the `DISPLAY`, `WAYLAND_DISPLAY`, `XAUTHORITY` and
|
|
140
|
+
`XDG_RUNTIME_DIR` your environment already has; when they are unset,
|
|
141
|
+
don't guess them: take "When no window opens".
|
|
142
|
+
|
|
143
|
+
Tell them what to type there, and ask whether the window opened (a
|
|
144
|
+
command that started is no proof of one). Check the result with a
|
|
78
145
|
read-only command, never by reading the window, then delete the file.
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
the workspace's host there.
|
|
146
|
+
When no window opens: for a secret, a login or a `sudo` or Homebrew
|
|
147
|
+
password, give them the command to run in a terminal of their own, the
|
|
148
|
+
one time a person types a command; otherwise tell them what did not
|
|
149
|
+
happen, and leave it to the setup expert.
|
|
84
150
|
|
|
85
151
|
## 1. Ask, in one round
|
|
86
152
|
|
|
87
153
|
On a machine found-list, ask the machine's round below instead of this list.
|
|
88
154
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
155
|
+
**First, step 2's checks.** They only read, so run them before the message
|
|
156
|
+
(not its installs): the changes to their computer that the message lists
|
|
157
|
+
are what they found missing.
|
|
158
|
+
|
|
159
|
+
**The message.** Ask three things, and in the same message propose
|
|
160
|
+
everything else as defaults they accept with "ok" or change:
|
|
161
|
+
1. What they want their agents to help with (the use case), and where their
|
|
162
|
+
notes and documentation live today, if anywhere (a docs repository, a
|
|
163
|
+
wiki, Notion, Confluence).
|
|
164
|
+
2. Which projects the agents should work on: the folders on this computer,
|
|
165
|
+
or where the code is kept online. Work out the rest yourself (where
|
|
166
|
+
each is cloned, whether it's private: `git -C <dir> remote -v`,
|
|
167
|
+
`gh repo view <owner>/<repo> --json visibility`); ask only what you
|
|
168
|
+
can't find.
|
|
169
|
+
3. Whether they're starting fresh, or joining agents that someone on their
|
|
170
|
+
team already set up (then the reference that person gives them).
|
|
171
|
+
|
|
172
|
+
Then the defaults, one plain line each: the workspace name, where its two
|
|
173
|
+
files live (the host, in plain words: "kept with your notes-app code on
|
|
174
|
+
GitHub", or "in a new private space on your GitHub, `<workspace>-oats`"),
|
|
175
|
+
the messaging account, the folder where their agents live, OATS Desktop
|
|
176
|
+
installed and opened, the name on their commits (only when Git has none),
|
|
177
|
+
where their agents keep track of work (tasks, below), and the changes to
|
|
178
|
+
their computer ("How to work"). Don't ask for the GitHub
|
|
179
|
+
owner (below), or for the coding agent the setup expert runs on: it is you,
|
|
180
|
+
when you are `claude`, `codex` or `pi`. When an answer changes a default (a
|
|
181
|
+
name, a host, a fresh start or a join), derive every default again and show
|
|
182
|
+
the final values in one short message before you go on. The rules:
|
|
183
|
+
|
|
94
184
|
- **A new workspace, or an existing one?**
|
|
95
185
|
- Existing: its repository reference, for example
|
|
96
|
-
`git:github.com/acme/acme-oats
|
|
97
|
-
|
|
186
|
+
`git:github.com/acme/acme-oats`, from whoever runs that workspace. Until
|
|
187
|
+
step 8, take its name from the reference's repository name without a
|
|
188
|
+
trailing `-oats` (`acme`), for the folder `D` only. Step 8 gives its real
|
|
189
|
+
name, which `A` and the setup expert's name use.
|
|
98
190
|
- New: the **workspace name**: lowercase letters and digits, words joined
|
|
99
191
|
by single `-` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), for example `acme`. Refuse
|
|
100
|
-
`agents`: OATS keeps instance homes in a folder of that name.
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
192
|
+
`agents`: OATS keeps instance homes in a folder of that name. Default:
|
|
193
|
+
their project's name (its repository's, or its folder's), normalised as
|
|
194
|
+
in the machine's round, with repeated `-` collapsed and a leading or
|
|
195
|
+
trailing `-` dropped (`My_App_` gives `my-app`); with no project, ask
|
|
196
|
+
for a name.
|
|
197
|
+
- **New workspace: the host,** the one repository that holds the
|
|
198
|
+
workspace's files:
|
|
199
|
+
- **One repository (a monorepo):** that repository, the files at its root;
|
|
200
|
+
its owner and name come from its remote.
|
|
105
201
|
- **Several repositories:** a dedicated host repository, private, created
|
|
106
|
-
in step 6
|
|
107
|
-
|
|
108
|
-
- **No repositories yet:**
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
the
|
|
202
|
+
in step 6 and named `<workspace>-oats`. Its owner is the one their
|
|
203
|
+
repositories share, when they share one; otherwise their GitHub login.
|
|
204
|
+
- **No repositories yet:** their first one, created in step 6, named
|
|
205
|
+
`<workspace>`, under their GitHub login.
|
|
206
|
+
|
|
207
|
+
The GitHub login is `gh api user --jq .login`: now, if gh is logged in,
|
|
208
|
+
else after step 3; until then the line says "your GitHub account". If any
|
|
209
|
+
repository of theirs is private, the host is private: the workspace file
|
|
210
|
+
names every member.
|
|
114
211
|
- **Messaging between agents:** which messaging capability, or none. The
|
|
115
|
-
default, and the one this skill sets up, is aweb (`oats.aweb`):
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
212
|
+
default, and the one this skill sets up, is aweb (`oats.aweb`): agents
|
|
213
|
+
that can mail each other can coordinate. For
|
|
214
|
+
another, leave messaging out here: the setup expert adds it. A new
|
|
215
|
+
workspace with aweb gets an aweb account of its own, which step 9 creates
|
|
216
|
+
with no sign-in:
|
|
217
|
+
- the messaging account's name `N`: the part of every agent's address
|
|
218
|
+
before the `/`, in the same form as the workspace name, default
|
|
219
|
+
`<workspace>-oats`. The root's name `A` is `<workspace>-root`.
|
|
220
|
+
- Tell them they attach themselves to that account later in the setup, with
|
|
221
|
+
the setup expert. Only if they want the team on their own aweb account
|
|
222
|
+
now, they sign in to it in their browser in step 5 instead.
|
|
120
223
|
- **The harness for the setup expert:** `claude`, `codex` or `pi`. Default:
|
|
121
224
|
the one you are, if it is one of these.
|
|
122
|
-
- **The deployment directory `D`:** where OATS lives on this machine.
|
|
123
|
-
folder but their home folder
|
|
124
|
-
`oats onboard`
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
225
|
+
- **The deployment directory `D`:** where OATS lives on this machine.
|
|
226
|
+
Default: `<home>/Agents/<workspace>`; any folder but their home folder
|
|
227
|
+
itself works (`oats onboard` lists it in `~/.oats/config/deployments.json`,
|
|
228
|
+
where the Desktop and the TUI find it). Write `D` everywhere as an absolute
|
|
229
|
+
path, with the home folder spelled out: never `~`, which the shell does not
|
|
230
|
+
expand inside quotes.
|
|
231
|
+
- **OATS Desktop:** installed and started unless they decline. Offer the TUI
|
|
232
|
+
(`oats tui`, a terminal client, preview) only if they ask for a terminal
|
|
233
|
+
client or decline the Desktop.
|
|
234
|
+
- **The name on their commits:** whenever step 2's checks printed
|
|
235
|
+
`NO_GIT_IDENTITY`, and only for a new workspace (step 7 commits only for
|
|
236
|
+
one). Default: the name Git already has (`git config --global user.name`),
|
|
237
|
+
when it has one; else their computer account's full name
|
|
238
|
+
(`getent passwd "$(id -un)" | cut -d: -f5 | cut -d, -f1` on Linux, `id -F`
|
|
239
|
+
on macOS); when that is empty or just their login name capitalised
|
|
240
|
+
(`Ubuntu` for `ubuntu`), their GitHub profile name, found after step 3
|
|
241
|
+
(`gh api user --jq '.name // .login'`), and the line says "your GitHub
|
|
242
|
+
name". Step 7 uses it without asking again.
|
|
243
|
+
- **Tasks, a new workspace with aweb only:** where the agents track work.
|
|
244
|
+
The default is aweb's task list (`oats.aweb-tasks`). It gives way only to
|
|
245
|
+
a tracker the person already uses, which you find, never ask about. The
|
|
246
|
+
first message can't know their projects yet, so its line says "aweb's
|
|
247
|
+
task list, unless your projects already use a tracker"; once they have
|
|
248
|
+
named them, look, and the final-values message (above) gives the result.
|
|
249
|
+
A tracker is:
|
|
250
|
+
- **GitHub issues:** a project's GitHub repository with an issue, open or
|
|
251
|
+
closed, updated in the last 180 days and not opened by a bot:
|
|
252
|
+
`gh issue list -R <owner>/<repo> --state all --limit 1 --json number --jq length --search "updated:>=<date 180 days ago> -author:app/renovate -author:app/dependabot"`
|
|
253
|
+
prints `1`. Issues switched on but unused are no tracker, and so is a
|
|
254
|
+
repository with issues switched off (the command says they are
|
|
255
|
+
disabled). If gh isn't logged in yet, step 3 runs this check after its
|
|
256
|
+
login.
|
|
257
|
+
- **Jira, Linear or another tracker:** the person named it in their
|
|
258
|
+
answers, or ticket keys are in the project's recent branch names or
|
|
259
|
+
commit subjects (`git -C <dir> log -50 --format=%s`,
|
|
260
|
+
`git -C <dir> branch -a --format='%(refname:short)'`): one prefix
|
|
261
|
+
matching `[A-Z][A-Z0-9]{1,9}-[1-9][0-9]*` with two different numbers,
|
|
262
|
+
other than `UTF`, `SHA`, `ISO`, `RFC`, `CVE`, `ES`, `HTTP`, `TLS`,
|
|
263
|
+
`PEP` and `GPT`.
|
|
264
|
+
|
|
265
|
+
With a tracker, the agents keep using it: the line says so ("your agents
|
|
266
|
+
use your GitHub issues; the setup assistant connects them") and step 7
|
|
267
|
+
writes `tasks: none`; the setup expert connects the tracker with the
|
|
268
|
+
person later. Without one, the line says "aweb's task list, shared by your
|
|
269
|
+
agents". Ask only when unsure, as the final-values message's one open
|
|
270
|
+
line, prefilled with the answer you'd pick: ticket keys the person didn't
|
|
271
|
+
name, a project kept somewhere other than GitHub (its issues can't be
|
|
272
|
+
read), or a `gh issue list` that failed for another reason. An existing
|
|
273
|
+
workspace or a machine found-list has no tasks line: its owner decided.
|
|
131
274
|
|
|
132
275
|
**The machine's round.** Read the found-list, then ask only these choices,
|
|
133
276
|
together, each with its default and one line on what it is. Enter, or
|
|
@@ -154,32 +297,57 @@ steward takes them up with the person later.
|
|
|
154
297
|
- **OATS Desktop:** installed and started by default; the TUI not opened.
|
|
155
298
|
- **The harness:** the found-list's `harness`. Ask only when it names none,
|
|
156
299
|
with the one you are as the default.
|
|
300
|
+
- **The name on its commits:** as in the list above, when Git has none.
|
|
301
|
+
- **The changes to this computer:** the list in "How to work", from step 2's
|
|
302
|
+
checks, as one line; "yes" covers it.
|
|
303
|
+
|
|
304
|
+
**This machine's name** (an existing workspace only, below) is its short
|
|
305
|
+
hostname (`hostname -s`, never the full domain name), normalised as in the
|
|
306
|
+
machine's round: `ada-s-laptop`. When that is a name many machines share
|
|
307
|
+
(`localhost`, `ubuntu`, `debian`, `fedora`, `raspberrypi`, or a model name
|
|
308
|
+
such as `macbook-pro`), add `-` and the first eight characters of a keyed
|
|
309
|
+
hash of the machine's id: `ubuntu-7d41e0c9`. Never the id itself: the whole
|
|
310
|
+
team sees this name, and the id is confidential (machine-id(5)). Linux:
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
printf 'oats-machine-name:%s' "$(cat /etc/machine-id)" | sha256sum | cut -c1-8
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
macOS:
|
|
317
|
+
|
|
318
|
+
```bash
|
|
319
|
+
printf 'oats-machine-name:%s' "$(ioreg -rd1 -c IOPlatformExpertDevice | awk -F'"' '/IOPlatformUUID/{print $4}')" | shasum -a 256 | cut -c1-8
|
|
320
|
+
```
|
|
157
321
|
|
|
158
322
|
## 2. Check, and install what is missing
|
|
159
323
|
|
|
324
|
+
You ran this step's checks (the commands that only read) before step 1's
|
|
325
|
+
message. Install now what they found missing, as step 1's yes allows.
|
|
326
|
+
`sudo -n true` is not one of those checks: it runs after the yes, right
|
|
327
|
+
before the first line that needs `sudo`.
|
|
328
|
+
|
|
160
329
|
```bash
|
|
161
|
-
uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
330
|
+
uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g; { git config --global user.name && git config --global user.email; } >/dev/null || echo NO_GIT_IDENTITY
|
|
162
331
|
```
|
|
163
332
|
|
|
164
333
|
- **Versions:** Node 22 or later; Git 2.45 or later recommended (partial
|
|
165
|
-
caches
|
|
166
|
-
(step
|
|
334
|
+
caches; older Git works with whole-tree fetches); `gh` 2.49 or later
|
|
335
|
+
(step 3 uses `gh attestation`).
|
|
167
336
|
- **The harness** they chose must be installed and logged in (`claude
|
|
168
337
|
--version`, `codex --version` or `pi --version`).
|
|
169
338
|
- **macOS:** with Homebrew (`brew --version`), `brew install node git tmux gh`.
|
|
170
|
-
- **Without Homebrew,** it
|
|
171
|
-
for them ("How to work") with the
|
|
172
|
-
<https://brew.sh
|
|
339
|
+
- **Without Homebrew,** it asks for their password, so it installs in
|
|
340
|
+
their own Terminal, which you open for them ("How to work"), with the
|
|
341
|
+
command under “Install Homebrew” on <https://brew.sh>. Then add its
|
|
173
342
|
`brew shellenv` line to their `~/.zprofile` yourself, as its “Next
|
|
174
|
-
steps” say
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
(`/usr/local/bin/brew` on Intel), or ask them to restart you.
|
|
343
|
+
steps” say, and start each later command of yours with
|
|
344
|
+
`eval "$(/opt/homebrew/bin/brew shellenv)"` (`/usr/local/bin/brew` on
|
|
345
|
+
Intel): your running process does not see their new PATH.
|
|
178
346
|
- **Linux:**
|
|
179
347
|
- **Packages:** the distribution's, for git and tmux.
|
|
180
348
|
- **gh:** from GitHub's own apt or rpm repository
|
|
181
|
-
(<https://github.com/cli/cli/blob/trunk/docs/install_linux.md>),
|
|
182
|
-
|
|
349
|
+
(<https://github.com/cli/cli/blob/trunk/docs/install_linux.md>), not the
|
|
350
|
+
distribution's, which is too old.
|
|
183
351
|
- **Node 22:** distributions ship older ones (Debian 13 has 20, Ubuntu
|
|
184
352
|
24.04 has 18). On Debian and Ubuntu, x64 or arm64, from NodeSource:
|
|
185
353
|
|
|
@@ -192,23 +360,34 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
|
192
360
|
```bash
|
|
193
361
|
sudo add-apt-repository -y ppa:git-core/ppa && sudo apt-get update && sudo apt-get install -y git
|
|
194
362
|
```
|
|
195
|
-
- **
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
363
|
+
- **The Desktop's system libraries** (x64): ALSA and FUSE 2. Check:
|
|
364
|
+
|
|
365
|
+
```bash
|
|
366
|
+
for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -p | grep -q "$l" || echo "MISSING $l"; done
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
- **ALSA missing:** the Desktop needs it, so step 1's list names its
|
|
370
|
+
package: `libasound2t64` on Ubuntu 24.04 and Debian 13, `libasound2`
|
|
371
|
+
before them, `alsa-lib` on Fedora.
|
|
372
|
+
- **FUSE 2 missing:** install nothing. Step 10 starts the AppImage with
|
|
373
|
+
`--appimage-extract-and-run`, which needs no FUSE.
|
|
374
|
+
- **Passwords:** a line that needs `sudo` runs only after their yes in
|
|
375
|
+
step 1, and goes to their own terminal unless `sudo -n true` succeeds.
|
|
376
|
+
- **Then check again** with `node --version` and `git --version`. Node still
|
|
377
|
+
under 22 (another distribution, or where that route does not apply): stop,
|
|
378
|
+
tell the person the minimum and the version found, and go no further until
|
|
379
|
+
they have installed it. Git under 2.45 is no stop: tell them it works with
|
|
380
|
+
whole-tree fetches, and go on.
|
|
381
|
+
- **npm's global folder** must be writable for step 4's installs
|
|
382
|
+
(`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node under
|
|
383
|
+
`/usr`, as NodeSource installs it), set a per-user prefix,
|
|
384
|
+
`npm config set prefix ~/.local`, as step 1's list said (when Node will
|
|
385
|
+
come from NodeSource, the list names the per-user folder and its PATH
|
|
386
|
+
line). Then start each later command of yours with
|
|
387
|
+
`export PATH="$HOME/.local/bin:$PATH"`, and add that line to their shell's
|
|
209
388
|
startup file yourself, so their own terminal finds `oats` too, and tell
|
|
210
|
-
them
|
|
211
|
-
|
|
389
|
+
them: `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc` (for fish,
|
|
390
|
+
`fish -c 'fish_add_path ~/.local/bin'` instead).
|
|
212
391
|
|
|
213
392
|
```bash
|
|
214
393
|
RC="$HOME/.bashrc"; case "$SHELL" in *zsh) RC="$HOME/.zshrc";; esac; grep -qsF '$HOME/.local/bin' "$RC" || printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$RC"; echo "$RC"
|
|
@@ -217,25 +396,24 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
|
217
396
|
|
|
218
397
|
## 3. Log in to GitHub
|
|
219
398
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
first:
|
|
399
|
+
Always run this check, even when step 2 just installed gh (an existing gh
|
|
400
|
+
config or `GH_TOKEN` may already log it in), and start the device login
|
|
401
|
+
below only if it says gh is not logged in.
|
|
224
402
|
|
|
225
403
|
```bash
|
|
226
404
|
gh auth status
|
|
227
405
|
```
|
|
228
406
|
|
|
229
407
|
If it is logged in, let Git use it (without this, step 6's push and step 8
|
|
230
|
-
fail with "could not read Username"), then go
|
|
408
|
+
fail with "could not read Username"), then go on below:
|
|
231
409
|
|
|
232
410
|
```bash
|
|
233
411
|
gh auth setup-git
|
|
234
412
|
```
|
|
235
413
|
|
|
236
|
-
If
|
|
237
|
-
|
|
238
|
-
|
|
414
|
+
If not, start the login yourself, detached and without a terminal (your
|
|
415
|
+
harness's background mode if it has one); gh prints a one-time code and a
|
|
416
|
+
URL instead of opening a browser, and waits:
|
|
239
417
|
|
|
240
418
|
```bash
|
|
241
419
|
nohup gh auth login --web --hostname github.com --git-protocol https --skip-ssh-key </dev/null >"$HOME/.oats-gh-login.txt" 2>&1 &
|
|
@@ -249,62 +427,131 @@ cat "$HOME/.oats-gh-login.txt"
|
|
|
249
427
|
|
|
250
428
|
- **Give the person the code, and open the URL** in their browser
|
|
251
429
|
(`open https://github.com/login/device` on macOS, `xdg-open …` on Linux;
|
|
252
|
-
give them the URL if that fails).
|
|
253
|
-
|
|
254
|
-
minutes; then start again.
|
|
430
|
+
give them the URL if that fails). They enter the code (not a secret) and
|
|
431
|
+
approve. It expires after about 15 minutes; then start again.
|
|
255
432
|
- **Once they say they approved,** check the login and let Git use it:
|
|
256
433
|
|
|
257
434
|
```bash
|
|
258
435
|
gh auth status && gh auth setup-git && rm -f "$HOME/.oats-gh-login.txt"
|
|
259
436
|
```
|
|
260
437
|
|
|
261
|
-
The token stays in gh's store and never reaches you.
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
438
|
+
The token stays in gh's store and never reaches you. Now run step 1's
|
|
439
|
+
GitHub-issues check if it waited for this login; a tracker it finds changes
|
|
440
|
+
the tasks line, so tell the person in one sentence. If the check fails for
|
|
441
|
+
another reason (access refused, say), ask now in one line, prefilled with
|
|
442
|
+
their GitHub issues (`tasks: none`): never aweb's task list beside a
|
|
443
|
+
tracker you couldn't rule out. That is all the Git
|
|
444
|
+
setup this needs: an SSH key, commit signing and the DCO sign-off are the
|
|
445
|
+
setup expert's `/oats-git-setup`, when Git access is broken or the person
|
|
446
|
+
wants them.
|
|
265
447
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
The Desktop accepts a band of CLI versions around its own, so install it
|
|
269
|
-
first, then the CLI of the same version `V`. Find `V`, and on macOS `ARCH`:
|
|
448
|
+
**Then find the OATS version `V`,** and on macOS `ARCH`; step 4 installs the
|
|
449
|
+
CLI and the Desktop of this one version:
|
|
270
450
|
|
|
271
451
|
```bash
|
|
272
452
|
npm view @awebai/oats version
|
|
273
453
|
sysctl -n hw.optional.arm64 2>/dev/null # macOS: 1 means ARCH=arm64, otherwise ARCH=x64
|
|
274
454
|
```
|
|
275
455
|
|
|
276
|
-
**
|
|
277
|
-
|
|
278
|
-
|
|
456
|
+
**Then start the Desktop's download, in the background,** unless they
|
|
457
|
+
declined the Desktop or this machine has none (Linux arm64, step 4); it runs
|
|
458
|
+
while step 4 installs the CLI. With `V` written in, and `F` the release
|
|
459
|
+
file: `oats-desktop-V-linux-x86_64.AppImage` on Linux x64,
|
|
460
|
+
`oats-desktop-V-mac-ARCH.zip` on macOS (where `shasum -a 256 -c -` replaces
|
|
461
|
+
`sha256sum -c -`). It prints `VERIFIED` only when the download, the
|
|
462
|
+
checksum and the release's attestation all pass:
|
|
463
|
+
|
|
464
|
+
```bash
|
|
465
|
+
W="$(mktemp -d)" && echo "$W" && { nohup sh -c 'cd "$1" && gh release download "vV" -R awebai/oats -p "F" -p SHA256SUMS.txt && grep " F\$" SHA256SUMS.txt | sha256sum -c - && gh attestation verify "F" --repo awebai/oats && echo VERIFIED; echo DONE' sh "$W" </dev/null >"$W.log" 2>&1 & }
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
Write the folder it prints in as `<W>` in step 4.
|
|
469
|
+
|
|
470
|
+
## 4. Install OATS Desktop, the CLI and the messaging CLI
|
|
471
|
+
|
|
472
|
+
The CLI and the Desktop are both of version `V` (step 3). **First the CLI,
|
|
473
|
+
and for pi its bridge,** while the Desktop's download runs:
|
|
474
|
+
|
|
475
|
+
```bash
|
|
476
|
+
npm install -g "@awebai/oats@V" && oats version
|
|
477
|
+
pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
**A new workspace needs `oats.framework` 1.19.0 or later** (its setup
|
|
481
|
+
expert attaches the person to the workspace's messaging account). Read the
|
|
482
|
+
installed CLI's catalog:
|
|
483
|
+
|
|
484
|
+
```bash
|
|
485
|
+
node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
It prints the two refs, for example `oats-framework/v1.21.0 v1.35.0`. If the
|
|
489
|
+
framework's version (after the `/`) is below `1.19.0`, or with aweb
|
|
490
|
+
`oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
|
|
491
|
+
skill: stop, and tell the person to wait for the next OATS
|
|
492
|
+
release. Never write a setup soul into the workspace in its place.
|
|
493
|
+
|
|
494
|
+
**With aweb, the messaging CLI `aw`, and the harness's aweb channel,** which
|
|
495
|
+
wakes an agent when mail arrives (skip this without messaging): Claude
|
|
496
|
+
`claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
|
|
497
|
+
pi `pi install npm:@awebai/pi`, then its entry in pi's `settings.json` set
|
|
498
|
+
to load none of the skills it bundles (pi's extension is installed without
|
|
499
|
+
its skills, so it puts none on the computer; each agent gets its own);
|
|
500
|
+
Codex nothing (the setup expert sets up its wake). Claude's aweb channel
|
|
501
|
+
plugin still carries one skill of its own, until aweb ships it without
|
|
502
|
+
(a known gap). The pi entry, which matches `npm:@awebai/pi` alone or with
|
|
503
|
+
`@` and a version, never another `@awebai/pi-…` package, and prints it so
|
|
504
|
+
you can check `"skills":[]`:
|
|
505
|
+
|
|
506
|
+
```bash
|
|
507
|
+
node -e 'const fs=require("fs"),path=require("path"),os=require("os");const f=path.join(process.env.PI_CODING_AGENT_DIR||path.join(os.homedir(),".pi","agent"),"settings.json");const s=JSON.parse(fs.readFileSync(f,"utf8"));const ours=(e)=>/^npm:@awebai\/pi(@|$)/.test(typeof e==="string"?e:e&&e.source||"");s.packages=(s.packages||[]).map((e)=>ours(e)?{...(typeof e==="object"?e:{}),source:typeof e==="string"?e:e.source,skills:[]}:e);fs.writeFileSync(f,JSON.stringify(s,null,2)+"\n");console.log(JSON.stringify(s.packages.filter(ours)))'
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
```bash
|
|
511
|
+
npm install -g @awebai/aw && aw version
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
`aw` must be 1.36.33 or later.
|
|
515
|
+
|
|
516
|
+
**Then the Desktop. Every step verifies before it installs.** Wait for step
|
|
517
|
+
3's download, then read its log. Run this once: it waits up to a minute
|
|
518
|
+
for a `DONE` line ("How to work", the time budget):
|
|
519
|
+
|
|
520
|
+
```bash
|
|
521
|
+
for i in $(seq 60); do grep -qx DONE "<W>.log" && break; sleep 1; done; tail -n 5 "<W>.log"
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
Install the Desktop only when the log has a `VERIFIED` line. If a download or
|
|
525
|
+
a check failed (its assets can lag the npm package), or it still has not
|
|
526
|
+
finished, go on without the Desktop, say so, and record it in the
|
|
527
|
+
hand-over: the person can install it later with the setup expert, through
|
|
528
|
+
`/oats-upgrade`. Never skip a check to
|
|
529
|
+
make it install, and never install or open this download before its
|
|
530
|
+
attestation has passed. A Desktop installed before this run stays as it is.
|
|
279
531
|
|
|
280
|
-
**macOS.** In one block, with `V` and `ARCH` written in.
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
line below:
|
|
532
|
+
**macOS.** In one block, with `V` and `ARCH` written in. `/Applications`
|
|
533
|
+
needs an administrator; for a standard user, use `$HOME/Applications`
|
|
534
|
+
(`mkdir -p "$HOME/Applications"`) in its place in every line below:
|
|
284
535
|
|
|
285
536
|
```bash
|
|
286
|
-
|
|
287
|
-
gh release download "vV" -R awebai/oats -p "oats-desktop-V-mac-ARCH.zip" -p SHA256SUMS.txt &&
|
|
288
|
-
grep " oats-desktop-V-mac-ARCH.zip\$" SHA256SUMS.txt | shasum -a 256 -c - &&
|
|
289
|
-
gh attestation verify "oats-desktop-V-mac-ARCH.zip" --repo awebai/oats &&
|
|
537
|
+
grep -qx VERIFIED "<W>.log" && cd "<W>" &&
|
|
290
538
|
ditto -x -k "oats-desktop-V-mac-ARCH.zip" . &&
|
|
291
539
|
codesign --verify --deep --strict "OATS Desktop.app" &&
|
|
292
540
|
defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleIdentifier &&
|
|
293
541
|
defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
294
542
|
```
|
|
295
543
|
|
|
296
|
-
- **Expected:** `ai.oats.desktop` and `V
|
|
297
|
-
|
|
298
|
-
- **Download with `gh`, never through a browser
|
|
299
|
-
|
|
300
|
-
would be quarantined.
|
|
544
|
+
- **Expected:** `ai.oats.desktop` and `V`, with `codesign --verify` passing
|
|
545
|
+
(the app is ad-hoc signed and not notarized).
|
|
546
|
+
- **Download with `gh`, never through a browser,** which would quarantine
|
|
547
|
+
it; `gh`'s copy starts from Finder.
|
|
301
548
|
- **Install it.** If the Desktop is running, tell the person and quit it;
|
|
302
549
|
its agents keep running:
|
|
303
550
|
`osascript -e 'quit app "OATS Desktop"'; for i in $(seq 20); do pgrep -xq "OATS Desktop" || break; sleep 1; done`.
|
|
304
|
-
Then
|
|
551
|
+
Then:
|
|
305
552
|
|
|
306
553
|
```bash
|
|
307
|
-
cd "<
|
|
554
|
+
grep -qx VERIFIED "<W>.log" && test -d "<W>/OATS Desktop.app" && cd "<W>" && rm -rf "/Applications/OATS Desktop.app" && ditto "OATS Desktop.app" "/Applications/OATS Desktop.app" && defaults read "/Applications/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
308
555
|
xattr -p com.apple.quarantine "/Applications/OATS Desktop.app" 2>/dev/null && echo QUARANTINED
|
|
309
556
|
```
|
|
310
557
|
|
|
@@ -312,18 +559,15 @@ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
|
312
559
|
if they agree (`xattr -dr com.apple.quarantine "/Applications/OATS
|
|
313
560
|
Desktop.app"`): never silently.
|
|
314
561
|
|
|
315
|
-
**Linux x64.** It needs glibc 2.34 or later (`ldd --version`)
|
|
316
|
-
|
|
562
|
+
**Linux x64.** It needs glibc 2.34 or later (`ldd --version`), installs per
|
|
563
|
+
user, without sudo, and shows in the app launcher. If the Desktop is
|
|
317
564
|
running, tell the person and quit it first; its agents keep running:
|
|
318
565
|
`pkill -o -u "$(id -u)" -x oats-desktop; for i in $(seq 20); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null || break; sleep 1; done; pgrep -u "$(id -u)" -x oats-desktop >/dev/null && echo STILL_RUNNING`
|
|
319
566
|
(the oldest process is the Desktop's main one). On `STILL_RUNNING`, ask the
|
|
320
567
|
person to quit it.
|
|
321
568
|
|
|
322
569
|
```bash
|
|
323
|
-
|
|
324
|
-
gh release download "vV" -R awebai/oats -p "oats-desktop-V-linux-x86_64.AppImage" -p SHA256SUMS.txt &&
|
|
325
|
-
grep " oats-desktop-V-linux-x86_64.AppImage\$" SHA256SUMS.txt | sha256sum -c - &&
|
|
326
|
-
gh attestation verify "oats-desktop-V-linux-x86_64.AppImage" --repo awebai/oats &&
|
|
570
|
+
grep -qx VERIFIED "<W>.log" && cd "<W>" &&
|
|
327
571
|
mkdir -p ~/.local/opt/oats-desktop ~/.local/share/applications &&
|
|
328
572
|
install -m 755 "oats-desktop-V-linux-x86_64.AppImage" ~/.local/opt/oats-desktop/OATS-Desktop.AppImage
|
|
329
573
|
```
|
|
@@ -340,55 +584,25 @@ Terminal=false
|
|
|
340
584
|
Categories=Development;
|
|
341
585
|
```
|
|
342
586
|
|
|
343
|
-
- **Without FUSE** (step
|
|
344
|
-
and later ship without
|
|
345
|
-
|
|
346
|
-
`
|
|
347
|
-
- **Linux arm64** (`uname -m` says `aarch64`) has no Desktop
|
|
348
|
-
download
|
|
587
|
+
- **Without FUSE 2** (step 2 printed `MISSING libfuse.so.2`; Ubuntu 22.04
|
|
588
|
+
and later ship without it), or when step 10's start fails with a FUSE
|
|
589
|
+
message, add ` --appimage-extract-and-run` after the AppImage's path in
|
|
590
|
+
`Exec=` and in step 10's start.
|
|
591
|
+
- **Linux arm64** (`uname -m` says `aarch64`) has no Desktop and no
|
|
592
|
+
download: say so and go on.
|
|
349
593
|
|
|
350
594
|
**Don't start the Desktop yet;** step 10 starts it on the new deployment.
|
|
351
595
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
```bash
|
|
355
|
-
npm install -g "@awebai/oats@V" && oats version
|
|
356
|
-
pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
|
|
357
|
-
```
|
|
596
|
+
## 5. Optional: the team on your own aweb account
|
|
358
597
|
|
|
359
|
-
**
|
|
360
|
-
|
|
598
|
+
**Only for a new workspace with aweb whose person chose, in step 1, the team
|
|
599
|
+
on their own aweb account now.** Otherwise skip it: step 9 creates the
|
|
600
|
+
workspace's account (the default), joins an existing workspace and signs up a machine
|
|
601
|
+
found-list.
|
|
361
602
|
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
It prints the two refs, for example `oats-framework/v1.19.0 v1.33.1`. If the
|
|
367
|
-
framework's version (the part after the `/`) is below `1.18.0`, this OATS
|
|
368
|
-
release is older than this skill: stop, and tell the person to wait for the
|
|
369
|
-
next OATS release. Never write a setup soul into the workspace in its place.
|
|
370
|
-
|
|
371
|
-
**With aweb, the messaging CLI `aw`, and the harness's aweb channel.**
|
|
372
|
-
Skip this without messaging. The channel is what wakes an agent when mail
|
|
373
|
-
arrives: Claude
|
|
374
|
-
`claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
|
|
375
|
-
pi `pi install npm:@awebai/pi`; Codex nothing (it is woken another way, which
|
|
376
|
-
the setup expert sets up).
|
|
377
|
-
|
|
378
|
-
```bash
|
|
379
|
-
npm install -g @awebai/aw && aw version
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
`aw` must be 1.36.33 or later.
|
|
383
|
-
|
|
384
|
-
## 5. Your messaging account and the workspace's team
|
|
385
|
-
|
|
386
|
-
**New workspace with aweb only.** An existing workspace joins in step 9, and
|
|
387
|
-
a machine found-list signs up there too: skip this step for both.
|
|
388
|
-
|
|
389
|
-
The workspace's agents share one team, its **default team**. Here the person
|
|
390
|
-
signs in to their own aweb account, and that account creates the team. Say
|
|
391
|
-
to them, in your words, exactly three things:
|
|
603
|
+
The workspace's agents share one team, its **default team**, which the
|
|
604
|
+
person's own aweb account creates here. Say to them, in your words, exactly
|
|
605
|
+
three things:
|
|
392
606
|
- you are creating a team for the workspace, owned by your aweb account;
|
|
393
607
|
- you sign in as yourself, in your own browser;
|
|
394
608
|
- every agent you spawn joins this default team. More teams are an explicit
|
|
@@ -398,10 +612,9 @@ Don't say that the agents are attributed or bound to them: the team is owned
|
|
|
398
612
|
by their account, and tying each agent to them is a later step the setup
|
|
399
613
|
expert offers.
|
|
400
614
|
|
|
401
|
-
**The workspace key `K`** is
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
that string, and a different spelling makes a different team.
|
|
615
|
+
**The workspace key `K`** is exactly `github.com/<owner>/<repo>`, the host's
|
|
616
|
+
owner and name from step 1 (`github.com/acme/acme-oats`): a different
|
|
617
|
+
spelling makes a different team.
|
|
405
618
|
|
|
406
619
|
**Sign in.** First check whether this machine's `aw` is signed in already:
|
|
407
620
|
|
|
@@ -409,9 +622,9 @@ that string, and a different spelling makes a different team.
|
|
|
409
622
|
aw auth status --json
|
|
410
623
|
```
|
|
411
624
|
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
625
|
+
With `"status": "authorized"` and an `account`, go on to the team. Otherwise
|
|
626
|
+
start the login yourself, detached, as with GitHub; aw prints a URL and a
|
|
627
|
+
one-time code, and waits:
|
|
415
628
|
|
|
416
629
|
```bash
|
|
417
630
|
nohup aw auth login </dev/null >"$HOME/.oats-aw-login.txt" 2>&1 &
|
|
@@ -423,10 +636,9 @@ A few seconds later, in a separate command:
|
|
|
423
636
|
cat "$HOME/.oats-aw-login.txt"
|
|
424
637
|
```
|
|
425
638
|
|
|
426
|
-
Open the URL in their browser and give them the code
|
|
427
|
-
create their aweb account there, and approve
|
|
428
|
-
|
|
429
|
-
they approved:
|
|
639
|
+
Open the URL in their browser and give them the code (not a secret). They
|
|
640
|
+
sign in, or create their aweb account there, and approve; the token stays in
|
|
641
|
+
aw's store. Once they say they approved:
|
|
430
642
|
|
|
431
643
|
```bash
|
|
432
644
|
aw auth status --json && rm -f "$HOME/.oats-aw-login.txt"
|
|
@@ -436,29 +648,26 @@ aw auth status --json && rm -f "$HOME/.oats-aw-login.txt"
|
|
|
436
648
|
the person.
|
|
437
649
|
|
|
438
650
|
**Create the team, with its root in `D/.aw`.** On a first run `D/.aw` must
|
|
439
|
-
not exist
|
|
651
|
+
not exist: if it does and this skill did not make it, stop and ask the
|
|
440
652
|
person what it is. With `D`, `K`, the workspace name and `ACCOUNT` written in:
|
|
441
653
|
|
|
442
654
|
```bash
|
|
443
655
|
mkdir -p "D" && test ! -e "D/.aw" && cd "D" && aw --identity-home "D/.aw" team ensure --workspace-key "K" --label "<workspace>" --expect-account "ACCOUNT" --json
|
|
444
656
|
```
|
|
445
657
|
|
|
446
|
-
- **Success** prints
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
- **It installs the team's root** in `D/.aw
|
|
450
|
-
|
|
451
|
-
leave it alone.
|
|
658
|
+
- **Success** prints JSON whose `canonical_team_id` is the team id `T`
|
|
659
|
+
(`<name>:<domain>`), which step 7 writes into the workspace. Never write
|
|
660
|
+
its `team_id` (an internal id), and never guess `T`.
|
|
661
|
+
- **It installs the team's root** in `D/.aw`, which adds each agent the
|
|
662
|
+
person spawns to the team, with no login. It holds keys: leave it alone.
|
|
452
663
|
- **A failure** prints one line on stderr and exits 2:
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
- `unsupported-server`, or anything else: stop and tell the person what it
|
|
458
|
-
printed.
|
|
664
|
+
`authorization-required` (the login is missing or expired): sign in again,
|
|
665
|
+
then rerun; `identity-home-occupied` (`D/.aw` holds something else),
|
|
666
|
+
`unsupported-server` or anything else: stop and tell the person what it
|
|
667
|
+
printed.
|
|
459
668
|
- **After an interrupted run** (killed, timed out, or its answer lost),
|
|
460
|
-
`D/.aw` exists
|
|
461
|
-
|
|
669
|
+
`D/.aw` exists and the first-run line stops at its check. Run the call
|
|
670
|
+
without that check, with exactly the same `D`, `K`, workspace name and
|
|
462
671
|
`ACCOUNT`: aw continues its own run, or answers `identity-home-occupied`
|
|
463
672
|
for anything else. Never remove or edit `D/.aw`.
|
|
464
673
|
|
|
@@ -470,17 +679,16 @@ Tell the person the team exists, owned by their aweb account `<handle>`.
|
|
|
470
679
|
|
|
471
680
|
## 6. The host repository
|
|
472
681
|
|
|
473
|
-
**New workspace,** by step 1's case
|
|
474
|
-
- **A dedicated host
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
files would end up in the first commit.
|
|
682
|
+
**New workspace,** by step 1's case; `<repo>` is the host's name.
|
|
683
|
+
- **A dedicated host, or the first repository:** create it inside `D`,
|
|
684
|
+
private unless every repository of theirs is public. `D/<repo>` must not
|
|
685
|
+
exist yet: its files would end up in the first commit.
|
|
478
686
|
|
|
479
687
|
```bash
|
|
480
688
|
mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
|
|
481
689
|
```
|
|
482
|
-
- **A monorepo:** clone it into `D`,
|
|
483
|
-
|
|
690
|
+
- **A monorepo:** clone it into `D`, where the setup expert's tools find it,
|
|
691
|
+
or use the clone of it already at `D/<repo>`.
|
|
484
692
|
|
|
485
693
|
```bash
|
|
486
694
|
mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo clone "<owner>/<repo>" "<repo>" && git -C "<repo>" status --short --branch
|
|
@@ -489,17 +697,17 @@ Tell the person the team exists, owned by their aweb account `<handle>`.
|
|
|
489
697
|
Its root must not hold `oats-workspace.yaml` or `oats-membership.yaml`
|
|
490
698
|
yet: if it does, stop and ask the person.
|
|
491
699
|
|
|
492
|
-
The workspace reference `W` is then `git:github.com/<owner>/<repo
|
|
493
|
-
`git:github.com/acme/acme-oats
|
|
700
|
+
The workspace reference `W` is then `git:github.com/<owner>/<repo>`
|
|
701
|
+
(`git:github.com/acme/acme-oats`).
|
|
494
702
|
|
|
495
703
|
**Existing workspace.** `W` is the reference they gave. Write nothing in its
|
|
496
704
|
repositories.
|
|
497
705
|
|
|
498
706
|
## 7. The skeleton
|
|
499
707
|
|
|
500
|
-
**New workspace.** Write two files at the root of `D/<repo>`, in one commit
|
|
501
|
-
|
|
502
|
-
|
|
708
|
+
**New workspace.** Write two files at the root of `D/<repo>`, in one commit,
|
|
709
|
+
with the person's own workspace name, host and team id in place of the
|
|
710
|
+
example's (`acme`, hosted in `acme/acme-oats`, with aweb).
|
|
503
711
|
|
|
504
712
|
`oats-workspace.yaml`:
|
|
505
713
|
|
|
@@ -509,31 +717,33 @@ name: acme
|
|
|
509
717
|
members:
|
|
510
718
|
- git:github.com/acme/acme-oats # the host; the setup expert adds the others
|
|
511
719
|
packages:
|
|
512
|
-
oats.framework: v1.
|
|
513
|
-
oats.aweb: v1.
|
|
720
|
+
oats.framework: v1.21.0 # the installed CLI's catalog versions (below)
|
|
721
|
+
oats.aweb: v1.35.0 # messaging: agent identities, mail and chat
|
|
514
722
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
515
723
|
defaults:
|
|
516
724
|
capabilities:
|
|
517
725
|
oats.core: { from: package }
|
|
518
726
|
messaging: { oats.aweb: { from: package } }
|
|
727
|
+
tasks: { oats.aweb-tasks: { from: package } } # or `tasks: none` (step 1)
|
|
519
728
|
teams:
|
|
520
729
|
acme: { description: The acme workspace's team, team: "T" }
|
|
521
730
|
defaultTeam: acme # every soul starts in this team
|
|
522
731
|
```
|
|
523
732
|
|
|
524
|
-
- **The versions** are the ones step 4 printed: the framework's (
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
- **
|
|
531
|
-
|
|
733
|
+
- **The versions** are the ones step 4 printed: the framework's (after
|
|
734
|
+
`oats-framework/`) and `oats.aweb`'s, that one never below `v1.33.1`.
|
|
735
|
+
- **The team** is `default:N.aweb.ai`, with `N` from step 1: the team step
|
|
736
|
+
9's signup creates, checked there against this line. With step 5's
|
|
737
|
+
sign-in, it is `T` from step 5 instead, written in literally. Its label
|
|
738
|
+
(here `acme`) is the workspace name.
|
|
739
|
+
- **The `oats.machine` line,** at the catalog's
|
|
740
|
+
`packages."oats.machine".ref`, only on a machine found-list.
|
|
741
|
+
- **The `tasks` line** is step 1's tasks answer: `oats.aweb-tasks` without
|
|
742
|
+
a tracker, `tasks: none` with one. On a machine found-list, leave it out.
|
|
532
743
|
- **Without messaging,** leave out the `oats.aweb` line, the `messaging`
|
|
533
|
-
line, `teams` and `defaultTeam`.
|
|
744
|
+
line, the `tasks` line, `teams` and `defaultTeam`.
|
|
534
745
|
- **Add nothing else:** no soul (the setup expert is `oats.framework`'s), no
|
|
535
|
-
|
|
536
|
-
own coordination, knowledge and tasks capabilities with the person.
|
|
746
|
+
knowledge; the setup expert authors those with the person.
|
|
537
747
|
|
|
538
748
|
`oats-membership.yaml`:
|
|
539
749
|
|
|
@@ -543,17 +753,19 @@ workspace: git:github.com/acme/acme-oats
|
|
|
543
753
|
```
|
|
544
754
|
|
|
545
755
|
**Commit and push.**
|
|
546
|
-
- **A repository created in step 6:**
|
|
547
|
-
|
|
548
|
-
- **A monorepo:**
|
|
549
|
-
|
|
550
|
-
|
|
756
|
+
- **A repository created in step 6:** straight to its default branch (it
|
|
757
|
+
is the person's own, just created).
|
|
758
|
+
- **A monorepo:** push the commit to its default branch on step 1's yes,
|
|
759
|
+
which named it, without asking again; show the person the files only if
|
|
760
|
+
they ask. When others can push to the repository (`gh api
|
|
761
|
+
repos/<owner>/<repo>/collaborators --jq length` prints more than 1, or
|
|
762
|
+
fails), its default branch is protected, or the push is refused: push a
|
|
763
|
+
branch instead, open a pull request, tell them, and stop until it is
|
|
551
764
|
merged.
|
|
552
|
-
- If `git config user.
|
|
553
|
-
|
|
554
|
-
`-c user.name="<their name>" -c user.email="<their noreply address>"
|
|
555
|
-
|
|
556
|
-
`gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'`.
|
|
765
|
+
- If `git config user.name` or `git config user.email` prints nothing in
|
|
766
|
+
`D/<repo>`, commit with the name step 1's yes covered:
|
|
767
|
+
`-c user.name="<their name>" -c user.email="<their noreply address>"`,
|
|
768
|
+
the address from `gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'`.
|
|
557
769
|
|
|
558
770
|
```bash
|
|
559
771
|
cd "D/<repo>" && git add oats-workspace.yaml oats-membership.yaml && git commit -m "OATS workspace acme: workspace and team" && git push -u origin HEAD
|
|
@@ -567,32 +779,34 @@ oats onboard D --workspace W --json
|
|
|
567
779
|
|
|
568
780
|
- **Effects:** it writes `D/oats-local.yaml` and `D/agents/`, reads every
|
|
569
781
|
member over Git and locks the packages.
|
|
570
|
-
- **The host must be `confirmed
|
|
571
|
-
access
|
|
572
|
-
|
|
782
|
+
- **The host must be `confirmed`;** a host that can't be read is a GitHub
|
|
783
|
+
access problem (step 3). Another member with `cannot-read` is an access
|
|
784
|
+
question for the setup expert, not a reason to stop.
|
|
573
785
|
- **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
|
|
574
786
|
person whether to use it as it is or to choose another directory.
|
|
575
787
|
|
|
576
788
|
**The setup expert, `S`, and its spawn line.** `result.next.spawn` is the
|
|
577
|
-
line to spawn it with. For a new workspace
|
|
578
|
-
`oats
|
|
579
|
-
|
|
580
|
-
|
|
789
|
+
line to spawn it with, and `S` is the soul it names. For a new workspace
|
|
790
|
+
that is `oats.framework`'s `oats-setup-expert` with
|
|
791
|
+
`--name <workspace>-oats-setup-expert`; for another name or no `--name`,
|
|
792
|
+
the text output of `oats onboard` says why.
|
|
793
|
+
- **An existing workspace's name** is its `--name` without the trailing
|
|
794
|
+
`-oats-setup-expert` or `-oats-setup` (`acme`); with no `--name` there,
|
|
795
|
+
keep step 1's.
|
|
581
796
|
- **On a machine found-list,** `S` is `oats.machine/steward`. An existing
|
|
582
797
|
workspace that doesn't offer it: stop, and say that its owner adds
|
|
583
798
|
`oats.machine` to its `packages:`.
|
|
584
|
-
- **An existing workspace with no setup soul** (`next.spawn` is `null`):
|
|
585
|
-
|
|
586
|
-
`oats-setup-expert
|
|
587
|
-
again.
|
|
588
|
-
|
|
589
|
-
**The clone.** A soul with `work: worktree`
|
|
590
|
-
at `D/<repo name
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
**Record the setup expert's harness** on this machine. A package soul names
|
|
799
|
+
- **An existing workspace with no setup soul** (`next.spawn` is `null`):
|
|
800
|
+
stop, and say that its owner pins `oats.framework` 1.19.0 or later, whose
|
|
801
|
+
`oats-setup-expert` attaches the person to the account. Once that is merged, run `oats sync --dir D` and
|
|
802
|
+
look again.
|
|
803
|
+
|
|
804
|
+
**The clone.** `oats-setup-expert` needs none. A soul with `work: worktree`
|
|
805
|
+
needs a clone of its repository at `D/<repo name>`: for an existing
|
|
806
|
+
workspace whose setup soul is its own, run the `git clone` line
|
|
807
|
+
`oats onboard` printed for it, if it says it is missing.
|
|
808
|
+
|
|
809
|
+
**Record the setup expert's harness** on this machine: a package soul names
|
|
596
810
|
none, and without this every later check (readiness, harness trust) and the
|
|
597
811
|
spawn would use the default, pi:
|
|
598
812
|
|
|
@@ -604,18 +818,17 @@ oats soul launch set S --harness <harness> --dir D
|
|
|
604
818
|
## 9. Messaging on this machine
|
|
605
819
|
|
|
606
820
|
Read `oats inspect --soul S --dir D --json`. Its `result.layers.messaging.id`
|
|
607
|
-
names the soul's messaging capability; `null`
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
names what is missing:
|
|
821
|
+
names the soul's messaging capability; with `null` (none), skip this step.
|
|
822
|
+
Otherwise the setup expert can't spawn here until that capability is set
|
|
823
|
+
up; its readiness names what is missing:
|
|
611
824
|
|
|
612
825
|
```bash
|
|
613
826
|
oats readiness --soul S --dir D --json
|
|
614
827
|
```
|
|
615
828
|
|
|
616
829
|
The messaging items must not report a problem. aweb, the default, is set up
|
|
617
|
-
|
|
618
|
-
|
|
830
|
+
below; for another capability, follow its own setup skill, and stop if its
|
|
831
|
+
readiness still reports a problem.
|
|
619
832
|
|
|
620
833
|
**With aweb (`oats.aweb`):**
|
|
621
834
|
1. **Check:**
|
|
@@ -624,69 +837,100 @@ stop if its readiness still reports a problem.
|
|
|
624
837
|
cd "D" && oats aweb setup --soul S --check-only --json
|
|
625
838
|
```
|
|
626
839
|
|
|
627
|
-
Its `aw.status` must be `ok
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
- **A new workspace** expects `"member": true`
|
|
631
|
-
root. Then this step is done.
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
840
|
+
Its `aw.status` must be `ok` (`aw` missing: install it and the harness's
|
|
841
|
+
channel as in step 4, then check again; anything else: stop and tell the
|
|
842
|
+
person why). Its `defaultTeam.label` is `L`, the setup expert's team.
|
|
843
|
+
- **A new workspace that signed in at step 5** expects `"member": true`
|
|
844
|
+
here: step 5 installed the root. Then this step is done.
|
|
845
|
+
Every other new workspace (the default, and a machine found-list)
|
|
846
|
+
has no root yet, so its `"member": false` here is expected: go on to
|
|
847
|
+
item 2.
|
|
848
|
+
- **`"member": false` after step 5's sign-in:** stop, spawn nothing, and
|
|
849
|
+
tell the person which fix applies. With
|
|
635
850
|
`"root": null`, there is no root in `D/.aw`: step 5's team creation did
|
|
636
851
|
not finish there, so run its line for an interrupted run, then check
|
|
637
852
|
again. With a `root`, that root is not a member of `defaultTeam.team`:
|
|
638
853
|
the team id step 7 wrote must be step 5's `canonical_team_id` exactly,
|
|
639
854
|
so correct it in `oats-workspace.yaml`, commit and push it, run
|
|
640
855
|
`oats sync --dir D`, then check again.
|
|
641
|
-
2. **
|
|
642
|
-
|
|
643
|
-
|
|
856
|
+
2. **A new workspace without step 5's sign-in, and a machine found-list:
|
|
857
|
+
sign up the workspace's aweb account and team,** with `N` and `A` from
|
|
858
|
+
step 1: no API key or token, nothing for the person to type. Preview
|
|
859
|
+
first, then run it:
|
|
644
860
|
|
|
645
861
|
```bash
|
|
646
862
|
cd "D" && oats aweb setup --soul S --username N --name A --label L --plan --json
|
|
647
863
|
cd "D" && oats aweb setup --soul S --username N --name A --label L --json
|
|
648
864
|
```
|
|
649
865
|
|
|
650
|
-
The
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
866
|
+
- **The answer:** `result.team` must be
|
|
867
|
+
the team line step 7 wrote, `default:N.aweb.ai`, and
|
|
868
|
+
`result.membershipVerified` must be `true`. Otherwise stop, spawn
|
|
869
|
+
nothing, and tell the person what it shows.
|
|
870
|
+
- **Then tell the person,** in your words: this is the workspace's
|
|
871
|
+
team, on an aweb account created for it; they attach themselves to it
|
|
872
|
+
later in the setup, with the setup expert.
|
|
873
|
+
- **`E_SETUP_NATIVE`:** most likely `N` is taken (the preview does not
|
|
874
|
+
contact aweb, and aw's output is withheld); the run may also have left
|
|
875
|
+
a root part-way. Never remove `D/.aw`, and never rerun blindly.
|
|
876
|
+
On a machine found-list, ask nothing: tell the person that the run
|
|
877
|
+
failed, most likely because `N` is taken, and stop.
|
|
878
|
+
Otherwise look first, read-only: `test -e "D/.aw" && echo RETAINED`.
|
|
879
|
+
- **Nothing printed:** aw kept nothing, so `N` is free to change. Ask
|
|
880
|
+
the person for another `N`, change the team line in
|
|
881
|
+
`D/<repo>/oats-workspace.yaml` to `default:<new N>.aweb.ai`, commit
|
|
882
|
+
and push it, run `oats sync --dir D`, then run the preview and the
|
|
883
|
+
signup again with the new `N`.
|
|
884
|
+
- **`RETAINED`:** the run left a root. Keep `N` and the team line, and
|
|
885
|
+
run the preview again, unchanged. When its `result.team` is
|
|
886
|
+
`default:N.aweb.ai`, the account exists: run the signup again,
|
|
887
|
+
unchanged, and it reuses that root. Anything else, the preview
|
|
888
|
+
failing included: stop, spawn nothing, and tell the person what it
|
|
889
|
+
shows.
|
|
890
|
+
3. **Existing workspace: the person gets an invite** from a member of `L`,
|
|
891
|
+
whose own agent runs
|
|
892
|
+
`oats aweb invite --soul <their soul> --label L --json` in their
|
|
893
|
+
deployment. The answer's `result.token` is the invite token,
|
|
894
|
+
passed to the person privately, never by ordinary mail. From oats.aweb
|
|
895
|
+
1.33.1 the answer's `result.awebUrl` is the service URL `U`, no secret,
|
|
896
|
+
which the member passes too. When it is `null` or absent, leave
|
|
897
|
+
`--service U` out of item 4: the join then takes the service from the
|
|
898
|
+
invite, or fails and item 5 stops. This machine's messaging root is
|
|
899
|
+
`A` = `<workspace>-<this machine's name>` (step 1), with the workspace's
|
|
900
|
+
name from step 8: don't ask. Only a hosted team works: if the invite is
|
|
901
|
+
refused, or the join says the team is not hosted, stop; the workspace's
|
|
902
|
+
owner decides.
|
|
663
903
|
4. **Existing workspace: the person joins in their own terminal,** which you
|
|
664
|
-
open for them ("How to work"), typing the token at the hidden prompt
|
|
665
|
-
|
|
904
|
+
open for them ("How to work"), typing the token at the hidden prompt,
|
|
905
|
+
with `D`, `S`, `L`, `A` and `U` filled in:
|
|
666
906
|
|
|
667
907
|
```text
|
|
668
908
|
cd "D" && sh -c 'stty -echo; printf "Invite token: "; read -r T; stty echo; echo; printf "%s\n" "$T" | oats aweb setup --soul S --join L --invite-stdin --name A --service U'
|
|
669
909
|
```
|
|
910
|
+
|
|
670
911
|
5. **After items 2 to 4, check again** (item 1), and expect `"member": true`.
|
|
671
912
|
On `"member": false`, stop and spawn nothing: tell the person the run
|
|
672
913
|
left this machine's root outside `L`, with what the check shows, and
|
|
673
|
-
don't rerun the signup or the join.
|
|
674
|
-
|
|
914
|
+
don't rerun the signup or the join (you can't see the join's output).
|
|
915
|
+
When another machine of the same name may already be in the team, say
|
|
916
|
+
that a taken name is a likely cause: the person who invited them can ask
|
|
917
|
+
their own agent whether that name is in the group (its agent reads
|
|
918
|
+
`oats aweb roster --label L`); the fix (a new invite and a name for this
|
|
919
|
+
machine) is the workspace owner's. Never take the other machine's name.
|
|
675
920
|
The setup expert does the rest of this machine's messaging
|
|
676
921
|
(`/oats-host-delivery`).
|
|
677
922
|
|
|
678
|
-
**The steward's global address (machine found-list only).** The
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
Without messaging there is no address to make: skip this. Otherwise it
|
|
685
|
-
needs every one of these, and when one fails, take the fallback below:
|
|
923
|
+
**The steward's global address (machine found-list only).** The team root
|
|
924
|
+
you just signed up makes the steward a global, contacts-only aweb address,
|
|
925
|
+
`<namespace>/R` (`R` from step 1, for the resident and the instance alike),
|
|
926
|
+
with no API key and nothing for the person to type. Without messaging, skip
|
|
927
|
+
this. It needs all of these; when one fails, take the fallback below:
|
|
686
928
|
- a new workspace: a root that joined by invite (items 3 and 4) does not own
|
|
687
929
|
the namespace, so aweb would refuse the create;
|
|
688
|
-
- `oats.aweb`
|
|
689
|
-
|
|
930
|
+
- an `oats.aweb` release that carries the root route
|
|
931
|
+
([awebai/oats-aweb#147](https://github.com/awebai/oats-aweb/pull/147)).
|
|
932
|
+
None is released yet: until one is, take the fallback below, whatever
|
|
933
|
+
`oats.aweb` version the `oats inspect` you read above reports;
|
|
690
934
|
- aw 1.36.48 or later: `aw.version` in the check (item 1).
|
|
691
935
|
|
|
692
936
|
Plan, then create, both from `D` and with no `AWEB_API_KEY`:
|
|
@@ -702,17 +946,17 @@ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --json
|
|
|
702
946
|
never makes a second one). Anything else, a refusal included (no team
|
|
703
947
|
root, say), is the fallback.
|
|
704
948
|
- **`--team-label L`** puts the resident in the team that is already the
|
|
705
|
-
default, so the run
|
|
706
|
-
|
|
949
|
+
default, so the run prints the spawn line as its one step
|
|
950
|
+
(`result.steps`). If it prints another step first, stop and tell the
|
|
707
951
|
person what it says: that step is theirs.
|
|
708
|
-
- **Success** prints `PASS resident <address>
|
|
709
|
-
|
|
710
|
-
- **A failure
|
|
711
|
-
|
|
712
|
-
|
|
952
|
+
- **Success** prints `PASS resident <address> …`; `result.address` is the
|
|
953
|
+
steward's address. Spawn with the grant-seat options below.
|
|
954
|
+
- **A failure:** report it to the person as it is, and spawn nothing. If
|
|
955
|
+
the create was interrupted (killed, or timed out with no answer), run the
|
|
956
|
+
same line again, unchanged, and nothing else. Never empty
|
|
713
957
|
`D/.aweb-residents/R`: the identity may already exist.
|
|
714
|
-
- **The fallback:** spawn the steward without the grant-seat options
|
|
715
|
-
a local team identity, as every instance
|
|
958
|
+
- **The fallback:** spawn the steward without the grant-seat options, with
|
|
959
|
+
a local team identity, as every instance has. Tell the person in one line,
|
|
716
960
|
without asking anything: the steward has a local team identity and no
|
|
717
961
|
global address because of <the reason>, and the GLOBAL residents and grant
|
|
718
962
|
seats section of `/oats-aweb` moves it to one later. Never ask for a key.
|
|
@@ -737,42 +981,69 @@ are cloned, knowledge tools, messaging wanted or not>
|
|
|
737
981
|
## Done by the getting-started skill
|
|
738
982
|
- Installed: OATS <V> (oats version), OATS Desktop <V> | not installed (why)
|
|
739
983
|
- GitHub: gh logged in over https as <login>; no SSH key or signing set up
|
|
740
|
-
- New workspace only: host <owner>/<repo>, skeleton committed (pushed |
|
|
741
|
-
|
|
984
|
+
- New workspace only: host <owner>/<repo>, skeleton committed (pushed |
|
|
985
|
+
merged from <url>)
|
|
742
986
|
- Messaging: <capability>, aw <version>, <harness> channel installed;
|
|
743
|
-
team T
|
|
744
|
-
|
|
745
|
-
|
|
987
|
+
team T on aweb account N, created for the workspace, not yet attached to
|
|
988
|
+
the person (new workspace), or T owned by aweb account <handle>
|
|
989
|
+
(signed in at step 5), or new account N signed up (machine found-list),
|
|
990
|
+
or joined L by invite (existing) | not set up (the setup expert has no
|
|
991
|
+
messaging)
|
|
746
992
|
- Harness channel mode: development, confirmed by OATS at each start
|
|
993
|
+
(Claude with aweb) | none (Codex, pi or no messaging)
|
|
994
|
+
- Tasks (new workspace with aweb): oats.aweb-tasks | none: the agents use
|
|
995
|
+
<GitHub issues in <repo> | <tracker the person named> | ticket keys
|
|
996
|
+
<PREFIX>-n>, for you to connect with the person; aweb's task list stays
|
|
997
|
+
empty
|
|
998
|
+
- For the person, later: <what they may want to know but the hand-off
|
|
999
|
+
message leaves out, such as a version, a skipped step and why>
|
|
747
1000
|
|
|
748
1001
|
## Left to you
|
|
749
1002
|
Everything else, starting with /oats-setup-expert.
|
|
750
1003
|
```
|
|
751
1004
|
|
|
752
1005
|
**Claude and Codex only: trust the deployment directory first,** so the first
|
|
753
|
-
start doesn't stop at the
|
|
754
|
-
nothing. Use `codex` for Codex:
|
|
1006
|
+
start doesn't stop at the folder-trust question (`codex` for Codex):
|
|
755
1007
|
|
|
756
1008
|
```bash
|
|
757
1009
|
oats harness trust --dir D --harness claude --plan
|
|
758
1010
|
oats harness trust --dir D --harness claude
|
|
759
1011
|
```
|
|
760
1012
|
|
|
761
|
-
- **If
|
|
762
|
-
the writer refuses), don't edit the file
|
|
763
|
-
own terminal ("How to work")
|
|
764
|
-
|
|
1013
|
+
- **If the trust command itself refuses a file** (on macOS,
|
|
1014
|
+
`~/.claude.json` can carry a mark the writer refuses), don't edit the file
|
|
1015
|
+
or its attributes. Open their own terminal ("How to work") running
|
|
1016
|
+
`cd "D" && claude` (or `codex`), and tell them to answer yes when it asks
|
|
1017
|
+
whether to trust the folder where their agents live, then close the
|
|
1018
|
+
window. A refusal by your harness's permission check is "How to work"'s
|
|
1019
|
+
case instead.
|
|
765
1020
|
- **Then check** that the `harness-trust` item of
|
|
766
1021
|
`oats readiness --soul S --dir D --json` passes.
|
|
767
1022
|
|
|
768
|
-
**The channel mode.** With Claude and aweb, the
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
1023
|
+
**The channel mode.** With Claude and aweb, leave the default development
|
|
1024
|
+
channel mode (Claude asks at each start whether to load the aweb channel,
|
|
1025
|
+
and OATS confirms it), and don't set `delivery: session`; the setup expert
|
|
1026
|
+
later offers the approved route, which needs `sudo`. Tell the person once,
|
|
1027
|
+
before the spawn: a notice about a "development channel" may flash past when
|
|
1028
|
+
the setup expert starts; OATS answers it, and the setup expert can remove it
|
|
1029
|
+
later.
|
|
1030
|
+
|
|
1031
|
+
**An existing workspace names the setup expert after this machine,** since
|
|
1032
|
+
every member's machine has its own in the same team, and two of one name
|
|
1033
|
+
can't share it: put
|
|
1034
|
+
`-<this machine's name>` (step 1) before `-oats-setup-expert` in
|
|
1035
|
+
`next.spawn`'s `--name`, giving
|
|
1036
|
+
`--name <workspace>-<this machine's name>-oats-setup-expert`. Over 64
|
|
1037
|
+
characters, cut characters from the end of this machine's name until it fits
|
|
1038
|
+
(then any `-` left last), so a rerun derives the same name and finds its own setup expert
|
|
1039
|
+
(`E_INSTANCE_NAME_TAKEN`, below). A renamed machine gets a new setup expert;
|
|
1040
|
+
its agent retires the old one. When `next.spawn` has no `--name` (a very
|
|
1041
|
+
long workspace name), before spawning, look in `oats status --dir D --json` for a setup
|
|
1042
|
+
expert of `S` already here, and open that one instead of spawning a second.
|
|
1043
|
+
A new workspace keeps `next.spawn` as it is.
|
|
773
1044
|
|
|
774
1045
|
**Preview the spawn, read it, then spawn,** with step 8's `next.spawn` line
|
|
775
|
-
|
|
1046
|
+
and the hand-over:
|
|
776
1047
|
|
|
777
1048
|
```bash
|
|
778
1049
|
<next.spawn> --task-file D/.oats-handover.md --preview
|
|
@@ -793,31 +1064,33 @@ In the fallback, or without messaging, leave out both `--provider` options.
|
|
|
793
1064
|
- **The preview** shows what the spawn would create. If it reports a
|
|
794
1065
|
problem, stop and tell the person what it says.
|
|
795
1066
|
- **The spawn** prints the instance's home `H` and its name. Then delete the
|
|
796
|
-
hand-over file
|
|
1067
|
+
hand-over file (the home has it as `TASK.md`).
|
|
1068
|
+
- **A messaging name already held by another machine's agent** (the spawn
|
|
1069
|
+
names the conflict): spawn nothing more and rename nothing; tell the
|
|
1070
|
+
person another machine in the team uses this name, and the workspace
|
|
1071
|
+
owner decides the fix.
|
|
797
1072
|
- **`E_SPAWN_INCOMPLETE`:** don't spawn again. Run `oats session inspect
|
|
798
1073
|
--home H --json` and tell the person what it shows.
|
|
799
1074
|
- **`E_INSTANCE_NAME_TAKEN`** (the preview or the spawn): the setup expert
|
|
800
|
-
already exists
|
|
801
|
-
is
|
|
802
|
-
|
|
1075
|
+
already exists; don't spawn another. Its home `H` is in the error; if it
|
|
1076
|
+
is stopped, start it with `oats session start --home H`. Either way, open
|
|
1077
|
+
it in the Desktop below.
|
|
803
1078
|
|
|
804
1079
|
**The Desktop**, if installed, opens on the new deployment with the setup
|
|
805
|
-
expert selected. `I` is its instance name: the
|
|
806
|
-
`
|
|
807
|
-
|
|
808
|
-
|
|
1080
|
+
expert selected. `I` is its instance name: the `--name` you spawned with
|
|
1081
|
+
(after `E_INSTANCE_NAME_TAKEN`, that same `--name`), else the one the spawn
|
|
1082
|
+
printed. Always pass `--instance`: a Desktop that does not know it ignores
|
|
1083
|
+
it.
|
|
809
1084
|
- **macOS:**
|
|
810
1085
|
|
|
811
1086
|
```bash
|
|
812
1087
|
open -n -a "OATS Desktop" --args --dir "D" --instance "I"
|
|
813
1088
|
```
|
|
814
1089
|
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
harness's variables and sandbox, and the Desktop passes its environment to
|
|
820
|
-
every agent it starts):
|
|
1090
|
+
A Desktop already running takes `--dir` and `--instance` from it.
|
|
1091
|
+
- **Linux:** start it through their session manager, so it gets their
|
|
1092
|
+
desktop session's environment, not yours (with your harness's variables
|
|
1093
|
+
and sandbox, which it would pass to every agent):
|
|
821
1094
|
|
|
822
1095
|
```bash
|
|
823
1096
|
U="oats-desktop-$(date +%s)"; LOG="$(mktemp)"; systemd-run --user --collect --quiet --unit "$U" -p KillMode=process -p StandardOutput="file:$LOG" -p StandardError="file:$LOG" -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY "$HOME/.local/opt/oats-desktop/OATS-Desktop.AppImage" --dir "D" --instance "I" && for i in $(seq 30); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null && break; sleep 1; done; sleep 3; if pgrep -u "$(id -u)" -x oats-desktop >/dev/null; then echo STARTED; else echo FAILED; tail -n 20 "$LOG"; fi
|
|
@@ -825,36 +1098,62 @@ deployment, so pass it always.
|
|
|
825
1098
|
|
|
826
1099
|
- **`STARTED`:** it shows `D`, with `I` selected.
|
|
827
1100
|
- **A FUSE message:** see step 4, then start it again.
|
|
828
|
-
- **Anything else,** or no `systemd-run`: tell the person what it printed
|
|
829
|
-
|
|
1101
|
+
- **Anything else,** or no `systemd-run`: tell the person what it printed;
|
|
1102
|
+
they open **OATS Desktop** from their app launcher, which lists `D` in
|
|
830
1103
|
its switcher.
|
|
831
|
-
- **Never start it with an emptied environment** (`env -i`): it then loses
|
|
832
|
-
HOME, and Git loses the person's login.
|
|
833
|
-
|
|
834
|
-
**The TUI**, if they wanted it, runs in a terminal of its own: open it in
|
|
835
|
-
their own terminal, as "How to work" says, with the command
|
|
836
|
-
`oats tui --dir "D"`.
|
|
837
|
-
|
|
838
|
-
**Tell the person where the setup expert is** (its instance name; on a
|
|
839
|
-
machine found-list, the steward, and its address), and that it continues
|
|
840
|
-
from here: in the Desktop or the TUI you started. Without either, they reach
|
|
841
|
-
it with `oats session attach --home H` in a terminal.
|
|
842
1104
|
|
|
843
|
-
|
|
844
|
-
|
|
1105
|
+
**The TUI:** open their own terminal ("How to work") running
|
|
1106
|
+
`oats tui --dir "D"` when they asked for it in step 1, or have no Desktop
|
|
1107
|
+
and say yes to it in the hand-over below.
|
|
1108
|
+
|
|
1109
|
+
**Hand over to the setup expert,** in a short message in plain words:
|
|
1110
|
+
- what is ready: their agents' shared setup, kept on GitHub, the group their
|
|
1111
|
+
agents talk in, and the setup assistant running; on a machine found-list,
|
|
1112
|
+
the steward, and its address when it has one;
|
|
1113
|
+
- **where to go now:** "Switch to the OATS Desktop window. Click
|
|
1114
|
+
**<I's display form>** under Instances on the left, if it isn't
|
|
1115
|
+
selected: it has already started and will ask you its first question
|
|
1116
|
+
there. You can close this chat." `I`'s display form is how the Desktop
|
|
1117
|
+
lists it: `-` turned into spaces, the first letter capitalised
|
|
1118
|
+
(`acme-oats-setup-expert` shows as "Acme oats setup expert"). Without the
|
|
1119
|
+
Desktop, offer to open a terminal window where they can talk to it (the
|
|
1120
|
+
TUI, above), and say the same about it there. When neither opens, tell
|
|
1121
|
+
them the setup assistant is running, and the OATS Desktop, once
|
|
1122
|
+
installed, shows it;
|
|
1123
|
+
- what the setup assistant does next, in one line: it learns how they work,
|
|
1124
|
+
then sets up their projects and their first agents with them, and it
|
|
1125
|
+
opens a small hidden prompt when they need to type a password or a key;
|
|
1126
|
+
- a new workspace with aweb only, where their agents track work, in one
|
|
1127
|
+
line, with how to change it: "Your agents share aweb's task list; to use
|
|
1128
|
+
another tracker later, ask the setup assistant to switch." With a
|
|
1129
|
+
tracker: "Your agents use your <GitHub issues | tracker>; the setup
|
|
1130
|
+
assistant connects them. Leave aweb's task list empty: one task there
|
|
1131
|
+
opts your whole group in to it. To use aweb's task list instead, ask the
|
|
1132
|
+
setup assistant."
|
|
1133
|
+
|
|
1134
|
+
Keep this message in plain words. Don't list homes, paths or commands, and
|
|
1135
|
+
name no versions (Git's, OATS's or any other), no package sources (a PPA,
|
|
1136
|
+
say) and no internal flags or codes (a "development-channel flag", a
|
|
1137
|
+
"channel-not-connected", say). When you name the setup expert as the
|
|
1138
|
+
Desktop lists it, use its display form, never its instance name. Anything they may want to know later goes in the hand-over file, for
|
|
1139
|
+
the setup expert, not in this message. You are done.
|
|
845
1140
|
|
|
846
1141
|
## Never
|
|
847
1142
|
|
|
848
|
-
- **Ask for, read, print or store a secret,** or suggest
|
|
849
|
-
|
|
850
|
-
them to rotate it.
|
|
851
|
-
- **Overwrite or re-onboard** a deployment,
|
|
852
|
-
|
|
853
|
-
|
|
1143
|
+
- **Ask for, read, print or store a secret,** or suggest Claude Code's
|
|
1144
|
+
`! <command>` for one: its command and output enter your context. If the
|
|
1145
|
+
person pastes one anyway, don't repeat it, and tell them to rotate it.
|
|
1146
|
+
- **Overwrite or re-onboard** a deployment, edit an existing deployment's
|
|
1147
|
+
files (`oats-local.yaml`, `oats-lock.json`, `agents/`), touch `D/.aw`, or
|
|
1148
|
+
push to a repository other than the new workspace's host they agreed to in
|
|
1149
|
+
step 1 (step 6 creates or clones it).
|
|
1150
|
+
- **Guess the team id:** it is the signup's `default:N.aweb.ai`, checked in
|
|
1151
|
+
step 9, or step 5's answer after its sign-in.
|
|
854
1152
|
- **Write a setup soul into the workspace:** the setup expert is
|
|
855
1153
|
`oats.framework`'s.
|
|
856
1154
|
- **The Desktop:** never download it through a browser, skip a verification
|
|
857
|
-
step, strip quarantine without asking, or start it with
|
|
1155
|
+
step, strip quarantine without asking, or start it with an emptied
|
|
1156
|
+
environment (`env -i`: it loses HOME, and Git the person's login).
|
|
858
1157
|
- **Put an absolute path or a credential** in `oats-workspace.yaml`,
|
|
859
1158
|
`oats-membership.yaml` or a soul (the team id is not a secret).
|
|
860
1159
|
- **Spawn** before `oats onboard` confirmed the host.
|