@awebai/oats 0.49.0 → 0.50.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +104 -18
- package/docs/capabilities.md +169 -0
- package/docs/capability-manifest.schema.json +42 -0
- package/docs/configuration.md +97 -0
- package/docs/desktop-cli-api.md +176 -18
- package/docs/desktop.md +13 -0
- package/docs/execution-targets.md +33 -7
- package/docs/implementation.md +18 -6
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +21 -7
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/schedules.md +228 -15
- package/docs/souls-and-instances.md +69 -7
- package/docs/workspaces.md +1 -1
- package/lib/capability-show.mjs +14 -1
- package/lib/core.mjs +272 -80
- package/lib/instance-events.mjs +3 -7
- package/lib/instance-git.mjs +8 -5
- package/lib/instance-inspect.mjs +44 -15
- package/lib/refused-text.mjs +17 -0
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/schedule.mjs +8 -2
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +521 -60
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
|
@@ -901,8 +901,8 @@ or the recorded window is gone and no pane on that server works in the home;
|
|
|
901
901
|
and, always, no live process on this host works in the home (a harness
|
|
902
902
|
started by hand elsewhere counts). Retire then runs its hooks and preserves
|
|
903
903
|
its work as usual. If the recorded window is still there, a pane or a process
|
|
904
|
-
works in the home (the refusal names its pid), or the
|
|
905
|
-
cannot run, retire refuses with
|
|
904
|
+
works in the home (the refusal names its pid), or the
|
|
905
|
+
[process scan](#the-process-scan) cannot run, retire refuses with
|
|
906
906
|
`E_RUNTIME_ENDPOINT_UNKNOWN`, even with `--force`: stop that session yourself,
|
|
907
907
|
then retire again. `oats retire <instance> --plan` says which case applies.
|
|
908
908
|
|
|
@@ -912,11 +912,28 @@ home. When the recorded server cannot be reached because its socket file is
|
|
|
912
912
|
missing (after a reboot), retire proceeds only when no process on this host
|
|
913
913
|
works in the home (any process whose working directory is in the home, not
|
|
914
914
|
only the harness); a tmux server that lost its socket file still runs, and
|
|
915
|
-
recreates the socket when its process is sent `SIGUSR1`.
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
915
|
+
recreates the socket when its process is sent `SIGUSR1`. A
|
|
916
|
+
[process scan](#the-process-scan) that cannot run or does not complete (a
|
|
917
|
+
timeout, for example) refuses the same way, also for a home without its
|
|
918
|
+
receipt. Status, start and stop apply the same rule to a missing socket file
|
|
919
|
+
([Sessions](execution-targets.md#missing-socket)).
|
|
920
|
+
|
|
921
|
+
<a id="the-process-scan"></a>
|
|
922
|
+
**The process scan.** "No process works in the home" comes from one scan of
|
|
923
|
+
the host's processes and their working directories. On Linux it reads
|
|
924
|
+
`/proc` (each process's `cwd` link, `comm` and `stat`); elsewhere (macOS) it
|
|
925
|
+
runs `lsof`. A Linux host whose `/proc/self/cwd` cannot be read uses `lsof`
|
|
926
|
+
too. On a host with neither, `oats doctor` says so in a
|
|
927
|
+
`process-scan-unavailable` information line, and retire refuses where it must
|
|
928
|
+
rule out a live process (a home without its session receipt, a missing
|
|
929
|
+
recorded tmux socket, a Herdr home), as do session start and stop when a
|
|
930
|
+
recorded tmux socket is missing: install `lsof`. The scan sees only the
|
|
931
|
+
processes this user may inspect: a process of another user, or a
|
|
932
|
+
non-dumpable one of the same user (such as `ssh-agent`), is not seen by
|
|
933
|
+
either mechanism, so one of those working in the home does not stop a
|
|
934
|
+
retire. Refusing whenever such a process exists would refuse on every host
|
|
935
|
+
(root daemons, `ssh-agent`). The harness OATS launches runs as the user and
|
|
936
|
+
can be inspected, and it is the process the scan exists to find.
|
|
920
937
|
|
|
921
938
|
`oats retire <instance> --self` lets an instance retire itself when the human
|
|
922
939
|
or briefing says it is done. A live harness cannot give a stable final
|
|
@@ -1044,6 +1061,15 @@ leaves `work/` untouched. For each tree:
|
|
|
1044
1061
|
the branch name with characters outside `A-Za-z0-9._-` replaced by `-`, or
|
|
1045
1062
|
`detached-<12 hex>` when HEAD is detached. A target that exists gets `-2`,
|
|
1046
1063
|
`-3`, and so on. A tree whose HEAD cannot be read is re-homed too.
|
|
1064
|
+
`work/` is re-homed under the same rule.
|
|
1065
|
+
|
|
1066
|
+
The leaf is one path component, so it is bounded: at most 231 bytes before
|
|
1067
|
+
its `-N` (NAME_MAX, 255, less a 16-byte margin and 8 bytes kept for `-N`;
|
|
1068
|
+
the leaf is ASCII, so bytes are characters). A leaf that fits is the
|
|
1069
|
+
flattened branch as it is. A longer one, from a long branch, is cut to 224
|
|
1070
|
+
bytes, its trailing `-` trimmed, and followed by `-` and the first 6 hex of
|
|
1071
|
+
the SHA-256 of the full branch name, so two branches that share a long
|
|
1072
|
+
prefix get different leaves. The plan's `movedTo` is the same name.
|
|
1047
1073
|
- **A tree the retire cannot handle refuses it.** A locked tree (`git worktree
|
|
1048
1074
|
lock`) refuses before anything runs: a retire that would remove the home
|
|
1049
1075
|
finds the lock in its first inspection, before the session is stopped and
|
|
@@ -1082,6 +1108,42 @@ recovery are in no commit: a retained worktree or the source may still hold
|
|
|
1082
1108
|
them, or the recovery may be the only copy, so inspect them before you
|
|
1083
1109
|
remove it.
|
|
1084
1110
|
|
|
1111
|
+
`oats doctor` lists them all. It prints one `retained-recovery:` line per
|
|
1112
|
+
recovery copy in each instances directory of the deployment, and one
|
|
1113
|
+
`retained-worktree:` line per retained worktree. Each kind starts with a line
|
|
1114
|
+
that gives its total. At most 50 items follow, then `… and N more`. The lines
|
|
1115
|
+
are also in `oats doctor --json`, in `information[]`. They are read-only: doctor
|
|
1116
|
+
runs Git without helpers or optional locks, refreshes no index and follows no
|
|
1117
|
+
link. A fact doctor can't read is said on its line.
|
|
1118
|
+
|
|
1119
|
+
- A recovery line gives the path, the instance, `phase` and `classes` from
|
|
1120
|
+
`recovery.json`, the size, and whether `after-hooks/` is there. A recovery
|
|
1121
|
+
whose `recovery.json` is missing or unreadable is listed and says so, with
|
|
1122
|
+
the instance taken from the directory's name. A dot-named entry is the
|
|
1123
|
+
staging of a copy that a retire could not remove (`unfinished copy`).
|
|
1124
|
+
- A retained worktree line gives the path, the repository, the branch (or
|
|
1125
|
+
`detached at <commit>`), and `clean` or `not clean; uncommitted: <classes>`
|
|
1126
|
+
(staged or unstaged changes, conflicts, untracked or ignored files, an
|
|
1127
|
+
operation in progress). Doctor doesn't ask Git for the status of a
|
|
1128
|
+
repository whose configuration names a content filter (`filter.<driver>.clean`
|
|
1129
|
+
or `.process`), because the status would run it: the line says `clean:
|
|
1130
|
+
unknown` and names the filter. The status never enters a submodule: it
|
|
1131
|
+
compares only the commit each one is at. A tree with a submodule is then
|
|
1132
|
+
`clean: unknown (submodule work trees not read)`, or `not clean` when the
|
|
1133
|
+
rest of it is, with `submodule work trees not read` after it. An entry that isn't a registered worktree is listed and
|
|
1134
|
+
says why.
|
|
1135
|
+
- Both end with the reachability fact for the HEAD commit. It is checked in the
|
|
1136
|
+
source repository against every ref but the tree's own branch:
|
|
1137
|
+
`commits: all reachable from <ref>`, `commits: <n> not reachable from any
|
|
1138
|
+
other ref`, `commits: HEAD <commit> is not in the source repository`, or
|
|
1139
|
+
`commits: unknown (<why>)`. For a recovery, the HEAD is that of its `repo/`
|
|
1140
|
+
clone, and the source repository is the one its copied home's
|
|
1141
|
+
`instance.json` records. That path is only a hint: it is used only when it
|
|
1142
|
+
is a Git repository's top level. A recovery with no `repo/` says `commits:
|
|
1143
|
+
no repository copy`. When a retained worktree of the same repository is on
|
|
1144
|
+
the recovery's branch, the recovery line names it: the uncommitted bytes
|
|
1145
|
+
may be in both.
|
|
1146
|
+
|
|
1085
1147
|
**Recovery copies** are at
|
|
1086
1148
|
`<instances>/.oats-retirement/recovery/<instance>-<random>/`, beside the
|
|
1087
1149
|
homes of the agent the instance belonged to. The retire summary prints the
|
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.
|
|
57
|
+
oats.framework: v1.9.0 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v5.0.0
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
package/lib/capability-show.mjs
CHANGED
|
@@ -15,6 +15,10 @@
|
|
|
15
15
|
* - Paths in the answers are POSIX and relative to the capability directory. `--file` reads only a path the
|
|
16
16
|
* show lists (the inject, a listed skill file): no other file of the capability is readable through it.
|
|
17
17
|
*
|
|
18
|
+
* - A manifest that declares `triggerSources` (#669) shows them exactly as declared, and the problems a trigger
|
|
19
|
+
* naming them would get (lib/trigger-sources.mjs) as `triggerSourceProblems`: a malformed declaration never
|
|
20
|
+
* refuses the show (containment), as it never refuses the capability.
|
|
21
|
+
*
|
|
18
22
|
* Every text is untrusted repository content; a consumer renders it as plain text or through a sanitising
|
|
19
23
|
* renderer (the docs say so).
|
|
20
24
|
*/
|
|
@@ -25,6 +29,7 @@ import { bindRemote } from "./packages.mjs";
|
|
|
25
29
|
import { locatedContractWarnings } from "./capability-contract.mjs";
|
|
26
30
|
import { capabilitySkills, lockedCapability, lockedPackageCapabilities, manifestFilePath, memberRef, unsafeRelPath } from "./resolve.mjs";
|
|
27
31
|
import { memberRowByKey } from "./workspace.mjs";
|
|
32
|
+
import { triggerSourcesOf } from "./trigger-sources.mjs";
|
|
28
33
|
|
|
29
34
|
export const CAPABILITY_SHOW_API = 1;
|
|
30
35
|
/** A text is cut to at most this many UTF-8 bytes; binary detection examines this many + 3. */
|
|
@@ -169,6 +174,14 @@ const header = (source) => ({ capabilityShowApi: CAPABILITY_SHOW_API, name: sour
|
|
|
169
174
|
/** What the capability declares and this kernel ignores (an unknown hook event), where its manifest is read. */
|
|
170
175
|
const contractWarnings = (source) => locatedContractWarnings(source.manifest, source.kind === "package" ? `package:${source.package}:${source.dir}/oats.json` : `${source.repoKey}:${source.dir}/oats.json`);
|
|
171
176
|
|
|
177
|
+
/** The trigger sources a manifest declares, as declared, and their use-time problems: added keys, each only when
|
|
178
|
+
* there is something to say. */
|
|
179
|
+
function triggerSourceKeys(manifest) {
|
|
180
|
+
if (manifest?.triggerSources === undefined) return {};
|
|
181
|
+
const { problems } = triggerSourcesOf(manifest);
|
|
182
|
+
return { triggerSources: manifest.triggerSources, ...(problems.length ? { triggerSourceProblems: problems } : {}) };
|
|
183
|
+
}
|
|
184
|
+
|
|
172
185
|
/** The show answer (capabilityShowApi 1): the inject with its text, each skill with its description and files. */
|
|
173
186
|
export async function capabilityShow(source, { remote, remoteOptions }) {
|
|
174
187
|
const r = bindRemote(remote, remoteOptions);
|
|
@@ -195,7 +208,7 @@ export async function capabilityShow(source, { remote, remoteOptions }) {
|
|
|
195
208
|
skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
|
|
196
209
|
}
|
|
197
210
|
}
|
|
198
|
-
return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems, warnings: contractWarnings(source) };
|
|
211
|
+
return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems, warnings: contractWarnings(source), ...triggerSourceKeys(source.manifest) };
|
|
199
212
|
}
|
|
200
213
|
|
|
201
214
|
/** The `--file` answer: one file the show lists (the inject, or a listed skill file), at the row's commit.
|