@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
@@ -13,14 +13,15 @@
13
13
  import { spawnSync } from "node:child_process";
14
14
  import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
15
15
  import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
16
- import { fileURLToPath } from "node:url";
17
- import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
18
- import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests } from "./instance-resolution.mjs";
16
+ import { capabilityManifests, kernelBin, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
17
+ import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests, soulsOffered } from "./instance-resolution.mjs";
19
18
  import { declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
20
19
  import { kernelCompatibility } from "./resolve.mjs";
21
20
  import { discoveredTeamKeys, isRemovedTeamKeys, isTeamRefusal, recordedTeams, reportRows, soulKeyOf, teamKeyOf, soulTeams, teamModel, teamProblems } from "./teams.mjs";
22
21
  import { launchLayers, launchReport } from "./launch-preference.mjs";
23
22
  import { loadLocal } from "./workspace.mjs";
23
+ import { CLAUDE_SESSION_HINT } from "./launch-prompt-fixtures.mjs";
24
+ import { neverSettled } from "./launch-prompts.mjs";
24
25
  import { ensureModuleTree } from "./operator-dispatch.mjs";
25
26
  import { operatorCoverage, operatorProblems } from "./operator-coverage.mjs";
26
27
  import { readLockIfPresent } from "./packages.mjs";
@@ -28,12 +29,12 @@ import { composeSoulInstructions } from "./soul-composition.mjs";
28
29
  /** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
29
30
  const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
30
31
  import { parseStrictJson } from "./canonical-json.mjs";
32
+ import { kernelNode } from "./stable-node.mjs";
31
33
 
32
34
  export const INSPECT_OPERATIONS_API = 2;
33
35
  export const SOULS_API = 2;
34
36
  export const READINESS_API = 2;
35
37
  const LAYERS = ["knowledge", "messaging", "tasks"];
36
- const CLI_BIN = fileURLToPath(new URL("../bin/oats.mjs", import.meta.url));
37
38
  const obj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
38
39
  const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
39
40
 
@@ -193,7 +194,7 @@ export async function soulTarget(contextDir, soul, { remoteOptions, materialize
193
194
  // Feature launch-preference: what a spawn with no flags would launch here.
194
195
  let launchConfigs = {};
195
196
  try { launchConfigs = launchConfigsAt(deployment); } catch { launchConfigs = {}; }
196
- const launch = launchReportFor({ layers: prepared?.launch ?? launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: soulKeyOf(soulEntry), local: found.local }), launchConfigs, contextDir: deployment });
197
+ const launch = launchReportFor({ layers: prepared?.launch ?? launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: soulKeyOf(soulEntry), local: found.local, offered: soulsOffered(discovery) }), launchConfigs, contextDir: deployment });
197
198
  return {
198
199
  kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch, session: newSessionDefaults(deployment),
199
200
  subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null },
@@ -361,19 +362,46 @@ function launchItems(t) {
361
362
  reason: `this instance runs ${show(a)}; its launch preference now says ${show(b)} (${t.launchCurrent.at ?? t.launchCurrent.from})`,
362
363
  remedy: "`oats session restart --reselect-launch`, or respawn", recorded: a, current: b, from: t.launchCurrent.from, at: t.launchCurrent.at })];
363
364
  }
364
- /** `harness-trust` (#341; a warning): the claude or codex session this subject launches will stop at
365
- * its folder-trust prompt, because the operator has not trusted the deployment. An instance's recorded
366
- * harness and home; a soul's launch here, for a home under the agents root. Reads, never writes, the
367
- * harness's configuration (lib/harness-trust.mjs). */
365
+ /** `harness-trust` (#341, #886): whether the configuration file the claude or codex session this
366
+ * subject launches reads trusts the deployment: a passing item naming that file, or a warning that
367
+ * folder trust is not established there (a missing root entry does not prove a prompt). The file is
368
+ * the launch's own: an instance's recorded harness, home and recorded launch env; a soul's selected
369
+ * launch configuration, for a home under the agents root. Reads, never writes, the harness's
370
+ * configuration (lib/harness-trust.mjs). */
368
371
  function folderTrustItems(t) {
369
372
  const harness = t.home ? t.meta?.harness : t.launch?.effective?.harness;
370
373
  if (harness !== "claude" && harness !== "codex") return [];
371
374
  const meta = t.home ? t.meta : { workspace: { deployment: t.deployment } };
372
- // A soul's yolo is its selected launch configuration's (a host fact, never the soul's).
373
- const config = () => { try { return launchConfigsAt(t.deployment)[t.launch?.effective?.launchConfig]; } catch { return undefined; } };
374
- const yolo = t.home ? (t.meta?.yolo ?? t.meta?.launch?.yolo) : config()?.yolo;
375
- const { warning } = launchFolderTrust({ harness, home: t.home ?? t.agentsRoot, meta, yolo });
376
- return warning ? [item("launch", "fail", { required: false, producer: "harness folder trust", code: "harness-trust", reason: warning, harness, deployment: t.deployment })] : [];
375
+ // A soul's yolo and env are its selected launch configuration's (a host fact, never the soul's).
376
+ const name = t.home ? t.meta?.launch?.launchConfig : t.launch?.effective?.launchConfig;
377
+ const config = t.home ? null : (() => { try { return launchConfigsAt(t.deployment)[name]; } catch { return undefined; } })();
378
+ const yolo = t.home ? (t.meta?.yolo ?? t.meta?.launch?.yolo) : config?.yolo;
379
+ const configEnv = t.home ? t.meta?.launch?.env : config?.env;
380
+ const trust = launchFolderTrust({ harness, home: t.home ?? t.agentsRoot, meta, yolo, configEnv: obj(configEnv) ? configEnv : {}, launchConfig: name });
381
+ return [item("launch", trust.warning ? "fail" : "pass", { required: false, producer: "harness folder trust", code: "harness-trust", reason: trust.warning,
382
+ harness, file: trust.file, deployment: t.deployment })];
383
+ }
384
+ /** `launch-prompt` (a warning): this home's last start blocked at a prompt that equals no
385
+ * development-channel tolerance entry, so the instance waits for a person. It names what
386
+ * differed and both remedies, adds that Claude may have ignored the flag when the blocked
387
+ * screen was Claude's running session, and clears when a later start records anything but
388
+ * `blocked` (`flag-ignored` included). */
389
+ function launchPromptItems(t) {
390
+ const prompts = t.home ? t.meta?.launchPrompts : null;
391
+ if (prompts?.status !== "blocked") return [];
392
+ const d = prompts.differed?.firstDifference;
393
+ const differed = prompts.differed && d ? ` (nearest tolerance entry ${prompts.differed.nearest}, first difference at ${d.index}: expected ${JSON.stringify(d.expected)}, found ${JSON.stringify(d.found)})` : "";
394
+ // A screen that never settled within the bound established no prompt to read and answer.
395
+ const settled = !neverSettled(prompts.reason);
396
+ const enterSent = prompts.answers?.some((a) => a.status === "submitted");
397
+ return [item("launch", "fail", { required: false, producer: "launch prompt", code: "launch-prompt",
398
+ reason: settled ? `the last start of this instance stopped at a prompt OATS does not confirm: ${prompts.reason}${differed}`
399
+ : enterSent ? `the last start of this instance sent one Enter to the development-channel confirmation, then never showed 2 s of a clean session within the 30 s bound: ${prompts.reason}${differed}`
400
+ : `the last start of this instance never settled into a screen OATS recognises within the 30 s bound: ${prompts.reason}${differed}`,
401
+ remedy: `${settled ? "read the prompt in the instance's terminal and press Enter if it is the development-channel confirmation, or add its captured wording as a tolerance entry (lib/launch-prompt-fixtures/dev-channel-confirmation.json) in a reviewed PR"
402
+ : enterSent ? "look at the instance's terminal: OATS sent its one Enter and sends no other key; if Claude's session is running, it started, and a later start clears this"
403
+ : "look at the instance's terminal: OATS established no prompt there and sent no key; if Claude's session is running, restart the instance"}${prompts.claudeSessionShown ? `. ${CLAUDE_SESSION_HINT}` : ""}`,
404
+ ...(prompts.differed ? { differed: prompts.differed } : {}) })];
377
405
  }
378
406
  /** Operator coverage (#671; warnings, never required): whether a soul this workspace offers composes
379
407
  * oats.setup (lib/operator-coverage.mjs), for the workspace and for the subject's own teams, over the
@@ -397,7 +425,7 @@ function roll(items) {
397
425
  return req.length ? "pass" : "not-applicable";
398
426
  }
399
427
  /** A readiness item's free text is at most ITEM_TEXT characters (#725): the Desktop refuses a WHOLE answer
400
- * whose item reason, remedy or problem message is over 1024 (packages/desktop/renderer/readiness-contract.mjs),
428
+ * whose item reason, remedy or problem message is over 1024 (packages/client/readiness-contract.mjs),
401
429
  * and some producers carry remote text (a discovery error). Producers that bound their own text keep it. A
402
430
  * provider's own answer (`result`) is relayed verbatim, never clipped here. */
403
431
  export const ITEM_TEXT = 1000;
@@ -411,7 +439,7 @@ const item = (subject, status, { required = true, reason = null, producer = "ker
411
439
  function providerEnv(t, capability, settings) {
412
440
  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^(OATS_|OAS_|PI_)/.test(k)));
413
441
  Object.assign(env, teamEnv({ workspace: { key: t.workspace.key, name: t.workspace.name, deployment: t.deployment }, teams: t.teams, defaultTeam: t.defaultTeam, teamsSource: t.teamsSource }));
414
- return Object.assign(env, { OATS_CAPABILITY: capability, OATS_SETTINGS: JSON.stringify(settings), OATS_SETTINGS_ORIGINS: JSON.stringify(t.payloadOrigins?.[capability] ?? {}), OATS_CLI_BIN: CLI_BIN, OATS_WORKSPACE: t.deployment,
442
+ return Object.assign(env, { OATS_CAPABILITY: capability, OATS_SETTINGS: JSON.stringify(settings), OATS_SETTINGS_ORIGINS: JSON.stringify(t.payloadOrigins?.[capability] ?? {}), OATS_CLI_BIN: kernelBin(), OATS_NODE_BIN: kernelNode().node, OATS_WORKSPACE: t.deployment,
415
443
  ...(t.home ? { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home } : {}), OATS_AGENT: t.soulIdentity?.agent || t.soul.name, ...(t.soulIdentity?.id ? { OATS_SOUL_ID: t.soulIdentity.id } : {}),
416
444
  ...(t.soul.soulDir ? { OATS_SOUL: t.soul.soulDir } : {}) });
417
445
  }
@@ -563,7 +591,7 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
563
591
  evidence: { command: req.command }, remedy: found ? null : req.install, ...cap(mod.name) }));
564
592
  }
565
593
  }
566
- configured.push(...teamItems(t), ...launchItems(t), ...folderTrustItems(t), ...await operatorItems(t, { remoteOptions }));
594
+ configured.push(...teamItems(t), ...launchItems(t), ...folderTrustItems(t), ...launchPromptItems(t), ...await operatorItems(t, { remoteOptions }));
567
595
  // member — the soul's member repository is a confirmed member of the workspace
568
596
  // (oats-membership.yaml backlink observed over the remotes); a package soul's is its
569
597
  // package instead (packageSoulItem).