@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.
Files changed (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. 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
+ }