@awebai/oats 0.51.0 → 0.53.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/README.md +3 -1
- package/bin/oats.mjs +407 -123
- package/docs/capabilities.md +75 -6
- package/docs/configuration.md +200 -91
- package/docs/desktop-cli-api.md +1563 -113
- package/docs/desktop-instance-start.md +69 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +145 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +238 -17
- package/docs/integrations.md +13 -9
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/macos-test-runs.md +246 -0
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +225 -11
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/release-notes/v0.53.0.md +1274 -0
- package/docs/schedules.md +97 -4
- package/docs/souls-and-instances.md +332 -40
- package/docs/tui.md +584 -0
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +278 -49
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +1282 -289
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +45 -17
- package/lib/instance-lifecycle.mjs +306 -57
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +236 -9
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +125 -22
- package/lib/schedule.mjs +73 -24
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/system-tools.mjs +39 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +54 -30
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +4 -4
- package/package.json +8 -2
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +561 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +72 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +95 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +180 -0
- package/packages/client/deployment-read-cli.mjs +57 -0
- package/packages/client/display-text.mjs +50 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +90 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +76 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +86 -0
- package/packages/client/instance-tree.mjs +462 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +200 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +413 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +48 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +293 -0
- package/packages/client/readiness-contract.mjs +174 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +151 -0
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +153 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +195 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +142 -0
- package/packages/client/spawn-preview-cli.mjs +38 -0
- package/packages/client/spawn-preview-contract.mjs +318 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +183 -0
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +64 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +44 -0
- package/packages/tui/lib/client.mjs +35 -0
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +176 -0
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +367 -0
- package/packages/tui/lib/term/screen.mjs +134 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +109 -0
- package/packages/tui/lib/term/tty.mjs +178 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +256 -0
- package/packages/tui/lib/views/help.mjs +140 -0
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +30 -23
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- package/lib/launch-prompt-policy.mjs +0 -87
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/** Which acts a roster row offers, decided from the kernel's row alone. A client draws its menu, its
|
|
2
|
+
* keys or its buttons from this answer: verbs and reasons, never a label, an icon or a key.
|
|
3
|
+
*
|
|
4
|
+
* instanceActs(instance) -> { blocked: Reason | null, limited: Reason | null, acts: Act[] }
|
|
5
|
+
* Act = { verb, enabled, reason: Reason | null }
|
|
6
|
+
* Reason = { code, sentence } and, by code:
|
|
7
|
+
* { code: 'unaddressable', key, sentence, origin? } key: the row reason's own (remote-address.mjs rowReason)
|
|
8
|
+
* { code: 'held', kind, sentence } kind: 'spawning' | 'spawn-incomplete' | 'retire-incomplete'
|
|
9
|
+
* { code: 'unsupported-session', sentence, origin? }
|
|
10
|
+
* { code: 'not-running', sentence } an `open` act's only (`openAct`)
|
|
11
|
+
* { code: 'state-unknown', sentence } an `open` act's only
|
|
12
|
+
*
|
|
13
|
+
* A client may switch on `code`, and on `key` or `kind` when it needs to; never on the sentence.
|
|
14
|
+
* The sentences are the ones the shared tables already produce. Two of them can be text this home did
|
|
15
|
+
* not write (an unaddressable row's `runtimeError`, the kernel's reason for a removed session backend): a
|
|
16
|
+
* client shows a sentence only through display-text.mjs `displayLine`.
|
|
17
|
+
*
|
|
18
|
+
* `origin` is there exactly when the sentence is not this home's own (the rule of `rowReason`, whose
|
|
19
|
+
* answer's `origin` is passed on as it is, never decided again here): "kernel", "terminal-probe" or
|
|
20
|
+
* "roster-read" when the row names the speaker of its `runtimeError`, "unattributed" when the row's text
|
|
21
|
+
* stands beside no speaker. It is absent on a sentence this home wrote and on the stand-in for an older
|
|
22
|
+
* kernel's Herdr row, and a `held` reason never has one. A client shows a sentence with an `origin`
|
|
23
|
+
* through its display filter, after instance-presentation.mjs `originLead`'s words when the value names
|
|
24
|
+
* a speaker, and a sentence with none as written, as this home's own.
|
|
25
|
+
*
|
|
26
|
+
* `blocked`: the row offers nothing, and this is why; `acts` is then empty.
|
|
27
|
+
* `limited`: the row offers fewer acts than a home normally does, and this is why. It is about the
|
|
28
|
+
* row, not about one act: **a client adds none of its own acts to a limited row.**
|
|
29
|
+
* `blocked` and `limited` are never both set. An act's own `reason` says why that one act is listed
|
|
30
|
+
* and not enabled; the others stay as they are.
|
|
31
|
+
*
|
|
32
|
+
* In order, the first that applies:
|
|
33
|
+
* a remote row the kernel does not report addressable blocked (unaddressable); no acts
|
|
34
|
+
* a home the kernel holds, spawning blocked (held); no acts
|
|
35
|
+
* a home the kernel holds, spawn or retire incomplete limited (held); retire
|
|
36
|
+
* a session backend OATS no longer has inspect, start (not enabled, unsupported-session), stop, retire
|
|
37
|
+
* running === true inspect, restart, stop, retire
|
|
38
|
+
* running === false inspect, start, stop, retire
|
|
39
|
+
* running unknown inspect, stop, retire
|
|
40
|
+
*
|
|
41
|
+
* openAct(instance) -> { verb: 'open', enabled, reason: Reason | null } | null
|
|
42
|
+
*
|
|
43
|
+
* Whether the row's terminal can be opened, and why not. It is not one of `acts`: it is read from
|
|
44
|
+
* `instanceActs`'s answer and from nothing else of the row, so the order above is written once.
|
|
45
|
+
* blocked or limited is set null: the row's own reason says why, and a client adds no act
|
|
46
|
+
* restart is listed, enabled enabled: the row runs
|
|
47
|
+
* start is listed, enabled not enabled (not-running)
|
|
48
|
+
* start is listed, not enabled not enabled, with that act's own reason (unsupported-session)
|
|
49
|
+
* neither is listed not enabled (state-unknown)
|
|
50
|
+
* A client's own condition for opening a terminal (a recorded session on this machine, say) is the
|
|
51
|
+
* client's, and is not here.
|
|
52
|
+
*/
|
|
53
|
+
import { heldHome } from './instance-tree.mjs';
|
|
54
|
+
import { unsupportedSession } from './instance-presentation.mjs';
|
|
55
|
+
import { canAddressRemote, rowReason } from './remote-address.mjs';
|
|
56
|
+
|
|
57
|
+
const act = (verb, reason = null) => ({ verb, enabled: !reason, reason });
|
|
58
|
+
// An `open` act's own two codes, and the one sentence both carry.
|
|
59
|
+
const NOT_RUNNING = 'not-running', STATE_UNKNOWN = 'state-unknown';
|
|
60
|
+
const NO_LIVE_TERMINAL = 'No live terminal is reported.';
|
|
61
|
+
|
|
62
|
+
export function instanceActs(instance) {
|
|
63
|
+
if (!canAddressRemote(instance)) {
|
|
64
|
+
const { key, sentence, origin } = rowReason(instance);
|
|
65
|
+
return { blocked: { code: 'unaddressable', key, sentence, ...(origin !== undefined ? { origin } : {}) }, limited: null, acts: [] };
|
|
66
|
+
}
|
|
67
|
+
// #802: a home the kernel holds starts, stops and opens nothing. Retire only when a spawn or a retire left it
|
|
68
|
+
// half cleaned (the kernel's retire completes it), nothing while its spawn sets up the worktree.
|
|
69
|
+
const held = heldHome(instance);
|
|
70
|
+
if (held) {
|
|
71
|
+
const reason = { code: 'held', kind: held.kind, sentence: held.sentence(instance.instance) };
|
|
72
|
+
return held.retire ? { blocked: null, limited: reason, acts: [act('retire')] } : { blocked: reason, limited: null, acts: [] };
|
|
73
|
+
}
|
|
74
|
+
// A Herdr-recorded row cannot start or restart: Start stays listed, not enabled, with the kernel's reason.
|
|
75
|
+
// Its sentence and its `origin` are the row reason's own (rowReason answers this reason first for such a row).
|
|
76
|
+
const herdr = unsupportedSession(instance) ? rowReason(instance) : null;
|
|
77
|
+
const launch = herdr ? [act('start', { code: 'unsupported-session', sentence: herdr.sentence, ...(herdr.origin !== undefined ? { origin: herdr.origin } : {}) })]
|
|
78
|
+
: instance.running === true ? [act('restart')] : instance.running === false ? [act('start')] : [];
|
|
79
|
+
return { blocked: null, limited: null, acts: [act('inspect'), ...launch, act('stop'), act('retire')] };
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
export function openAct(instance) {
|
|
83
|
+
const { blocked, limited, acts } = instanceActs(instance);
|
|
84
|
+
if (blocked || limited) return null;
|
|
85
|
+
const restart = acts.find(({ verb }) => verb === 'restart'), start = acts.find(({ verb }) => verb === 'start');
|
|
86
|
+
if (restart?.enabled) return act('open');
|
|
87
|
+
if (start?.enabled) return act('open', { code: NOT_RUNNING, sentence: NO_LIVE_TERMINAL });
|
|
88
|
+
if (start) return act('open', start.reason);
|
|
89
|
+
return act('open', { code: STATE_UNKNOWN, sentence: NO_LIVE_TERMINAL });
|
|
90
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/** Shared qualified roster authority. No filesystem, kernel import or process.
|
|
2
|
+
* Individual operations negotiate their own CLI feature/API after admission. */
|
|
3
|
+
import { isAbsolute, basename } from 'node:path';
|
|
4
|
+
import { gitTarget } from './instance-git-contract.mjs';
|
|
5
|
+
import { canAddressRemote, unaddressableSentence, unroutableReason } from './remote-address.mjs';
|
|
6
|
+
export { canAddressRemote };
|
|
7
|
+
export const record = v => !!v && typeof v === 'object' && !Array.isArray(v);
|
|
8
|
+
export const absolute = v => typeof v === 'string' && isAbsolute(v) && !v.includes('\0');
|
|
9
|
+
const name = v => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(v);
|
|
10
|
+
const host = v => v === null || v === undefined || typeof v === 'string' && /^[a-z0-9][a-z0-9-]{0,63}$/.test(v);
|
|
11
|
+
export function instanceSelector(v) {
|
|
12
|
+
return record(v) && Object.keys(v).every(k => ['instance', 'agent', 'agentsRoot', 'server'].includes(k))
|
|
13
|
+
&& name(v.instance) && name(v.agent) && absolute(v.agentsRoot) && host(v.server);
|
|
14
|
+
}
|
|
15
|
+
/** Admit one roster row. A remote row is admitted only in its own remote workspace, when the kernel
|
|
16
|
+
* reports it addressable and this machine's probe routes `operation` (a `remote` entry). The
|
|
17
|
+
* admitted `context` is then this machine's cwd (`localCwd`), never a `--dir`: the kernel sends the
|
|
18
|
+
* registered workspace. A remote denial carries a `reason` naming the server. */
|
|
19
|
+
export function admitInstance(selector, { workspace, instances = [], cli, operation, localCwd } = {}) {
|
|
20
|
+
const denied = (code, target = null, reason = undefined) => ({ code, target, ...(reason ? { reason } : {}) });
|
|
21
|
+
if (!instanceSelector(selector)) return denied('E_BAD_ARGS');
|
|
22
|
+
if (!workspace || typeof workspace.id !== 'string' || !workspace.id || !absolute(workspace.scope)) return denied('E_WORKSPACE_UNKNOWN');
|
|
23
|
+
const matches = (Array.isArray(instances) ? instances : []).filter(i => record(i) && host(i.server)
|
|
24
|
+
&& i.instance === selector.instance && i.agent === selector.agent && i.agentsRoot === selector.agentsRoot && (i.server ?? null) === (selector.server ?? null));
|
|
25
|
+
if (matches.length !== 1) return denied(matches.length ? 'E_AMBIGUOUS_INSTANCE' : 'E_SESSION_UNKNOWN');
|
|
26
|
+
const instance = matches[0];
|
|
27
|
+
if (!absolute(instance.home) || basename(instance.home) !== instance.instance) return denied('E_HOME_MISMATCH');
|
|
28
|
+
const target = gitTarget({ workspace: workspace.id, instance: instance.instance, agent: instance.agent,
|
|
29
|
+
agentsRoot: instance.agentsRoot, home: instance.home, server: instance.server ?? null });
|
|
30
|
+
if (!target) return denied('E_HOME_MISMATCH');
|
|
31
|
+
const remote = !!(workspace.remote || workspace.server || instance.remote || target.server);
|
|
32
|
+
if (remote) {
|
|
33
|
+
// Never resolve a remote target against a local panel, or the reverse.
|
|
34
|
+
if (!workspace.remote || !host(workspace.server) || !workspace.server || target.server !== workspace.server) return denied('E_SESSION_UNKNOWN', target);
|
|
35
|
+
const label = workspace.name || workspace.server;
|
|
36
|
+
if (!canAddressRemote(instance)) return denied('E_SNAPSHOT_UNKNOWN', target,
|
|
37
|
+
{ code: 'E_SNAPSHOT_UNKNOWN', message: unaddressableSentence({ ...instance, repoName: label }), detail: null, remote: true });
|
|
38
|
+
if (typeof operation !== 'string' || !Array.isArray(cli?.remote) || !cli.remote.includes(operation)) return denied('unsupported-remote-operation', target, unroutableReason(label));
|
|
39
|
+
if (cli?.ok !== true || !absolute(cli.bin)) return denied('cli-unavailable', target);
|
|
40
|
+
if (!absolute(localCwd)) return denied('E_WORKSPACE_UNKNOWN', target);
|
|
41
|
+
return { target, context: localCwd, bin: cli.bin, remote: { server: workspace.server, label } };
|
|
42
|
+
}
|
|
43
|
+
if (cli?.ok !== true || !absolute(cli.bin)) return denied('cli-unavailable', target);
|
|
44
|
+
return { target, context: workspace.scope, bin: cli.bin };
|
|
45
|
+
}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
/** K7 API2 consumer input contract. Pure data validation; no log/kernel IO. */
|
|
2
|
+
import { absolute, record } from './readiness-contract.mjs';
|
|
3
|
+
import { remoteReason } from './remote-address.mjs';
|
|
4
|
+
const exact = (v, keys) => record(v) && Object.keys(v).every(k => keys.includes(k));
|
|
5
|
+
const name = v => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/.test(v);
|
|
6
|
+
const text = (v, max = 4096) => typeof v === 'string' && !!v && v.length <= max && !/[\x00-\x1f\x7f]/.test(v);
|
|
7
|
+
export const EVENTS_LIMITS = Object.freeze([50, 100, 200]);
|
|
8
|
+
export const EVENTS_DEFAULT_LIMIT = 100;
|
|
9
|
+
export const eventsTimestamp = v => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(v)
|
|
10
|
+
&& Number.isFinite(Date.parse(v)) && new Date(v).toISOString() === v;
|
|
11
|
+
/** Text the activity view and the roster may show: no control characters, no URL, no token-looking
|
|
12
|
+
* assignment. Shared by packages/desktop/renderer/instance-events-data.mjs and waiting-on-you.mjs. The URL
|
|
13
|
+
* alternative finds `://` first and looks behind it for the scheme, as display-text.mjs `UNSAFE` does and
|
|
14
|
+
* for its reason: time that grows with the length of the text, not with the square of a run. */
|
|
15
|
+
export const eventsUnsafe = /[\x00-\x08\x0b-\x1f\x7f]|:\/\/(?<=[a-z][a-z0-9+.-]*:\/\/)\S+|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}|(?:token|authorization|password|secret|api[_ -]?key)\s*[:=]\s*\S+/i;
|
|
16
|
+
/** A producer or kind id: non-empty, ≤ 256, no control characters, nothing unsafe. */
|
|
17
|
+
export const eventsId = v => typeof v === 'string' && !!v && v.length <= 256 && !/[\x00-\x1f\x7f]/.test(v) && !eventsUnsafe.test(v);
|
|
18
|
+
/** What stands in for text eventsUnsafe refuses. The one literal: eventsDetail and waitingMessage return it,
|
|
19
|
+
* and the sidebar's claim (waitingOnYouData) reads it as "no note". */
|
|
20
|
+
export const EVENTS_WITHHELD = '[Detail withheld]';
|
|
21
|
+
/** A free-text detail: a string ≤ max (throws otherwise); unsafe text is withheld, never shown. */
|
|
22
|
+
export function eventsDetail(v, max = 2048) {
|
|
23
|
+
if (typeof v !== 'string' || v.length > max) throw Error('invalid event detail');
|
|
24
|
+
return eventsUnsafe.test(v) ? EVENTS_WITHHELD : v;
|
|
25
|
+
}
|
|
26
|
+
export const eventsLimit = v => EVENTS_LIMITS.includes(v) ? v : null;
|
|
27
|
+
export const eventsSupported = cli => cli?.ok === true && absolute(cli.bin) && cli.eventsApi === 2
|
|
28
|
+
&& Array.isArray(cli.features) && cli.features.includes('instance-events-2');
|
|
29
|
+
/** Renderer supplies a qualified selector (a server id for a remote row), never a home or log path. */
|
|
30
|
+
export function eventsSelector(v) {
|
|
31
|
+
return exact(v, ['instance', 'agent', 'agentsRoot', 'server']) && name(v.instance) && name(v.agent)
|
|
32
|
+
&& absolute(v.agentsRoot) && (v.server === null || typeof v.server === 'string' && /^[a-z0-9][a-z0-9-]{0,63}$/.test(v.server))
|
|
33
|
+
? { instance: v.instance, agent: v.agent, agentsRoot: v.agentsRoot, server: v.server } : null;
|
|
34
|
+
}
|
|
35
|
+
export function eventsRequest(v) {
|
|
36
|
+
if (!exact(v, ['action', 'selector', 'limit']) || v.action !== 'read') return null;
|
|
37
|
+
const selector = eventsSelector(v.selector);
|
|
38
|
+
const limit = Object.hasOwn(v, 'limit') ? eventsLimit(v.limit) : EVENTS_DEFAULT_LIMIT;
|
|
39
|
+
return selector && limit !== null ? { action: 'read', selector, limit } : null;
|
|
40
|
+
}
|
|
41
|
+
/** Only server admission supplies these paths. Syntactic validation is NOT
|
|
42
|
+
* roster/scope admission, incarnation proof, or authority to open a file. */
|
|
43
|
+
export function eventsTarget(v) {
|
|
44
|
+
const selector = eventsSelector(v?.selector);
|
|
45
|
+
return record(v) && selector && text(v.workspace) && absolute(v.context) && absolute(v.home)
|
|
46
|
+
&& v.home.split('/').at(-1) === selector.instance && (v.incarnation == null || eventsTimestamp(v.incarnation))
|
|
47
|
+
? { workspace: v.workspace, context: v.context, selector, home: v.home, incarnation: v.incarnation ?? null } : null;
|
|
48
|
+
}
|
|
49
|
+
const errors = {
|
|
50
|
+
E_BAD_ARGS: 'Activity requires one qualified local instance and an approved row limit.',
|
|
51
|
+
E_EVENTS_UNAVAILABLE: 'Activity requires advertised instance-events-2 and integer eventsApi 2. API 1 is not invoked.',
|
|
52
|
+
E_WORKSPACE_UNKNOWN: 'Choose an advertised local workspace.',
|
|
53
|
+
E_SESSION_UNKNOWN: 'The selected instance is no longer in the current roster.',
|
|
54
|
+
E_AMBIGUOUS_INSTANCE: 'Choose one exact instance home.',
|
|
55
|
+
E_HOME_MISMATCH: 'The instance home no longer matches the selected address.',
|
|
56
|
+
E_NOT_IN_SCOPE: 'The selected instance is outside this workspace scope.',
|
|
57
|
+
E_TARGET_CHANGED: 'The workspace, instance or CLI changed. Load activity again.',
|
|
58
|
+
'cli-unavailable': 'Choose a compatible installed OATS CLI.',
|
|
59
|
+
'unsupported-remote-operation': "This computer's OATS can't route this to the server. Update OATS here.",
|
|
60
|
+
E_UNSUPPORTED_MODE: 'Activity is unavailable for this execution mode; no classic fallback.',
|
|
61
|
+
'unsupported-action': 'This CLI cannot read activity for the selected execution mode.',
|
|
62
|
+
E_BUSY: 'Two activity reads are already in progress. Retry when one finishes.',
|
|
63
|
+
E_FORBIDDEN_FRAME: 'This frame cannot request activity.',
|
|
64
|
+
E_CLI_TIMEOUT: 'The activity read timed out.',
|
|
65
|
+
E_CLI_OUTPUT_LIMIT: 'The activity response exceeded its output limit.',
|
|
66
|
+
E_CLI_PROTOCOL: 'The CLI returned invalid or mismatched activity data.',
|
|
67
|
+
E_CLI_FAILED: 'The installed CLI could not complete the activity read.',
|
|
68
|
+
};
|
|
69
|
+
/** `reason`: a remote read's reason (remote-address.mjs), kept only when it validates. */
|
|
70
|
+
export function eventsFailure(code, target = null, reason = null) {
|
|
71
|
+
if (!Object.hasOwn(errors, code)) code = 'E_CLI_FAILED';
|
|
72
|
+
return { instanceEventsViewApi: 1, status: 'unavailable', target: eventsTarget(target), data: null,
|
|
73
|
+
reason: remoteReason(reason) || { code, message: errors[code] } };
|
|
74
|
+
}
|
|
75
|
+
/** The fixed sentence for an activity code: the headline of a host refusal outside the remote table. */
|
|
76
|
+
export const eventsMessage = code => eventsFailure(code).reason.message;
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
/** Public K1 DTO checks only; no Git parsing, filesystem reads or kernel imports.
|
|
2
|
+
* Shared by the Desktop read boundary and its inert renderer controller. */
|
|
3
|
+
export const INSTANCE_GIT_MINIMUM_VERSION = '0.24.7';
|
|
4
|
+
export const INSTANCE_DIFF_LIMIT = 256 * 1024;
|
|
5
|
+
export const gitKinds = ['changed', 'renamed', 'copied', 'unmerged', 'untracked'];
|
|
6
|
+
const object = v => !!v && typeof v === 'object' && !Array.isArray(v);
|
|
7
|
+
const text = v => typeof v === 'string' && v.length > 0 && !v.includes('\0');
|
|
8
|
+
const nullable = v => v === null || text(v);
|
|
9
|
+
const count = v => Number.isSafeInteger(v) && v >= 0;
|
|
10
|
+
const optionalCount = v => v === null || count(v);
|
|
11
|
+
export const gitFileId = v => typeof v === 'string' && /^[a-f0-9]{24}$/.test(v);
|
|
12
|
+
export const gitRevision = v => v === 'unborn' || typeof v === 'string' && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(v);
|
|
13
|
+
// An opaque producer fingerprint, NOT a Git tree object or a path.
|
|
14
|
+
export const gitIndexRevision = v => typeof v === 'string' && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(v);
|
|
15
|
+
export function gitObservation(v) {
|
|
16
|
+
if (!object(v) || !gitRevision(v.revision) || !gitIndexRevision(v.indexRevision)
|
|
17
|
+
|| !text(v.at) || !Number.isFinite(Date.parse(v.at)) || !text(v.worktree) || !nullable(v.branch)
|
|
18
|
+
|| typeof v.detached !== 'boolean' || typeof v.unborn !== 'boolean'
|
|
19
|
+
|| v.unborn !== (v.revision === 'unborn') || (v.detached && (v.unborn || v.branch !== null))) return null;
|
|
20
|
+
return { revision: v.revision, indexRevision: v.indexRevision, at: v.at, worktree: v.worktree,
|
|
21
|
+
branch: v.branch, detached: v.detached, unborn: v.unborn };
|
|
22
|
+
}
|
|
23
|
+
export function gitTarget(v) {
|
|
24
|
+
if (!object(v) || !['workspace', 'instance', 'agent', 'agentsRoot', 'home'].every(k => text(v[k])) || !nullable(v.server)) return null;
|
|
25
|
+
return Object.fromEntries(['workspace', 'instance', 'agent', 'agentsRoot', 'home', 'server'].map(k => [k, v[k]]));
|
|
26
|
+
}
|
|
27
|
+
export const gitTargetKey = v => JSON.stringify([v.workspace, v.instance, v.agent, v.agentsRoot, v.home, v.server]);
|
|
28
|
+
/* Per-file line counts (kernel #238, 0.29.1): additions/deletions are non-negative integers or
|
|
29
|
+
null (unknown, NOT zero: binary, untracked, submodules); binary is a boolean or null. Absent on
|
|
30
|
+
older kernels, so absent here too. */
|
|
31
|
+
const lineCount = v => v === null || (Number.isSafeInteger(v) && v >= 0);
|
|
32
|
+
const lineCounts = v => ['additions', 'deletions'].every(k => v[k] === undefined || lineCount(v[k])) && (v.binary === undefined || v.binary === null || typeof v.binary === 'boolean');
|
|
33
|
+
const counted = v => Object.fromEntries(['additions', 'deletions', 'binary'].filter(k => v[k] !== undefined).map(k => [k, v[k]]));
|
|
34
|
+
export function gitFile(v, full = false) {
|
|
35
|
+
if (!object(v) || !gitFileId(v.id) || !gitKinds.includes(v.kind) || typeof v.xy !== 'string'
|
|
36
|
+
|| !/^[.MADRCUT?!]{2}$/.test(v.xy) || !text(v.path) || !nullable(v.origPath)
|
|
37
|
+
|| (['renamed', 'copied'].includes(v.kind) && !text(v.origPath))
|
|
38
|
+
|| (full && typeof v.submodule !== 'boolean') || (v.score !== undefined && !text(v.score))
|
|
39
|
+
|| (full && !lineCounts(v))) return null;
|
|
40
|
+
return { id: v.id, kind: v.kind, xy: v.xy, path: v.path, origPath: v.origPath,
|
|
41
|
+
...(full ? { submodule: v.submodule, ...(v.score === undefined ? {} : { score: v.score }), ...counted(v) } : {}) };
|
|
42
|
+
}
|
|
43
|
+
export function gitState(v, target) {
|
|
44
|
+
const observation = gitObservation(v?.observation);
|
|
45
|
+
if (!object(v) || v.instanceGitApi !== 1 || !observation || !target
|
|
46
|
+
|| v.home !== target.home || v.instance !== target.instance || v.agent !== target.agent || !nullable(v.workMode)
|
|
47
|
+
|| !object(v.recorded) || !nullable(v.recorded.branch) || !nullable(v.recorded.repo) || typeof v.recorded.drift !== 'boolean'
|
|
48
|
+
|| !object(v.upstream) || !nullable(v.upstream.ref) || !optionalCount(v.upstream.ahead) || !optionalCount(v.upstream.behind)
|
|
49
|
+
|| !object(v.base) || !['ref', 'source', 'mergeBase'].every(k => nullable(v.base[k])) || !optionalCount(v.base.ahead) || !optionalCount(v.base.behind)
|
|
50
|
+
|| !object(v.summary) || !gitKinds.every(k => count(v.summary[k]))
|
|
51
|
+
|| !Array.isArray(v.files) || !Array.isArray(v.notes) || v.notes.some(n => typeof n !== 'string')) return null;
|
|
52
|
+
if (v.upstream.ref === null && (v.upstream.ahead !== null || v.upstream.behind !== null)) return null;
|
|
53
|
+
if (v.base.ref === null && (v.base.ahead !== null || v.base.behind !== null || v.base.mergeBase !== null)) return null;
|
|
54
|
+
const files = v.files.map(f => gitFile(f, true));
|
|
55
|
+
if (files.some(f => !f) || new Set(files.map(f => f.id)).size !== files.length
|
|
56
|
+
|| gitKinds.some(k => files.filter(f => f.kind === k).length !== v.summary[k])) return null;
|
|
57
|
+
return { instanceGitApi: 1, instance: v.instance, agent: v.agent, home: v.home, workMode: v.workMode, observation,
|
|
58
|
+
recorded: { branch: v.recorded.branch, repo: v.recorded.repo, drift: v.recorded.drift },
|
|
59
|
+
upstream: { ref: v.upstream.ref, ahead: v.upstream.ahead, behind: v.upstream.behind },
|
|
60
|
+
base: { ref: v.base.ref, source: v.base.source, mergeBase: v.base.mergeBase, ahead: v.base.ahead, behind: v.base.behind },
|
|
61
|
+
summary: Object.fromEntries(gitKinds.map(k => [k, v.summary[k]])), files, notes: [...v.notes] };
|
|
62
|
+
}
|
|
63
|
+
export function gitDiff(v, { fileId, revision, indexRevision, observation: expected, file: selected } = {}) {
|
|
64
|
+
const observation = gitObservation(v?.observation), file = gitFile(v?.file);
|
|
65
|
+
if (!object(v) || v.instanceGitApi !== 1 || !observation || !file
|
|
66
|
+
|| file.id !== fileId || observation.revision !== revision || observation.indexRevision !== indexRevision
|
|
67
|
+
|| (expected && observation.worktree !== expected.worktree)
|
|
68
|
+
|| (selected && ['id', 'path', 'origPath', 'kind', 'xy'].some(k => file[k] !== selected[k]))
|
|
69
|
+
|| (file.kind !== 'untracked' && revision === 'unborn')
|
|
70
|
+
|| v.against !== (file.kind === 'untracked' ? 'empty' : revision)
|
|
71
|
+
|| typeof v.binary !== 'boolean' || typeof v.truncated !== 'boolean' || typeof v.patch !== 'string'
|
|
72
|
+
|| !count(v.bytes) || v.limit !== INSTANCE_DIFF_LIMIT
|
|
73
|
+
|| v.readOnly?.helpers !== 'disabled' || v.readOnly?.optionalLocks !== 'off' || v.readOnly?.objectsWritten !== 0) return null;
|
|
74
|
+
const length = new TextEncoder().encode(v.patch).length;
|
|
75
|
+
if (length > v.limit || (v.binary && (length || v.bytes || v.truncated))
|
|
76
|
+
|| (!v.truncated && v.bytes !== length) || (v.truncated && v.bytes <= v.limit)) return null;
|
|
77
|
+
return { instanceGitApi: 1, observation, file, against: v.against, binary: v.binary, bytes: v.bytes,
|
|
78
|
+
truncated: v.truncated, limit: v.limit, patch: v.patch,
|
|
79
|
+
readOnly: { helpers: 'disabled', optionalLocks: 'off', objectsWritten: 0 } };
|
|
80
|
+
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { HERDR_REMOVED } from "./terminal-contract.mjs";
|
|
2
|
+
import { requireTerms } from './client-terms.mjs';
|
|
3
|
+
|
|
4
|
+
export function runtimeState(instance) {
|
|
5
|
+
return instance.running === true ? "running" : instance.running === false ? "stopped" : "unknown";
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
/** The stand-in `unsupportedSession` writes for an older kernel's Herdr row: the one text of a row that is
|
|
9
|
+
* this home's own sentence. Not on the stable surface. */
|
|
10
|
+
export const HERDR_STAND_IN = `E_HERDR_REMOVED: ${HERDR_REMOVED}`;
|
|
11
|
+
|
|
12
|
+
/** The row carries the kernel's own reason for a removed session backend, which `unsupportedSession` answers as it is. */
|
|
13
|
+
const kernelsOwnReason = (instance) => instance?.runtimeState === "unsupported" && typeof instance.runtimeError === "string" && !!instance.runtimeError;
|
|
14
|
+
|
|
15
|
+
/** Why a kernel-reported row has no usable session, or null. A Herdr-recorded
|
|
16
|
+
* instance cannot open, start or restart; it can still retire. A 0.31 kernel
|
|
17
|
+
* reports it as runtimeState "unsupported" with its E_HERDR_REMOVED text; an
|
|
18
|
+
* older kernel only records a sessionTarget (local) or a herdr backend
|
|
19
|
+
* (remote), and its runtimeError is a Herdr probe's, so the stem stands in. */
|
|
20
|
+
export function unsupportedSession(instance) {
|
|
21
|
+
const stem = HERDR_STAND_IN;
|
|
22
|
+
if (instance?.runtimeState === "unsupported") return kernelsOwnReason(instance) ? instance.runtimeError : stem;
|
|
23
|
+
return (instance?.sessionTarget !== undefined && instance?.sessionTarget !== null) || instance?.backend === "herdr" ? stem : null;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Who wrote what `unsupportedSession` answers for a row as the kernel or a host reported it: "kernel"
|
|
27
|
+
* for the row's own text, null for the stand-in written here (and for a row it answers null for). Asked
|
|
28
|
+
* where the text is chosen (liveness.mjs, remote-roster.mjs), of the reported row: a panel's row already
|
|
29
|
+
* holds the chosen text as its `runtimeError`, stand-in included, and its speaker in `runtimeErrorOrigin`.
|
|
30
|
+
* Not on the stable surface. */
|
|
31
|
+
export const unsupportedSessionOrigin = (instance) => (kernelsOwnReason(instance) ? "kernel" : null);
|
|
32
|
+
|
|
33
|
+
/** The speakers a text of a row can have, as `runtimeErrorOrigin` and a reason's `origin` name them, each
|
|
34
|
+
* with the words a client puts in front of the text (`originLead`):
|
|
35
|
+
*
|
|
36
|
+
* kernel read from a kernel answer: this machine's OATS, or another host's OATS relayed by it.
|
|
37
|
+
* A client names both the same; a row's `serverUnreached` says which read the text is about.
|
|
38
|
+
* terminal-probe made by the client's terminal check (liveness.mjs, tmux-status.mjs): a sentence of
|
|
39
|
+
* its own, or the message of a failed `tmux` or `ps` run
|
|
40
|
+
* roster-read made by the client while it read the roster of other machines (remote-roster.mjs)
|
|
41
|
+
*
|
|
42
|
+
* A text with no speaker (the stand-in above) has no key. The marks are written here, in the shared home,
|
|
43
|
+
* at the place that chooses the text, and never taken from an answer: a key a kernel, a host or the
|
|
44
|
+
* liveness collector sent is dropped on every path.
|
|
45
|
+
*
|
|
46
|
+
* A reason's `origin` has one more value, "unattributed", with no words: remote-address.mjs `rowReason`
|
|
47
|
+
* writes it for a row's text that reached it beside no speaker. It names nobody, so it is not in this
|
|
48
|
+
* table, `originLead` answers null for it, and it is never a row's `runtimeErrorOrigin` nor a kept
|
|
49
|
+
* failure's `errorOrigin`. */
|
|
50
|
+
const LEADS = Object.freeze({
|
|
51
|
+
kernel: () => "OATS says:",
|
|
52
|
+
"terminal-probe": (terms) => `${terms.name}'s terminal check says:`,
|
|
53
|
+
"roster-read": (terms) => `${terms.name}'s read of other machines says:`,
|
|
54
|
+
});
|
|
55
|
+
/** Whether a value is one of the three speakers. Not on the stable surface. */
|
|
56
|
+
export const knownOrigin = (value) => typeof value === "string" && Object.hasOwn(LEADS, value);
|
|
57
|
+
|
|
58
|
+
/** The words a client puts in front of a text to name who made it, or null when `origin` is not one of
|
|
59
|
+
* the three speakers (absent, or any other value). It takes a row's `runtimeErrorOrigin`, a reason's
|
|
60
|
+
* `origin` (remote-address.mjs `rowReason`, instance-acts.mjs) or a kept failure's `errorOrigin`: all hold
|
|
61
|
+
* the same values. A client writes nothing of its own there, so two clients name a speaker the same way.
|
|
62
|
+
*
|
|
63
|
+
* kernel "OATS says:" no term: the word the other sentences use
|
|
64
|
+
* terminal-probe "<name>'s terminal check says:" `terms.name` (client-terms.mjs)
|
|
65
|
+
* roster-read "<name>'s read of other machines says:"
|
|
66
|
+
*
|
|
67
|
+
* The two checks name the client: the kernel's own text can be about a terminal server too, so "the
|
|
68
|
+
* terminal check" alone would not say whose check it was. A text with no lead is shown as the client's
|
|
69
|
+
* own words always were: never under "OATS says:". A reason's "unattributed" is such a value: no words.
|
|
70
|
+
* `terms` is required, also where no term is used. */
|
|
71
|
+
export function originLead(origin, terms) {
|
|
72
|
+
requireTerms(terms, "originLead");
|
|
73
|
+
return knownOrigin(origin) ? LEADS[origin](terms) : null;
|
|
74
|
+
}
|
|
75
|
+
/** Whether a row has a `runtimeError`: a string that is not empty. Only such a row carries `runtimeErrorOrigin`. */
|
|
76
|
+
export const hasRuntimeError = (row) => typeof row?.runtimeError === "string" && !!row.runtimeError;
|
|
77
|
+
/** The speaker of a row's own `runtimeError`, or null: the row's `runtimeErrorOrigin` when the row has a
|
|
78
|
+
* text and the key names one of the three. The key is a panel row's, set by the shared home
|
|
79
|
+
* (deployment-panel.mjs, remote-roster.mjs). Not on the stable surface. */
|
|
80
|
+
export const runtimeErrorSpeaker = (row) => (hasRuntimeError(row) && knownOrigin(row.runtimeErrorOrigin) ? row.runtimeErrorOrigin : null);
|
|
81
|
+
|
|
82
|
+
export function runtimeCounts(instances) {
|
|
83
|
+
const counts = { running: 0, stopped: 0, unknown: 0 };
|
|
84
|
+
for (const instance of instances) counts[runtimeState(instance)]++;
|
|
85
|
+
return counts;
|
|
86
|
+
}
|