@awebai/oats 0.69.23 → 0.69.24

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 (74) hide show
  1. package/bin/oats.mjs +56 -17
  2. package/docs/capabilities.md +353 -5
  3. package/docs/capability-manifest.schema.json +36 -0
  4. package/docs/configuration.md +27 -7
  5. package/docs/design/2026-11-19-sandboxes.md +595 -121
  6. package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +257 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +186 -3
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +5 -1
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge-capability-authoring.md +1 -1
  15. package/docs/knowledge-reference/proposal.md +10 -0
  16. package/docs/knowledge.md +20 -11
  17. package/docs/official-catalog.md +2 -2
  18. package/docs/packages.md +7 -7
  19. package/docs/release-notes/v0.69.24.md +264 -0
  20. package/docs/souls-and-instances.md +45 -0
  21. package/docs/tui.md +21 -1
  22. package/docs/upgrading.md +12 -5
  23. package/docs/workspaces.md +13 -5
  24. package/lib/capability-show.mjs +11 -1
  25. package/lib/command-flags.mjs +2 -2
  26. package/lib/compile-cache.mjs +1 -1
  27. package/lib/core.mjs +1176 -181
  28. package/lib/errors.mjs +4 -1
  29. package/lib/hook-env.mjs +106 -0
  30. package/lib/host-run.mjs +11 -3
  31. package/lib/instance-inspect.mjs +44 -0
  32. package/lib/instance-lifecycle.mjs +15 -3
  33. package/lib/instance-listing.mjs +97 -8
  34. package/lib/kernel-features.mjs +10 -1
  35. package/lib/node-version.mjs +9 -0
  36. package/lib/provider-call-child.mjs +60 -0
  37. package/lib/provider-resume.mjs +83 -0
  38. package/lib/provider-test-seams.mjs +20 -0
  39. package/lib/read-call.mjs +2 -0
  40. package/lib/reserved-launch-env.mjs +8 -1
  41. package/lib/retire-admission.mjs +5 -1
  42. package/lib/schedule.mjs +14 -4
  43. package/lib/servers.mjs +28 -4
  44. package/lib/session-inspect.mjs +104 -13
  45. package/lib/session-providers.mjs +528 -0
  46. package/lib/session-resume.mjs +68 -15
  47. package/lib/stable-node.mjs +3 -0
  48. package/lib/triggers.mjs +3 -1
  49. package/package-catalog.json +2 -2
  50. package/package.json +2 -1
  51. package/packages/client/capability-list.mjs +21 -0
  52. package/packages/client/cli-adapter.mjs +19 -4
  53. package/packages/client/cli-locator.mjs +5 -1
  54. package/packages/client/deployment-data.mjs +23 -1
  55. package/packages/client/deployment-panel.mjs +25 -3
  56. package/packages/client/home-board.mjs +33 -19
  57. package/packages/client/inspect-boundary.mjs +18 -8
  58. package/packages/client/instance-acts.mjs +30 -3
  59. package/packages/client/instance-board.mjs +206 -0
  60. package/packages/client/instance-presentation.mjs +55 -0
  61. package/packages/client/liveness.mjs +15 -4
  62. package/packages/client/own-codes.mjs +5 -1
  63. package/packages/client/remote-roster.mjs +6 -1
  64. package/packages/client/session-backends.mjs +31 -0
  65. package/packages/client/session-start.mjs +18 -6
  66. package/packages/client/spawn-apply-cli.mjs +5 -3
  67. package/packages/client/spawn-apply-contract.mjs +25 -2
  68. package/packages/client/spawn-apply.mjs +5 -1
  69. package/packages/client/spawn-messages.mjs +3 -0
  70. package/packages/client/terminal-contract.mjs +4 -0
  71. package/packages/client/waiting-on-you.mjs +12 -2
  72. package/packages/tui/lib/model.mjs +14 -3
  73. package/packages/tui/lib/store.mjs +12 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -173,18 +173,41 @@ const errors = {
173
173
  E_INTERRUPTED: 'The spawn was interrupted while its worktree hooks ran.',
174
174
  E_REQUIRED_HOOK_FAILED: 'A required worktree hook failed.',
175
175
  E_HOOK_ENVIRONMENT_CONTRACT: 'A worktree hook broke the hook environment contract.',
176
+ // Feature sandboxes (D-S1-4): a spawn into a sandbox is bound and keyed by the kernel itself, never by a
177
+ // confirmed apply. Shown only when the kernel's own message cannot travel.
178
+ E_SANDBOX_PLACEMENT: 'This soul runs in a sandbox, which a confirmed spawn cannot reach. Spawn it with `oats spawn <soul>` (OATS binds it to the sandbox itself) or from a schedule.',
176
179
  };
