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