@awebai/oats 0.69.12 → 0.69.15
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 +216 -178
- package/bin/oats.mjs +254 -201
- package/docs/capabilities.md +58 -13
- package/docs/configuration.md +63 -5
- package/docs/container.md +291 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +590 -55
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +84 -9
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +99 -32
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/schedules.md +159 -5
- package/docs/servers.md +241 -7
- package/docs/souls-and-instances.md +223 -14
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +36 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +20 -5
- package/lib/command-flags.mjs +240 -0
- package/lib/core.mjs +1004 -633
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +145 -33
- package/lib/errors.mjs +3 -2
- package/lib/harness-token.mjs +110 -0
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +165 -14
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +114 -43
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/kernel-features.mjs +4 -1
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +4 -1
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +126 -31
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +239 -21
- package/lib/servers.mjs +161 -28
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +63 -56
- package/lib/session-seen.mjs +3 -14
- package/lib/start-env.mjs +13 -7
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +68 -10
- package/package-catalog.json +1 -1
- package/package.json +5 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +93 -26
- package/lib/tmux-config.mjs +0 -35
package/lib/deployments.mjs
CHANGED
|
@@ -16,8 +16,9 @@
|
|
|
16
16
|
* inside it), under the same lock, and records `imports["agents-dir"]` even when there is nothing
|
|
17
17
|
* to import. A command whose import could not run fails: it never answers a list that skipped it.
|
|
18
18
|
*
|
|
19
|
-
* Concurrency: every read-modify-write holds `config/deployments.lock` (withDirLock
|
|
20
|
-
*
|
|
19
|
+
* Concurrency: every read-modify-write holds `config/deployments.lock` (withDirLock: a file that
|
|
20
|
+
* names its holder, taken over when that process is gone), waits up to 3 s for a holder that runs
|
|
21
|
+
* and re-reads inside it; each write replaces the file atomically. Readers take no lock:
|
|
21
22
|
* they read a regular file only, without following a link, up to 1 MiB. A row's `state` is an
|
|
22
23
|
* existence check: no deployment's content is read here.
|
|
23
24
|
*/
|
|
@@ -144,7 +145,7 @@ function updateDeployments(change, { wait = LOCK_WAIT_MS } = {}) {
|
|
|
144
145
|
}, { retryMs: wait, busy: (why) => deploymentsError("E_DEPLOYMENTS_BUSY", `this computer's deployments list is locked (${why}); if no oats process is changing it, remove ${lock} and retry; nothing was changed`, { file, lock }) });
|
|
145
146
|
} catch (e) {
|
|
146
147
|
if (typeof e?.code === "string" && e.code.startsWith("E_")) throw e;
|
|
147
|
-
// The lock
|
|
148
|
+
// The lock itself could not be made or written: the list was not touched.
|
|
148
149
|
if (typeof e?.code === "string") throw writeFailed(file, e);
|
|
149
150
|
throw e;
|
|
150
151
|
}
|
package/lib/dir-lock.mjs
CHANGED
|
@@ -1,39 +1,151 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
* processes share (the host schedule state, the server registry
|
|
2
|
+
* The lock for short read-modify-write sections over files several oats
|
|
3
|
+
* processes share (the host schedule state, the server registry, this
|
|
4
|
+
* computer's deployments list, a deployment's oats-local.yaml).
|
|
5
|
+
*
|
|
6
|
+
* It is a claim (lib/claim.mjs): one file at the lock's path that names its
|
|
7
|
+
* holder by pid and process start. One process holds it at a time. A lock
|
|
8
|
+
* whose holder is verifiably gone (killed, exited, its pid reused by another
|
|
9
|
+
* process) is taken over by the next acquirer; one whose holder lives, or
|
|
10
|
+
* cannot be judged, never is.
|
|
11
|
+
*
|
|
12
|
+
* A SIGINT or SIGTERM that arrives while a section runs waits for it: the
|
|
13
|
+
* section completes, the lock is released, and then the signal is raised
|
|
14
|
+
* again, so it ends the process as it would have (holdSignals).
|
|
15
|
+
*
|
|
16
|
+
* A holder that keeps the lock across asynchronous work (the machine's resume
|
|
17
|
+
* sweep, lib/session-resume.mjs) takes it with acquireDirLock and releases it
|
|
18
|
+
* itself. No signal is held back for it: a holder a signal ends leaves its
|
|
19
|
+
* lock, and the next acquirer takes it over.
|
|
4
20
|
*/
|
|
5
21
|
|
|
6
|
-
import {
|
|
7
|
-
import { dirname
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
const
|
|
11
|
-
|
|
12
|
-
/**
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
22
|
+
import { lstatSync, mkdirSync } from "node:fs";
|
|
23
|
+
import { dirname } from "node:path";
|
|
24
|
+
import { acquireClaim, claimUnheld, releaseClaim, shownHolder } from "./claim.mjs";
|
|
25
|
+
|
|
26
|
+
const isDirectory = (path) => { try { return lstatSync(path).isDirectory(); } catch { return false; } };
|
|
27
|
+
|
|
28
|
+
/** The claim's refusals (lib/claim.mjs) for the lock `path`, each made with the caller's
|
|
29
|
+
* `busy(why, { found })`: `why` is a clause that says what was found, for the caller's own
|
|
30
|
+
* sentence, which names `path` as what to remove; `found` is one word for it:
|
|
31
|
+
* running a holder that lives
|
|
32
|
+
* unknown a holder whose liveness cannot be established
|
|
33
|
+
* own-start-unreadable this process's own start cannot be read, so it could not hold the lock
|
|
34
|
+
* directory a directory at `path`, the lock of an earlier kernel
|
|
35
|
+
* unreadable a record that does not parse
|
|
36
|
+
* cannot-take-over a gone holder's record that cannot be taken over
|
|
37
|
+
* held-again a lock found without a live holder and taken again, every time
|
|
38
|
+
* `at` is the file a refusal is about: `path`, or the claim of a takeover of it
|
|
39
|
+
* (`<path>.reclaim-<nonce>`), which is then named in full. A holder is named as shownHolder
|
|
40
|
+
* allows: text of a record is never part of `why`. */
|
|
41
|
+
function refusals(path, busy) {
|
|
42
|
+
const pid = (holder) => shownHolder(holder).pid ?? "?";
|
|
43
|
+
const held = (at) => (at === path ? "it" : `${at}, the claim of a takeover of it`);
|
|
44
|
+
return {
|
|
45
|
+
busy: (holder, unknown, at) => (unknown
|
|
46
|
+
? busy(`whether pid ${pid(holder)}, which holds ${held(at)}, still runs cannot be established: ${unknown}`, { found: "unknown" })
|
|
47
|
+
: busy(`pid ${pid(holder)} holds ${held(at)}`, { found: "running" })),
|
|
48
|
+
ownStartUnreadable: (reason) => busy(`this process's own start time cannot be read (${reason}), so it cannot hold the lock verifiably`, { found: "own-start-unreadable" }),
|
|
49
|
+
// A directory is the lock of a kernel that locked with one. It is never removed here and its
|
|
50
|
+
// owner is never judged: while that kernel runs it holds the directory, which excludes this
|
|
51
|
+
// one; once it is gone the operator removes the directory, as the caller's sentence says.
|
|
52
|
+
unreadableClaim: (at) => (isDirectory(at)
|
|
53
|
+
? busy(`${at} is a lock directory written by an earlier kernel`, { found: "directory" })
|
|
54
|
+
: busy(`the record at ${at} is unreadable`, { found: "unreadable" })),
|
|
55
|
+
cannotTakeOver: (holder, at, why) => busy(`the holder of ${at}, pid ${pid(holder)}, is gone, and that file cannot be taken over (${why}); it must be removed`, { found: "cannot-take-over" }),
|
|
56
|
+
heldAgain: (holder, at, times) => busy(`${at} was found without a live holder ${times} times and was taken again each time, the last time by a process that is gone; retry`, { found: "held-again" }),
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** What stops the lock `path` from being taken, read and not taken → `{ why, found }` as an
|
|
61
|
+
* acquirer's `busy` is handed them (refusals), or null when nobody holds it: no lock is there, or
|
|
62
|
+
* its holder is gone and the next acquirer takes it over. A lock that cannot be read for a reason
|
|
63
|
+
* of the system's is `unreadable`. Nothing is written, removed or waited for. `holderGone` as
|
|
64
|
+
* acquireDirLock takes it. */
|
|
65
|
+
export function dirLockHeld(path, { holderGone } = {}) {
|
|
66
|
+
const found = refusals(path, (why, { found }) => ({ why, found }));
|
|
67
|
+
try { claimUnheld(path, { holderGone, ...found }, found.unreadableClaim(path)); }
|
|
68
|
+
catch (held) {
|
|
69
|
+
if (typeof held?.found === "string") return held;
|
|
70
|
+
throw held;
|
|
32
71
|
}
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
72
|
+
return null;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** What to do about a lock `path` that needs a person, by what was found (`found`: refusals), said
|
|
76
|
+
* to whoever ran `command` (`oats session resume`), the one command that takes the lock. A
|
|
77
|
+
* directory is the lock of a kernel that locked with one: nothing here tells whether that kernel's
|
|
78
|
+
* command runs, so it is the operator who removes it. A record that cannot be read, or whose
|
|
79
|
+
* holder cannot be told to run, is removed once a person has seen that no `command` runs. A gone
|
|
80
|
+
* holder's record is removed without that. Where nothing is in the way (the lock was taken again
|
|
81
|
+
* each time, or this process cannot read its own start) there is nothing to remove. */
|
|
82
|
+
const STUCK_REMEDY = {
|
|
83
|
+
directory: (path) => `once no earlier oats is running on this machine, remove the directory ${path} and run it again`,
|
|
84
|
+
"cannot-take-over": (path) => `remove ${path} and run it again`,
|
|
85
|
+
"held-again": () => "run it again",
|
|
86
|
+
"own-start-unreadable": (path) => `run it again; nothing at ${path} is to be removed`,
|
|
87
|
+
};
|
|
88
|
+
export function stuckLockRemedy(path, found, command) {
|
|
89
|
+
return STUCK_REMEDY[found]?.(path) ?? `if no ${command} is running on this machine, remove ${path} and run it again`;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** The signals a section is not cut short by. */
|
|
93
|
+
const HELD_SIGNALS = ["SIGINT", "SIGTERM"];
|
|
94
|
+
let sections = 0, listening = false, idle = null;
|
|
95
|
+
function stopListening() {
|
|
96
|
+
if (idle) { clearImmediate(idle); idle = null; }
|
|
97
|
+
if (!listening) return;
|
|
98
|
+
listening = false;
|
|
99
|
+
for (const signal of HELD_SIGNALS) process.off(signal, onHeldSignal);
|
|
100
|
+
}
|
|
101
|
+
/** A section is synchronous, so a signal that arrived during one reaches this listener after it,
|
|
102
|
+
* the lock released. The signal is raised again without this listener: it ends the process by its
|
|
103
|
+
* default action when nothing else listens for it, and reaches the listeners that do otherwise. */
|
|
104
|
+
function onHeldSignal(signal) {
|
|
105
|
+
stopListening();
|
|
106
|
+
process.kill(process.pid, signal);
|
|
107
|
+
}
|
|
108
|
+
/** Listen for HELD_SIGNALS while a section runs: a listener keeps a signal's default action from
|
|
109
|
+
* ending the process inside it. → the function to call when the section is over. The listeners
|
|
110
|
+
* stay until the event loop has turned once with no section running, which is when a signal that
|
|
111
|
+
* arrived during the section is delivered; taking them off at the section's end would drop it. */
|
|
112
|
+
function holdSignals() {
|
|
113
|
+
sections += 1;
|
|
114
|
+
if (idle) { clearImmediate(idle); idle = null; }
|
|
115
|
+
if (!listening) { listening = true; for (const signal of HELD_SIGNALS) process.on(signal, onHeldSignal); }
|
|
116
|
+
return () => { if (--sections === 0) idle = setImmediate(stopListening); };
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** Take the lock `path` → the function that releases it, only while the lock still names this
|
|
120
|
+
* holding. `facts` is what the lock's record says besides its holder.
|
|
121
|
+
*
|
|
122
|
+
* A holder that lives is waited for up to `retryMs`, then refused with `busy(why, { found })`,
|
|
123
|
+
* the caller's own error (`found`: refusals). Refused the same way, without waiting, and left as it is:
|
|
124
|
+
* a holder whose liveness cannot be read, a record that does not parse, a directory at `path`
|
|
125
|
+
* (the lock of an earlier kernel) and a gone holder's record that cannot be taken over. A lock
|
|
126
|
+
* whose holder is gone is taken over, so a process killed while it holds the lock stops nobody;
|
|
127
|
+
* `holderGone(holder)` is the caller's own reading of a record that says so (lib/claim.mjs).
|
|
128
|
+
*
|
|
129
|
+
* A failure of the system's to make the lock (its directory, its file) is thrown as the system's
|
|
130
|
+
* own error, for the caller to answer in its own words. */
|
|
131
|
+
export function acquireDirLock(path, facts, { retryMs = 0, busy, holderGone } = {}) {
|
|
132
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
133
|
+
let me;
|
|
134
|
+
try { me = acquireClaim(path, { waitMs: retryMs, facts, holderGone, ...refusals(path, busy) }); }
|
|
135
|
+
catch (e) {
|
|
136
|
+
// acquireClaim answers an error that is not the kernel's as E_LIFECYCLE_FAILED, holding it as `cause`.
|
|
137
|
+
throw e?.code === "E_LIFECYCLE_FAILED" && Object.hasOwn(e, "cause") ? e.cause : e;
|
|
138
|
+
}
|
|
139
|
+
return () => releaseClaim(path, me);
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** Run `fn` holding the lock `path` (acquireDirLock: how it is taken, and its refusals) → what
|
|
143
|
+
* `fn` returns; an error `fn` throws propagates once the lock is released. `what` says in the
|
|
144
|
+
* lock's record what the holder is doing. A SIGINT or SIGTERM during `fn` ends the process only
|
|
145
|
+
* once `fn` has returned and the lock is released (holdSignals). */
|
|
146
|
+
export function withDirLock(path, what, fn, { retryMs = 0, busy } = {}) {
|
|
147
|
+
const release = acquireDirLock(path, { what }, { retryMs, busy });
|
|
148
|
+
const sectionOver = holdSignals();
|
|
37
149
|
try { return fn(); }
|
|
38
|
-
finally {
|
|
150
|
+
finally { release(); sectionOver(); }
|
|
39
151
|
}
|
package/lib/errors.mjs
CHANGED
|
@@ -60,7 +60,8 @@ const SPAWN_REFUSAL_DETAILS = Object.freeze({
|
|
|
60
60
|
E_CHILD_SPAWNS_DISABLED: (e) => ({ parent: e.parent, policy: e.policy }),
|
|
61
61
|
E_BRANCH_EXISTS: () => undefined,
|
|
62
62
|
E_BASE_UNKNOWN: () => undefined,
|
|
63
|
-
// Interrupted while its
|
|
63
|
+
// Interrupted while its capabilities were copied into the home, or while its worktree hooks ran
|
|
64
|
+
// (#796): rolled back, the message says how far.
|
|
64
65
|
E_INTERRUPTED: (e) => e.details,
|
|
65
66
|
// The hooks' receipt (paths only), and `unconfirmed` when the rollback could not confirm its effects.
|
|
66
67
|
E_REQUIRED_HOOK_FAILED: hookReceipt,
|
|
@@ -192,7 +193,7 @@ export const ifItDoesNotEnd = (what, at) => `if it does not end, ${checkHolderBy
|
|
|
192
193
|
* after the verb's first effect is never answered (afterFirstEffect). The docs table of
|
|
193
194
|
* docs/desktop-cli-api.md is checked against this constant, and a client's own set must lie
|
|
194
195
|
* inside it (test/lifecycle-before-effect-codes.test.mjs). */
|
|
195
|
-
const BEFORE_EFFECT = Object.freeze(["E_BAD_ARGS", "E_PLAN_STALE", "E_INSTANCE_RETIRING", "E_LIFECYCLE_BUSY", "E_HOME_MISMATCH", "E_SESSION_UNKNOWN",
|
|
196
|
+
const BEFORE_EFFECT = Object.freeze(["E_BAD_ARGS", "E_USAGE", "E_PLAN_STALE", "E_INSTANCE_RETIRING", "E_LIFECYCLE_BUSY", "E_HOME_MISMATCH", "E_SESSION_UNKNOWN",
|
|
196
197
|
"E_AMBIGUOUS_INSTANCE", "E_UNIDENTIFIED_INSTANCE_HOME", "E_REMOTE_INCOMPATIBLE", "E_AMBIGUOUS", "E_SNAPSHOT_UNKNOWN"]);
|
|
197
198
|
export const BEFORE_EFFECT_CODES = Object.freeze({ "instance stop": BEFORE_EFFECT, retire: BEFORE_EFFECT });
|
|
198
199
|
/** The defect afterFirstEffect makes. Its name is on the prototype, so that it is in the stack's
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
/** Operator-only client for the pinned oats-login-receive forced-command protocol.
|
|
2
|
+
* Its response is metadata, never a remote OATS envelope or shell output to forward. */
|
|
3
|
+
import { execFileSync } from "node:child_process";
|
|
4
|
+
import { createHash } from "node:crypto";
|
|
5
|
+
import { readStreamBounded } from "./attachments.mjs";
|
|
6
|
+
import { getServer, operatorSshArgv, readServerOperatorRoutes, runRemote, serverError, targetOf } from "./servers.mjs";
|
|
7
|
+
import { shellWord } from "./shell-word.mjs";
|
|
8
|
+
|
|
9
|
+
const HARNESSES = new Set(["claude", "codex", "pi", "opencode"]);
|
|
10
|
+
const NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
|
|
11
|
+
const FINGERPRINT = /^sha256:[a-f0-9]{16}$/;
|
|
12
|
+
const delivery = (message) => serverError("E_HARNESS_TOKEN_DELIVERY", message);
|
|
13
|
+
const unexpected = () => delivery("Unexpected reply from the server's credential receiver.");
|
|
14
|
+
function replacedAt(value) {
|
|
15
|
+
return typeof value === "string" && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$/.test(value)
|
|
16
|
+
&& Number.isFinite(Date.parse(value)) && new Date(value).toISOString().replace(".000Z", "Z") === value;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function receiverReply(call, action, harness, name, secret = "") {
|
|
20
|
+
// Hitting maxBuffer also signals the child; it is a bad reply, not a failed hop.
|
|
21
|
+
if (call.code === "ENOBUFS") throw unexpected();
|
|
22
|
+
if (call.status === 255 || ["ENOENT", "ETIMEDOUT"].includes(call.code) || call.signal) throw delivery("Couldn't reach the server. Check the operator SSH alias and connection.");
|
|
23
|
+
let reply;
|
|
24
|
+
try {
|
|
25
|
+
const text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(call.stdout ?? "")).trim();
|
|
26
|
+
if (/[\r\n]/.test(text)) throw unexpected();
|
|
27
|
+
reply = JSON.parse(text);
|
|
28
|
+
} catch { throw unexpected(); }
|
|
29
|
+
if (!reply || reply.harness !== harness || reply.name !== name || typeof reply.ok !== "boolean") throw unexpected();
|
|
30
|
+
if (!reply.ok) {
|
|
31
|
+
if (call.status !== 1 || typeof reply.error !== "string" || !reply.error || reply.error.length > 2048) throw unexpected();
|
|
32
|
+
const reason = secret ? reply.error.replaceAll(secret, "<redacted>") : reply.error;
|
|
33
|
+
throw delivery(`The server refused the credential: ${reason.replace(/[\x00-\x1f\x7f]/g, " ")}`);
|
|
34
|
+
}
|
|
35
|
+
if (call.status !== 0 || !replacedAt(reply.replacedAt) || (action === "remove" ? reply.fingerprint !== null : typeof reply.fingerprint !== "string" || !FINGERPRINT.test(reply.fingerprint))) throw unexpected();
|
|
36
|
+
return { fingerprint: reply.fingerprint, replacedAt: reply.replacedAt };
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
async function credentialBytes(input, harness) {
|
|
40
|
+
const bad = (message) => serverError("E_HARNESS_TOKEN_INPUT", message);
|
|
41
|
+
if (input === undefined) throw serverError("E_HARNESS_TOKEN_UNSUPPORTED", harness === "claude"
|
|
42
|
+
? "Interactive Claude token setup is not available. Pipe an existing inference-only setup-token with --stdin."
|
|
43
|
+
: harness === "opencode" ? "Interactive opencode sign-in is not supported. Pipe a provider API key with --stdin."
|
|
44
|
+
: "Browser sign-in needs refreshing credentials and an agent-writable auth file, which the read-only operator route cannot support. Pipe a non-refreshing provider API key with --stdin.");
|
|
45
|
+
if (input?.isTTY) throw bad("Pipe the credential with --stdin; terminal input would show it.");
|
|
46
|
+
if (!Buffer.isBuffer(input) && (!input || typeof input[Symbol.asyncIterator] !== "function")) throw bad("Supply credential bytes or a readable stdin stream.");
|
|
47
|
+
let raw;
|
|
48
|
+
try { raw = Buffer.isBuffer(input) ? input : await readStreamBounded(input, 65536); }
|
|
49
|
+
catch (e) { throw bad(e?.code === "E_UPLOAD_TOO_LARGE" ? "The credential input is larger than 64 KiB." : "Couldn't read the credential from stdin."); }
|
|
50
|
+
if (raw.length > 65536) throw bad("The credential input is larger than 64 KiB.");
|
|
51
|
+
let value;
|
|
52
|
+
try { value = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw).replace(/^[\x09-\x0d\x20]+|[\x09-\x0d\x20]+$/g, ""); }
|
|
53
|
+
catch { throw bad("The credential must be UTF-8 text."); }
|
|
54
|
+
if (!value || /[\0\r\n]/.test(value)) throw bad("Give one non-empty credential line with no NUL bytes.");
|
|
55
|
+
const bytes = Buffer.from(value);
|
|
56
|
+
if (bytes.length > 65535) throw bad("The credential must leave room for its final newline within 64 KiB.");
|
|
57
|
+
if (harness === "claude" && (!value.startsWith("sk-ant-oat") || bytes.length > 512)) throw bad("This is not a Claude setup-token. Pipe an inference-only token beginning with sk-ant-oat.");
|
|
58
|
+
return bytes;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function olderSessions(registration, server, harness, at, secret, io) {
|
|
62
|
+
const { envelope } = runRemote(targetOf(registration), ["status", "--json", "--dir", registration.workspace], { execFileSync: io.execFileSync, serverId: server, timeoutMs: 60000 });
|
|
63
|
+
if (!envelope.ok || !Array.isArray(envelope.result?.agents)) throw unexpected();
|
|
64
|
+
// The receiver truncates to whole seconds; starts during that second may still
|
|
65
|
+
// have read the previous file. Include them rather than silently miss a session.
|
|
66
|
+
const before = Date.parse(at) + 1000;
|
|
67
|
+
const out = [];
|
|
68
|
+
for (const agent of envelope.result.agents) for (const row of agent.instances ?? []) {
|
|
69
|
+
if ((row.harness ?? row.runtime ?? agent.harness ?? agent.runtime) !== harness || row.startedAt === null) continue;
|
|
70
|
+
if (typeof row.startedAt !== "string" || !Number.isFinite(Date.parse(row.startedAt))) throw unexpected();
|
|
71
|
+
if (Date.parse(row.startedAt) >= before) continue;
|
|
72
|
+
const item = { instance: row.instance, agent: agent.name, home: row.home, startedAt: row.startedAt };
|
|
73
|
+
if (Object.values(item).some((v) => typeof v !== "string" || !v || v.includes(secret))) throw unexpected();
|
|
74
|
+
out.push(item);
|
|
75
|
+
}
|
|
76
|
+
return out;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** The operator transport is chosen and validated before any input is consumed or SSH runs. */
|
|
80
|
+
export async function harnessToken({ action, harness, server, name, input }, io = {}) {
|
|
81
|
+
if (!["set", "status", "remove"].includes(action) || !HARNESSES.has(harness) || typeof server !== "string" || !server || (action !== "set" && input !== undefined)) throw serverError("E_BAD_ARGS", "Give set, status or remove, a harness, and --server <id>. Only set reads stdin.");
|
|
82
|
+
const registration = getServer(server), routes = readServerOperatorRoutes();
|
|
83
|
+
const route = Object.hasOwn(routes, server) ? routes[server] : undefined;
|
|
84
|
+
if (!route) {
|
|
85
|
+
const command = ["oats", "server", "add", server, "--ssh", registration.sshHost, "--workspace", registration.workspace];
|
|
86
|
+
for (const [key, flag] of [["label", "--label"], ["oatsPath", "--oats"], ["path", "--path"]]) {
|
|
87
|
+
if (registration[key] !== undefined) command.push(flag, registration[key]);
|
|
88
|
+
}
|
|
89
|
+
throw serverError("E_HARNESS_TOKEN_ROUTE", `Server ${server} has no operator SSH route. Register one with ${command.map(shellWord).join(" ")} --operator-ssh <alias> --replace. Credentials never use the agent route.`);
|
|
90
|
+
}
|
|
91
|
+
const selectedName = name ?? registration.label;
|
|
92
|
+
if (typeof selectedName !== "string" || !NAME.test(selectedName)) throw serverError("E_BAD_ARGS", "Give --name <team>: lowercase letters, digits and dashes, starting with a letter or digit, at most 63 characters. A server label is used only when it follows these rules.");
|
|
93
|
+
const credential = action === "set" ? await credentialBytes(input, harness) : undefined;
|
|
94
|
+
const [bin, ...args] = operatorSshArgv(route.operatorSshHost, [action === "set" ? "install" : action, harness, selectedName]);
|
|
95
|
+
let call;
|
|
96
|
+
try {
|
|
97
|
+
call = { status: 0, stdout: (io.execFileSync ?? execFileSync)(bin, args, { stdio: [credential ? "pipe" : "ignore", "pipe", "pipe"], ...(credential ? { input: credential } : {}), maxBuffer: 65536, timeout: 60000 }) };
|
|
98
|
+
} catch (error) { call = { status: error.status, stdout: error.stdout, code: error.code, signal: error.signal }; }
|
|
99
|
+
// Even debug output must not forward a receiver that unexpectedly echoes input, including a
|
|
100
|
+
// truncated prefix that cannot be safely redacted. Transport facts are enough to diagnose the hop.
|
|
101
|
+
io.debug?.(`operator SSH: exit ${Number.isInteger(call.status) ? call.status : "unknown"}${["ENOENT", "ETIMEDOUT", "ENOBUFS", "EACCES"].includes(call.code) ? ", " + call.code : ""}`);
|
|
102
|
+
const secret = credential?.toString("utf8") ?? "";
|
|
103
|
+
const result = { server, action, harness, name: selectedName, ...receiverReply(call, action, harness, selectedName, secret), warnings: [] };
|
|
104
|
+
if (credential) {
|
|
105
|
+
if (result.fingerprint !== "sha256:" + createHash("sha256").update(credential).digest("hex").slice(0, 16)) throw unexpected();
|
|
106
|
+
try { result.staleInstances = olderSessions(registration, server, harness, result.replacedAt, secret, io); }
|
|
107
|
+
catch { result.staleInstances = null; result.warnings.push("The credential was installed, but older sessions could not be listed. Existing sessions pick it up at their next start; nothing was restarted."); }
|
|
108
|
+
}
|
|
109
|
+
return result;
|
|
110
|
+
}
|
package/lib/host-run.mjs
ADDED
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
/** `oats host run` (oats-project/oats#1789): the kernel's periodic work in one foreground process,
|
|
2
|
+
* for a host where no timer can run it (a container, a machine without launchd or a systemd user
|
|
3
|
+
* manager). Every `oats` command is short-lived and agents sit under a daemonised tmux server, so
|
|
4
|
+
* without it nothing there runs the resume sweep at start or the schedule tick each minute, and
|
|
5
|
+
* nothing stops the agents in order when the host stops.
|
|
6
|
+
*
|
|
7
|
+
* - Refused before any effect: inside an instance session (OATS_INSTANCE_HOME set), E_USAGE; while
|
|
8
|
+
* the host timer is active (lib/schedule-host.mjs hostUnitStatus), E_HOST_RUN_TIMER_ACTIVE: two
|
|
9
|
+
* tickers would run. Unit files that are installed and not active are a warning. Nothing asks
|
|
10
|
+
* whether this is a container: the command is as right on a machine without a user manager.
|
|
11
|
+
* - One host run per machine: the lock `host-run/lock` under OATS_HOME_DIR (default ~/.oats), taken
|
|
12
|
+
* as the resume sweep takes its own (lib/dir-lock.mjs acquireDirLock): a claim that names its
|
|
13
|
+
* holder by pid, process start and boot id. A lock whose holder is gone, or that was taken in
|
|
14
|
+
* another boot (in a container, another run), is taken over at once; a holder that runs, and a
|
|
15
|
+
* lock that cannot be judged, are E_HOST_RUN_BUSY, `details` `{ lock, found }`.
|
|
16
|
+
* - A run, in order: the lock; the resume sweep once (`oats session resume`); then, at second 0 of
|
|
17
|
+
* each minute, `oats schedule tick --host` when the host schedule registry lists a scope (with
|
|
18
|
+
* none it ticks nothing and says so), and a listing of every deployment's instances, which
|
|
19
|
+
* records what runs for the next start's sweep. Each is an `oats` child, so this process's
|
|
20
|
+
* loop stays free for the signal. A minute whose tick still runs is skipped; a minute missed is
|
|
21
|
+
* never replayed (the host timer's own rule).
|
|
22
|
+
* - SIGTERM or SIGINT stops it (hostRun): ticking first, then every running home, so that the
|
|
23
|
+
* next start resumes them; then it answers and exits 0.
|
|
24
|
+
* - `plan` says what a run would refuse, the scopes it would tick (the host schedule registry) and
|
|
25
|
+
* what its sweep would do (lib/session-resume.mjs, its own plan), and changes nothing.
|
|
26
|
+
* The answers' shapes and the two codes are a contract (docs/desktop-cli-api.md). */
|
|
27
|
+
import { homedir } from "node:os";
|
|
28
|
+
import { join } from "node:path";
|
|
29
|
+
import { fileURLToPath } from "node:url";
|
|
30
|
+
import { acquireDirLock, dirLockHeld, stuckLockRemedy } from "./dir-lock.mjs";
|
|
31
|
+
import { oatsError } from "./errors.mjs";
|
|
32
|
+
import { hostUnitStatus } from "./schedule-host.mjs";
|
|
33
|
+
import { readRegistry } from "./schedule.mjs";
|
|
34
|
+
import { kernelAnswer, resumeSessions } from "./session-resume.mjs";
|
|
35
|
+
import { OUTCOME } from "./session-resume-contract.mjs";
|
|
36
|
+
import { bootId, takenInAnotherBoot } from "./session-seen.mjs";
|
|
37
|
+
|
|
38
|
+
export const HOST_RUN_SCHEMA = 1;
|
|
39
|
+
/** What a run and a plan say when the host schedule registry lists no scope. */
|
|
40
|
+
export const NO_SCOPE_SAID = "no scope is registered, so nothing is ticked: register a deployment with oats schedule host install --register-only --dir <deployment>";
|
|
41
|
+
|
|
42
|
+
/** The signals that stop a run: what a container runtime sends, and Ctrl-C. */
|
|
43
|
+
const STOP_SIGNALS = ["SIGTERM", "SIGINT"];
|
|
44
|
+
const oatsHomeDir = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
|
|
45
|
+
export const hostRunLockPath = () => join(oatsHomeDir(), "host-run", "lock");
|
|
46
|
+
|
|
47
|
+
/** E_HOST_RUN_BUSY for the lock `path`, found as lib/dir-lock.mjs says it (`why`, `found`): a host
|
|
48
|
+
* run that runs, or a lock that needs a person, with what to do about it. */
|
|
49
|
+
function hostRunBusy(path, why, found) {
|
|
50
|
+
const said = found === "running" ? `another oats host run on this machine holds ${path} (${why})` : `the host run lock ${path} cannot be taken (${why}); ${stuckLockRemedy(path, found, "oats host run")}`;
|
|
51
|
+
return Object.assign(oatsError("E_HOST_RUN_BUSY", `${said}; nothing was started`), { details: { lock: path, found } });
|
|
52
|
+
}
|
|
53
|
+
/** Take the machine's host run lock → its release function. Its record also names the boot it was
|
|
54
|
+
* taken in (lib/session-seen.mjs bootId, takenInAnotherBoot), as the resume sweep's does. */
|
|
55
|
+
export function acquireHostRunLock({ boot = bootId() } = {}) {
|
|
56
|
+
const path = hostRunLockPath();
|
|
57
|
+
return acquireDirLock(path, { bootId: boot }, { busy: (why, { found }) => hostRunBusy(path, why, found), holderGone: takenInAnotherBoot(boot) });
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** What refuses a run before it takes its lock, in the order a run meets them: `inInstance`, the
|
|
61
|
+
* refusal inside an instance session, or null; `timer(unit)`, the refusal for what the host timer
|
|
62
|
+
* answered (hostUnitStatus), or null. A run asks the timer only once it is not refused as an instance. */
|
|
63
|
+
function refusalsBeforeLock({ env, hostStatus }) {
|
|
64
|
+
const home = env.OATS_INSTANCE_HOME;
|
|
65
|
+
const inInstance = home ? oatsError("E_USAGE", `oats host run runs as the host, never inside an instance session: OATS_INSTANCE_HOME is set (${home}); nothing was started`) : null;
|
|
66
|
+
return { inInstance, timer: (unit) => (unit.active ? Object.assign(oatsError("E_HOST_RUN_TIMER_ACTIVE", `the host timer is active (${unit.unit}) and already runs oats schedule tick --host every minute; remove it (oats schedule host uninstall) before oats host run; nothing was started`), { details: { unit: unit.unit } }) : null) };
|
|
67
|
+
}
|
|
68
|
+
/** The warning for unit files that are installed while the timer is not active, or none. */
|
|
69
|
+
const inactiveUnitWarnings = (unit) => (unit.installed && !unit.active
|
|
70
|
+
? [`the host timer's unit files are installed but not active (${unit.unit}): oats host run ticks in its place; remove them (oats schedule host uninstall) so that the timer cannot start beside it`] : []);
|
|
71
|
+
|
|
72
|
+
/** `oats host run --plan` → `{ schemaVersion, plan: true, refusals, warnings, scopes, sweep }`:
|
|
73
|
+
* `refusals` every refusal a run would meet now (`{ code, message, details? }`, in a run's order),
|
|
74
|
+
* the lock's included, `scopes` the registered scopes it would tick, `sweep` the resume sweep's
|
|
75
|
+
* own plan. Read only. */
|
|
76
|
+
export async function hostRunPlan({ env = process.env, boot = bootId(), hostStatus = hostUnitStatus } = {}) {
|
|
77
|
+
const refuse = refusalsBeforeLock({ env, hostStatus }), unit = hostStatus();
|
|
78
|
+
// The lock as a run would find it, read where the run takes it and not taken (dirLockHeld).
|
|
79
|
+
const path = hostRunLockPath(), held = dirLockHeld(path, { holderGone: takenInAnotherBoot(boot) });
|
|
80
|
+
const refusals = [refuse.inInstance, refuse.timer(unit), held && hostRunBusy(path, held.why, held.found)].filter(Boolean).map((e) => ({ code: e.code, message: e.message, ...(e.details ? { details: e.details } : {}) }));
|
|
81
|
+
return { schemaVersion: HOST_RUN_SCHEMA, plan: true, refusals, warnings: inactiveUnitWarnings(unit), scopes: readRegistry().workspaces, sweep: await resumeSessions({ plan: true, env }) };
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
const MINUTE = 60_000;
|
|
85
|
+
/** How long a stopped home's harness is given when `--stop-grace` says nothing: the stop's own default. */
|
|
86
|
+
const STOP_GRACE_MS = 20_000;
|
|
87
|
+
const STOP_CHILD = fileURLToPath(new URL("./host-stop-child.mjs", import.meta.url));
|
|
88
|
+
/** A timer that fires this long before its minute, or less, is early: nothing runs then. */
|
|
89
|
+
const EARLY_MS = 1000;
|
|
90
|
+
const plural = (n, what) => `${n} ${what}${n === 1 ? "" : "s"}`;
|
|
91
|
+
/** A child's failure as the run says it. */
|
|
92
|
+
const failed = (answer) => `(${answer?.error?.code ?? "E_HOST_RUN_FAILED"}): ${answer?.error?.message ?? "no answer"}`;
|
|
93
|
+
/** The sweep's rows by outcome, in the order they first appear: `2 resumed, 1 skipped`. */
|
|
94
|
+
function sweepSaid(rows) {
|
|
95
|
+
const counts = new Map();
|
|
96
|
+
for (const row of rows) counts.set(row.outcome, (counts.get(row.outcome) ?? 0) + 1);
|
|
97
|
+
return counts.size ? [...counts].map(([outcome, n]) => `${n} ${outcome}`).join(", ") : "nothing to resume";
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** `oats host run`: refuses (above), then runs until SIGTERM or SIGINT →
|
|
101
|
+
* `{ schemaVersion, plan: false, signal, warnings, sweep, ticks, stopped }`: `sweep` the resume
|
|
102
|
+
* sweep's answer, or `{ error: { code, message } }`; `ticks` the minutes counted (`run`,
|
|
103
|
+
* `skipped` while the tick before still ran, `failed`, `noScope` with no scope registered);
|
|
104
|
+
* `stopped` one row per home that ran when it stopped, in the listing's order (stopHome).
|
|
105
|
+
*
|
|
106
|
+
* On the signal, in this order: no minute is armed any more; a tick or a sweep that runs is
|
|
107
|
+
* waited for (a tick's wake job starts a stopped home, so ticking ends before any home is
|
|
108
|
+
* stopped); one listing; then every running home is stopped, side by side, each by a child of its
|
|
109
|
+
* own (lib/host-stop-child.mjs: the stop `oats session restart` and a retire use, its record
|
|
110
|
+
* written first and asking for a resume, the harness given `stopGraceMs` and never escalated).
|
|
111
|
+
* The next start's sweep resumes those homes.
|
|
112
|
+
*
|
|
113
|
+
* `stopHome(home, graceMs)` → Promise of `{ ok: true, home, stopped, alreadyIdle, state }` or
|
|
114
|
+
* `{ ok: false, home, code, message, stillRunning }`, which never rejects.
|
|
115
|
+
* `kernel` is `{ execPath, bin }`, how an `oats` child is run. The other options are the process
|
|
116
|
+
* boundary, for the tests: `run(argv)` → Promise of a child's JSON answer, which never rejects;
|
|
117
|
+
* `now()` and `timer(fn, ms)` → its cancel; `onSignal(handler)` → the function that stops
|
|
118
|
+
* listening; `scopes()` the registered scopes; `say(line)` one line of progress. */
|
|
119
|
+
export async function hostRun({
|
|
120
|
+
kernel, env = process.env, boot = bootId(), hostStatus = hostUnitStatus,
|
|
121
|
+
scopes = () => readRegistry().workspaces,
|
|
122
|
+
run = (argv) => kernelAnswer({ ...kernel, env }, argv, { code: "E_HOST_RUN_FAILED", what: `oats ${argv.join(" ")}` }),
|
|
123
|
+
stopGraceMs = STOP_GRACE_MS,
|
|
124
|
+
stopHome = async (home, graceMs) => {
|
|
125
|
+
const answer = await kernelAnswer({ execPath: kernel.execPath, bin: STOP_CHILD, env }, [home, String(graceMs)], { code: "E_SESSION_STOP_FAILED", what: "the stop" });
|
|
126
|
+
return answer.error ? { ok: false, home, code: answer.error.code, message: answer.error.message, stillRunning: null } : answer;
|
|
127
|
+
},
|
|
128
|
+
now = Date.now,
|
|
129
|
+
timer = (fn, ms) => { const armed = setTimeout(fn, ms); return () => clearTimeout(armed); },
|
|
130
|
+
onSignal = (handler) => {
|
|
131
|
+
for (const signal of STOP_SIGNALS) process.on(signal, handler);
|
|
132
|
+
return () => { for (const signal of STOP_SIGNALS) process.off(signal, handler); };
|
|
133
|
+
},
|
|
134
|
+
say = (line) => { process.stderr.write(`oats host run: ${line}\n`); },
|
|
135
|
+
} = {}) {
|
|
136
|
+
const refuse = refusalsBeforeLock({ env, hostStatus });
|
|
137
|
+
if (refuse.inInstance) throw refuse.inInstance;
|
|
138
|
+
const unit = hostStatus(), active = refuse.timer(unit);
|
|
139
|
+
if (active) throw active;
|
|
140
|
+
const release = acquireHostRunLock({ boot });
|
|
141
|
+
let signal = null, disarm = null, stopListening = () => {};
|
|
142
|
+
try {
|
|
143
|
+
const warnings = inactiveUnitWarnings(unit);
|
|
144
|
+
const stopRequested = new Promise((requested) => {
|
|
145
|
+
// The first signal ends the ticking at once: no minute is armed after it. A later one changes nothing.
|
|
146
|
+
stopListening = onSignal((received) => {
|
|
147
|
+
if (signal) return;
|
|
148
|
+
signal = received;
|
|
149
|
+
disarm?.();
|
|
150
|
+
requested();
|
|
151
|
+
});
|
|
152
|
+
});
|
|
153
|
+
say(`started (pid ${process.pid}); it holds ${hostRunLockPath()}`);
|
|
154
|
+
for (const warning of warnings) say(`warning: ${warning}`);
|
|
155
|
+
|
|
156
|
+
// The sweep, once: a home lost while this runs is a crash, and the sweep's bound is per boot.
|
|
157
|
+
const swept = await run(["session", "resume", "--json"]);
|
|
158
|
+
const sweep = swept?.ok === true ? swept.result : { error: { code: swept?.error?.code ?? "E_HOST_RUN_FAILED", message: swept?.error?.message ?? "no answer" } };
|
|
159
|
+
say(swept?.ok === true ? `resume sweep: ${sweepSaid(sweep.rows ?? [])}` : `resume sweep failed ${failed(swept)}`);
|
|
160
|
+
|
|
161
|
+
// The minutes. Each is armed from the clock as it reads then, for second 0 of the next one: a
|
|
162
|
+
// minute missed while this process did not run is never armed again.
|
|
163
|
+
const ticks = { run: 0, skipped: 0, failed: 0, noScope: 0 };
|
|
164
|
+
let ticking = null, listing = null, ticked;
|
|
165
|
+
const list = () => run(["session", "resume", "--plan", "--json"]);
|
|
166
|
+
const arm = () => { disarm = timer(minute, MINUTE - (now() % MINUTE)); };
|
|
167
|
+
const minute = () => {
|
|
168
|
+
if (signal) return;
|
|
169
|
+
// Early: a tick started now would evaluate the minute before (it reads its own start).
|
|
170
|
+
if (now() % MINUTE >= MINUTE - EARLY_MS) return arm();
|
|
171
|
+
let registered;
|
|
172
|
+
try { registered = scopes(); } catch (e) { registered = null; ticks.failed += 1; say(`tick failed (${e?.code ?? "E_HOST_RUN_FAILED"}): ${e?.message ?? e}`); }
|
|
173
|
+
if (registered && registered.join("\n") !== ticked) {
|
|
174
|
+
ticked = registered.join("\n");
|
|
175
|
+
say(registered.length ? `ticking ${plural(registered.length, "scope")} each minute: ${registered.join(", ")}` : NO_SCOPE_SAID);
|
|
176
|
+
}
|
|
177
|
+
if (registered && !registered.length) ticks.noScope += 1;
|
|
178
|
+
else if (registered && ticking) { ticks.skipped += 1; say("tick skipped: the tick of the minute before still runs"); }
|
|
179
|
+
else if (registered) {
|
|
180
|
+
ticks.run += 1;
|
|
181
|
+
ticking = run(["schedule", "tick", "--host", "--json"]).then((answer) => {
|
|
182
|
+
ticking = null;
|
|
183
|
+
if (answer?.ok !== true) { ticks.failed += 1; say(`tick failed ${failed(answer)}`); }
|
|
184
|
+
});
|
|
185
|
+
}
|
|
186
|
+
// The listing each minute writes what the sweep of the next start needs: that each running
|
|
187
|
+
// home was seen running (lib/session-seen.mjs recordSeen, by the sweep's own read of every
|
|
188
|
+
// deployment, which its plan does and nothing else).
|
|
189
|
+
listing ??= list().then((answer) => {
|
|
190
|
+
listing = null;
|
|
191
|
+
if (answer?.ok !== true) say(`listing failed ${failed(answer)}`);
|
|
192
|
+
});
|
|
193
|
+
arm();
|
|
194
|
+
};
|
|
195
|
+
if (!signal) arm();
|
|
196
|
+
await stopRequested;
|
|
197
|
+
|
|
198
|
+
// Ticking has ended. A tick that runs is waited for: its wake job may start a home.
|
|
199
|
+
say(`${signal}: ticking ended`);
|
|
200
|
+
await Promise.all([ticking, listing]);
|
|
201
|
+
const last = await list();
|
|
202
|
+
if (last?.ok !== true) say(`listing failed ${failed(last)}: no instance is stopped`);
|
|
203
|
+
const homes = last?.ok === true ? (last.result?.rows ?? []).filter((row) => row.outcome === OUTCOME.ALREADY_RUNNING && typeof row.home === "string").map((row) => row.home) : [];
|
|
204
|
+
if (homes.length) say(`stopping ${plural(homes.length, "running instance")}, each given ${stopGraceMs / 1000} s`);
|
|
205
|
+
// Side by side: each stop waits for its own harness, and the host's patience is one span for all.
|
|
206
|
+
const stopped = await Promise.all(homes.map(async (home) => {
|
|
207
|
+
const row = await stopHome(home, stopGraceMs);
|
|
208
|
+
say(row.ok ? (row.stopped ? `stopped ${home}` : `${home} was already idle`) : `could not stop ${home} (${row.code}): ${row.message}`);
|
|
209
|
+
return row;
|
|
210
|
+
}));
|
|
211
|
+
say("ended");
|
|
212
|
+
return { schemaVersion: HOST_RUN_SCHEMA, plan: false, signal, warnings, sweep, ticks, stopped };
|
|
213
|
+
} finally {
|
|
214
|
+
disarm?.();
|
|
215
|
+
stopListening();
|
|
216
|
+
release();
|
|
217
|
+
}
|
|
218
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/** Private entry point of lib/host-run.mjs; no CLI or provider contract. One process per running
|
|
2
|
+
* home when the host stops: `node host-stop-child.mjs <home> <grace ms>` stops that home's session
|
|
3
|
+
* with the host (lib/core.mjs stopInstanceSession, `withHost`: its record asks for a resume and is
|
|
4
|
+
* written before the harness is signalled) and prints one JSON line:
|
|
5
|
+
* { ok: true, home, stopped, alreadyIdle, state }
|
|
6
|
+
* { ok: false, home, code, message, stillRunning }
|
|
7
|
+
* A stop waits synchronously for its harness, so each home has a process of its own and the homes
|
|
8
|
+
* stop side by side. It exits 0 whatever the stop answered: the answer is the line. */
|
|
9
|
+
import { stillRunningOf, stopInstanceSession } from "./core.mjs";
|
|
10
|
+
import { kernelCode, reportDefect } from "./errors.mjs";
|
|
11
|
+
|
|
12
|
+
const [home, grace] = process.argv.slice(2);
|
|
13
|
+
let answer;
|
|
14
|
+
try {
|
|
15
|
+
const { stopped, alreadyIdle, state } = stopInstanceSession(home, { graceMs: Number(grace), withHost: true });
|
|
16
|
+
answer = { ok: true, home, stopped, alreadyIdle, state };
|
|
17
|
+
} catch (e) {
|
|
18
|
+
reportDefect(e); // the error becomes a row here: its stack would otherwise be lost
|
|
19
|
+
answer = { ok: false, home, code: kernelCode(e, "E_SESSION_STOP_FAILED"), message: String(e?.message ?? e), stillRunning: stillRunningOf(e) };
|
|
20
|
+
}
|
|
21
|
+
process.stdout.write(`${JSON.stringify(answer)}\n`);
|
package/lib/hot-reads.mjs
CHANGED
|
@@ -14,9 +14,9 @@
|
|
|
14
14
|
* test/cli-hot-reads.test.mjs runs each read and pins the modules it must not load. Kernel-private,
|
|
15
15
|
* not exported from `./core`. Dependency-free. */
|
|
16
16
|
|
|
17
|
-
/** The dispatch's own modules: argv's `--flag=value` expansion, the
|
|
18
|
-
* the resume feature, the inherited captured context's refusal. */
|
|
19
|
-
const DISPATCH = { argv: ["argv"], deprecation: ["deprecation"], errors: ["errors"], "session-resume-contract": ["session-resume-contract"], "captured-context": ["captured-context"] };
|
|
17
|
+
/** The dispatch's own modules: argv's `--flag=value` expansion, the flags each state-changing command defines,
|
|
18
|
+
* the deprecated-name warning, the typed failures, the resume feature, the inherited captured context's refusal. */
|
|
19
|
+
const DISPATCH = { argv: ["argv"], "command-flags": ["command-flags"], deprecation: ["deprecation"], errors: ["errors"], "session-resume-contract": ["session-resume-contract"], "captured-context": ["captured-context"] };
|
|
20
20
|
/** A read that lists its deployment (LISTS_ITS_DEPLOYMENT in bin/oats.mjs): the observer and the list. */
|
|
21
21
|
const LISTS = { "resolved-deployment": ["resolved-deployment"], deployments: ["deployments"] };
|
|
22
22
|
/** The deployment reads (status and workspace status): their call scope (lib/read-call.mjs: the remote budget,
|
|
@@ -42,6 +42,7 @@ const LEAVES = {
|
|
|
42
42
|
argv: () => import("./argv.mjs"),
|
|
43
43
|
"automation-api": () => import("./automation-api.mjs"),
|
|
44
44
|
"captured-context": () => import("./captured-context.mjs"),
|
|
45
|
+
"command-flags": () => import("./command-flags.mjs"),
|
|
45
46
|
deployments: () => import("./deployments.mjs"),
|
|
46
47
|
deprecation: () => import("./deprecation.mjs"),
|
|
47
48
|
errors: () => import("./errors.mjs"),
|