180
+ /** Refusals whose kernel message and `details: {reason, remedy}` travel: the kernel says why and what a
181
+ * person does next (feature sandboxes, E_SANDBOX_PLACEMENT). Nothing else of their details is kept. */
182
+ export const KERNEL_WORDED_CODES = ['E_SANDBOX_PLACEMENT'];
183
+ const MESSAGE_MAX = 2048, REMEDY_MAX = 1024;
184
+ const REASON = /^[a-z][a-z0-9-]{0,63}$/;
185
+ // As previewFailure bounds a kernel message: at most `max` characters, no control character but a
186
+ // newline, no credential-shaped text.
187
+ const boundedText = (v, max) => typeof v === 'string' && !!v.trim() && v.length <= max && !v.includes('\0')
188
+ && !/[\x00-\x09\x0b-\x1f\x7f]|https?:\/\/[^/\s]*@|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}/.test(v);
189
+ /** A kernel-worded refusal's details as they travel: `reason` (a slug) and `remedy` (bounded text), each
190
+ * only when valid; null when neither is. */
191
+ export function kernelWordedDetails(details) {
192
+ if (!record(details)) return null;
193
+ const out = {
194
+ ...(typeof details.reason === 'string' && REASON.test(details.reason) ? { reason: details.reason } : {}),
195
+ ...(boundedText(details.remedy, REMEDY_MAX) ? { remedy: details.remedy } : {}),
196
+ };
197
+ return Object.keys(out).length ? out : null;
198
+ }
177
199
  /** Feature worktree-event: a dispatched spawn failure with one of these codes and no
178
200
  * `details.unconfirmed: true` was rolled back by the kernel (confirmed compensation): nothing
179
201
  * was created. With the marker its cleanup is owed. Only these three; every other code keeps
180
202
  * the unknown-unless-proven rule. */
181
203
  export const ROLLED_BACK_CODES = ['E_INTERRUPTED', 'E_REQUIRED_HOOK_FAILED', 'E_HOOK_ENVIRONMENT_CONTRACT'];
182
- /** The kernel's message travels only for ROLLED_BACK_CODES (it names the capability and its log);
183
- * bounded here, and shown through displayLine. */
204
+ /** The kernel's message travels for ROLLED_BACK_CODES (it names the capability and its log) and
205
+ * KERNEL_WORDED_CODES; bounded here, and shown through displayLine. */
184
206
  const kernelText = v => typeof v === 'string' && !!v.trim() && v.length <= 4096 && !v.includes('\0');
185
207
  export function spawnApplyReason(code, kernelMessage) {
186
208
  if (typeof code !== 'string') code = 'E_CLI_FAILED';
187
209
  if (ROLLED_BACK_CODES.includes(code)) return { code, message: kernelText(kernelMessage) ? kernelMessage : errors[code] };
210
+ if (KERNEL_WORDED_CODES.includes(code)) return { code, message: boundedText(kernelMessage, MESSAGE_MAX) ? kernelMessage : errors[code] };
188
211
  if (Object.hasOwn(errors, code)) return { code, message: errors[code] };
189
212
  const reason = previewFailure(code).reason;
190
213
  return reason.code === code && code !== 'E_CLI_FAILED' ? reason : { code: 'E_CLI_FAILED', message: errors.E_CLI_FAILED };
@@ -15,7 +15,7 @@ import { cliSpawnApply } from './spawn-apply-cli.mjs';
15
15
  import { admitSpawnSelection, PREVIEW_MAX_AGE_S } from './spawn-preview.mjs';
16
16
  import { record } from './spawn-preview-contract.mjs';
17
17
  import { spawnApplySupported, spawnApplyChoicesSupported, spawnPrepareInput, spawnRefInput, spawnPreparedData, spawnReference,
18
- spawnCreationReceipt, spawnApplyFailure, spawnApplyDeadlineMs, ROLLED_BACK_CODES, WAKE_OUTCOME_UNKNOWN } from './spawn-apply-contract.mjs';
18
+ spawnCreationReceipt, spawnApplyFailure, spawnApplyDeadlineMs, ROLLED_BACK_CODES, KERNEL_WORDED_CODES, WAKE_OUTCOME_UNKNOWN } from './spawn-apply-contract.mjs';
19
19
  /** The apply request answers within this; the proxy's own 65 s timeout then never fires on a healthy spawn. */
20
20
  export const ANSWER_WITHIN_MS = 50000;
21
21
  export const MAX_APPLIES = 4;
@@ -145,6 +145,10 @@ export function createSpawnApplyBoundary({ read, invoke = cliSpawnApply, exec, a
145
145
  if (envelope.error.details?.unconfirmed === true) { entry.final = true; return denied(code, entry, 'unknown', message); }
146
146
  return denied(code, entry, 'refused', message);
147
147
  }
148
+ // Feature sandboxes (D-S1-4): a spawn into a sandbox is refused before anything is minted, kept or
149
+ // created (docs/desktop-cli-api.md, Sandbox refusals): refused, in the kernel's words, which end with
150
+ // what a person does next.
151
+ if (KERNEL_WORDED_CODES.includes(code)) return denied(code, entry, 'refused', envelope.error.message);
148
152
  // A taken explicit name (spawn-name) refuses before any home is kept: the
149
153
  // confirmation is consumed and a fresh preview reports the taken name.
150
154
  if (['E_DECISION_STALE', 'E_IDEMPOTENCY_CONFLICT', 'E_PLACEMENT_TAKEN', 'E_INSTANCE_NAME_TAKEN'].includes(code)) return denied(code, entry, 'stale');
@@ -89,6 +89,9 @@ const SPAWN_FACTS = {
89
89
  E_CLI_OUTPUT_LIMIT: said('OATS couldn’t confirm the spawn.', 'check-result'),
90
90
  E_CLI_PROTOCOL: said('OATS couldn’t complete the spawn.', 'details'),
91
91
  E_CLI_FAILED: said('OATS couldn’t complete the spawn.', 'details'),
92
+ // Feature sandboxes (D-S1-4): the kernel binds a spawn into a sandbox itself; its own remedy is the detail
93
+ // (`details`: a client shows it). Trying again cannot work: a client's words for this next say so per code.
94
+ E_SANDBOX_PLACEMENT: said('This soul runs in a sandbox, which a confirmed spawn can’t reach yet. Nothing was created. Spawn it with oats spawn in a terminal, or from a schedule.', 'details'),
92
95
  // Wherever nothing is above the sentence and Details hold no kernel text: the whole of it is shared.
93
96
  [UNMATCHED]: said('This machine’s launch preferences name a soul this workspace doesn’t offer, so OATS won’t choose a launch for this soul. To spawn now, pick a harness or a launch configuration for this spawn. To fix it for every spawn, correct the preference.'),
94
97
  };
@@ -37,6 +37,10 @@ const messages = {
37
37
  E_TERM_ATTACHMENT_FAILED: 'Could not prepare these attachments.',
38
38
  E_TERM_ATTACHMENT_INTERRUPTED: 'Attachment interrupted; some file copies may already exist. No input was inserted.',
39
39
  E_TERM_INPUT_LIMIT: 'Terminal input exceeds the safe write limit. Nothing was sent.',
40
+ // An answer (the agent view) refused because the terminal is in tmux's scrollback (copy mode): nothing was typed.
41
+ E_TERM_IN_MODE: 'The terminal is in its scrollback. Nothing was typed.',
42
+ // An answer refused because the pane's mode could not be read (or there is no local pane to read): nothing was typed.
43
+ E_TERM_MODE_UNKNOWN: 'The terminal could not be checked for its scrollback. Nothing was typed.',
40
44
  E_TERM_TRANSPORT: 'The terminal service did not confirm the operation.',
41
45
  E_HERDR_REMOVED: HERDR_REMOVED,
42
46
  E_TERM_REMOTE_UNREACHABLE: serverMessages.E_TERM_REMOTE_UNREACHABLE('the server'),
@@ -7,6 +7,7 @@
7
7
  import { record } from './readiness-contract.mjs';
8
8
  import { eventsTimestamp, eventsId, eventsUnsafe, EVENTS_WITHHELD } from './instance-events-contract.mjs';
9
9
  import { NOT_NOTE_TEXT } from './display-text.mjs';
10
+ import { sessionProvider } from './instance-presentation.mjs';
10
11
 
11
12
  /** A claim's note: a non-empty string of at most 200 code points (not UTF-16 units: 101 emoji is a valid
12
13
  * note), with none of NOT_NOTE_TEXT (the set's one definition is in display-text.mjs); unsafe text is
@@ -36,9 +37,18 @@ export function waitingOnYouData(v) {
36
37
  * or a row the roster holds stale (`stale`: its last re-read failed), carries a last-known claim, which is
37
38
  * unknown. A null or absent `runtimeState` is "not reported", never "not running" (#582): the kernel's
38
39
  * remote roster sends null on every row, so a remote row is gated on the `running` its host reported; a
39
- * local row always carries the concrete state Desktop liveness observed. */
40
+ * local row always carries the concrete state Desktop liveness observed.
41
+ *
42
+ * A row on a session provider (instance-presentation.mjs `sessionProvider`: "bb", say) has another liveness
43
+ * gate, under the same two rules of currency: it shows the claim the kernel's row carries unless the row is
44
+ * stopped (`running === false`). Its `runtimeState` is never "running" (a provider's states are `unknown`,
45
+ * `shell`, `stopped`, `unreachable`), and an agent that waits on a person is idle there, which the kernel
46
+ * reports as `running: null`: the kernel is such a row's only reader, and it decides whether the row carries
47
+ * a claim at all. A home OATS stopped reads `running: false` and shows none. */
40
48
  export function waitingClaim(row, { stale = false } = {}) {
41
- if (stale || !record(row) || row.running !== true || row.serverUnreached === true) return null;
49
+ if (stale || !record(row) || row.serverUnreached === true) return null;
50
+ if (sessionProvider(row)) return row.running === false ? null : waitingOnYouData(row.waitingOnYou);
51
+ if (row.running !== true) return null;
42
52
  if (row.runtimeState != null && row.runtimeState !== 'running') return null;
43
53
  return waitingOnYouData(row.waitingOnYou);
44
54
  }
@@ -108,7 +108,11 @@ export function reachedMachines(state, at) {
108
108
  * that was not reached (the shared home marks it) still carries the word of its last report,
109
109
  * which is not its state now: it gets the shared word, so nothing reads as stopped, or as
110
110
  * running, that is only not reached. */
111
- const stateWord = (row) => (text(row.runtimeState) && row.serverUnreached !== true ? row.runtimeState : runtimeState(row));
111
+ const stateWord = (row) => (text(row.runtimeState) && row.serverUnreached !== true && !providerKnown(row) ? row.runtimeState : runtimeState(row));
112
+ /** A row on a session provider (the shared openAct's `no-terminal`) whose `running` the kernel answered: its
113
+ * `runtimeState` is the provider's word (`unknown` while it runs), which would contradict its mark, so its
114
+ * state is the shared word for its `running`. One the kernel answered `running: null` keeps the kernel's word. */
115
+ const providerKnown = (row) => typeof row.running === "boolean" && openAct(row)?.reason?.code === "no-terminal";
112
116
  /** The word a list row shows beside its name, or null: only what its mark cannot say. That is a
113
117
  * held home's state (Retiring… while a retire runs, or this run's own is in flight), else the
114
118
  * shared label of the reason the row can't be reached or opened (remote-address.mjs rowReason:
@@ -528,7 +532,8 @@ const elsewhere = (row) => typeof row.server === "string" && row.server !== "";
528
532
  * for a row of another machine (its preflight runs first)
529
533
  * { open: false, said: { said, under } } opens nothing, and this says why
530
534
  * Whether a row can be opened is the shared openAct's, switched on its reason's code, never on a
531
- * sentence. The viewer is started with no key of its own (the TUI takes the back key before the
535
+ * sentence. A row on a session provider is never opened, from the list, the palette, the steps or a
536
+ * workspace's remembered tabs (they all ask here); its reason's link is printed under its sentence. The viewer is started with no key of its own (the TUI takes the back key before the
532
537
  * pane sees it), so a kernel or a host of any version is opened alike. */
533
538
  export function openDecision(state, row, acts) {
534
539
  const name = row.instance, id = instanceId(row);
@@ -542,7 +547,13 @@ export function openDecision(state, row, acts) {
542
547
  if (!act.enabled) {
543
548
  if (act.reason.code === "not-running") return no(OPEN_WORDS.notRunning(name));
544
549
  if (act.reason.code === "state-unknown") return no(OPEN_WORDS.stateUnknown(name));
545
- return no([], outside(reasonSpoken(act.reason)));
550
+ // A row on a session provider (code `no-terminal`) has no terminal: the shared home's sentence says where
551
+ // the agent runs, and under it the link the provider offers (its label and its url, one text from outside),
552
+ // for the person to open themselves. The link carries no mark of who made it, and the TUI names no speaker
553
+ // of its own (test/tui-boundary.test.mjs): it stands in quotation marks, as any text nobody vouches for.
554
+ // Nothing is attached or started.
555
+ const link = act.reason.link ? spoken(`${act.reason.link.label}: ${act.reason.link.url}`, undefined, false) : null;
556
+ return no([], [...outside(reasonSpoken(act.reason)), ...outside(link)]);
546
557
  }
547
558
  if (!elsewhere(row)) return { open: true, id, name, machine, target: { home: row.home }, routed: false };
548
559
  return { open: true, id, name, machine, target: { serverId: row.server, instance: row.instance, home: row.home }, routed: true };
@@ -10,7 +10,7 @@
10
10
  // Selection is an identity (the shared `instanceId`), never an index, so it survives every read;
11
11
  // the rows it moves among are the model's, in drawn order.
12
12
  import { ACTIONS, LEADER_KEYS, backKeyLabel, bindings, chordKeys, chordsRead, paletteKeys } from "./actions.mjs";
13
- import { CHORDS, chordFamilyFrom, collapseKey, workspaceStep, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
13
+ import { CHORDS, chordFamilyFrom, collapseKey, workspaceStep, displayLine, instanceActs, instanceId, openAct, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
14
14
  import { defaultDetachKey } from "./config.mjs";
15
15
  import { BACKGROUND_ID, backgroundOpen, BUTTON_ORDER, PIN_WORDS, pinDecision, pinLine, SPAWN_WORDS, LEADER_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, paletteStep, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, switcherWindow, memoryKey, memoryKeys, LIST_WORDS, WORKSPACE_WORDS, listChoice, listChoices, workspaceList } from "./model.mjs";
16
16
  import { backKeyId, backKeySequences, isBackKey } from "./term/through.mjs";
@@ -1120,12 +1120,21 @@ const TAB_PICKS = Object.freeze({
1120
1120
 
1121
1121
  /** The preflight of another machine's agent ended. Given up meanwhile (Esc, a suspend, a second
1122
1122
  * open): dropped. Failed: the line that says so, unless it is the person's own giving up. Else
1123
- * the viewer is started in the panel, unless the row it is for has gone from the roster since. */
1123
+ * the viewer is started in the panel, unless the row it is for has gone from the roster since, or
1124
+ * runs on a session provider now: the roster may have brought, while the preflight ran, the row of a
1125
+ * home that moved to one, which has no terminal (the shared open decision, asked again of the row as
1126
+ * it is now). Then nothing starts: the line says where it runs, as Enter on that row would, and a
1127
+ * restore says nothing, as for any tab it drops. A row that runs in tmux is started as before. */
1124
1128
  function prepared(state, { id, error }) {
1125
1129
  const opening = state.opening;
1126
1130
  if (opening === null || opening.id !== id || opening.phase !== "preflight") return { state, effect: null };
1127
1131
  if (error !== undefined) return { state: next(state, { opening: null, outcome: preflightLine(opening, error) }), effect: null };
1128
- if (!roster(state).instances.some((row) => instanceId(row) === id)) return { state: next(state, { opening: null }), effect: null };
1132
+ const row = roster(state).instances.find((each) => instanceId(each) === id) ?? null;
1133
+ if (row === null) return { state: next(state, { opening: null }), effect: null };
1134
+ if (openAct(row)?.reason?.code === "no-terminal") {
1135
+ const decision = openDecision(state, row, instanceActs(row));
1136
+ return { state: next(state, { opening: null, ...(opening.restore ? {} : { outcome: decision.said }) }), effect: null };
1137
+ }
1129
1138
  return { state: (opening.restore ? restoredTab : tabOpened)(next(state, { opening: null }), opening), effect: { panel: id } };
1130
1139
  }
1131
1140
 
@@ -562,7 +562,7 @@ installed CLI's catalog:
562
562
  node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
563
563
  ```
564
564
 
565
- It prints the two refs, for example `oats-framework/v1.27.0 v1.46.0`. If the
565
+ It prints the two refs, for example `oats-framework/v1.28.0 v1.47.0`. If the
566
566
  framework's version (after the `/`) is below `1.19.0`, or with aweb
567
567
  `oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
568
568
  skill: stop, and tell the person to wait for the next OATS
@@ -856,8 +856,8 @@ name: acme
856
856
  members:
857
857
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
858
858
  packages:
859
- oats.framework: v1.27.0 # the installed CLI's catalog versions (below)
860
- oats.aweb: v1.46.0 # messaging: agent identities, mail and chat
859
+ oats.framework: v1.28.0 # the installed CLI's catalog versions (below)
860
+ oats.aweb: v1.47.0 # messaging: agent identities, mail and chat
861
861
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
862
862
  defaults:
863
863
  capabilities: