@awebai/oats 0.43.1 → 0.43.3

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/bin/oats.mjs CHANGED
@@ -30,7 +30,7 @@ import {
30
30
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
31
31
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
32
32
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
33
- findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
33
+ findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
34
34
  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
35
35
  } from "../lib/core.mjs";
36
36
  import {
@@ -3094,10 +3094,13 @@ async function capabilityCommand() {
3094
3094
  // as a spawn preview reads it (the per-commit copy a spawn left under the agents root, else a
3095
3095
  // temporary fetch removed when the command ends). Read only when the command runs (after its
3096
3096
  // --help). A soul that cannot be read refuses the command: it never runs with OATS_SOUL unset.
3097
+ // Its name and stable id are the ones a spawn of it records and hands its hooks (OATS_AGENT,
3098
+ // OATS_SOUL_ID): the agents-root name and the prepared entry's id, never the copy's path.
3097
3099
  const soul = async () => {
3098
- const { previewWorkspaceSoul } = await import("../lib/instance-resolution.mjs");
3100
+ const { previewWorkspaceSoul, agentDirOf } = await import("../lib/instance-resolution.mjs");
3099
3101
  const entry = hit.prepared?.soulEntry;
3100
- try { const p = await previewWorkspaceSoul(hit.prepared, join(hit.deployment, "agents")); return { dir: p.soulDir, cleanup: p.cleanup }; }
3102
+ const identity = entry ? { agent: agentDirOf(entry), id: preparedSoulIdOf(entry) } : {};
3103
+ try { const p = await previewWorkspaceSoul(hit.prepared, join(hit.deployment, "agents")); return { dir: p.soulDir, cleanup: p.cleanup, ...identity }; }
3101
3104
  catch (e) {
3102
3105
  throw Object.assign(new Error(`oats ${cmd}: cannot read soul ${flag("soul")} at ${String(entry?.commit ?? "?").slice(0, 12)}, so the command would run without OATS_SOUL; nothing was run: ${e.message}`),
3103
3106
  { code: typeof e?.code === "string" && e.code.startsWith("E_") ? e.code : "E_REMOTE_UNREADABLE", details: { soul: flag("soul"), repoKey: entry?.repoKey ?? null, commit: entry?.commit ?? null } });
@@ -3177,7 +3180,10 @@ async function capabilityCommand() {
3177
3180
  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
3178
3181
  teamCtx = homeTeamCtx(live);
3179
3182
  }
3180
- return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir, () => ({ dir: soulDir, cleanup: () => {} }));
3183
+ // The home's soul as its lifecycle hooks get it: the recorded name and stableSoulId's id.
3184
+ const agent = homeMeta.meta.agent;
3185
+ return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir,
3186
+ () => ({ dir: soulDir, cleanup: () => {}, agent, id: stableSoulId({ home: instanceHome, soulDir, agentName: agent }) }));
3181
3187
  }
3182
3188
 
3183
3189
  /** Help / unknown-command / spec validation / exec — shared by every context.
@@ -3218,14 +3224,15 @@ async function capabilityCommand() {
3218
3224
  try { abs = capabilityExecutablePath(withDir, script); }
3219
3225
  catch (e) { bail("E_CAPABILITY_BROKEN", e.message); }
3220
3226
  if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(dir, script)})`);
3221
- // The soul the command acts for → { dir, cleanup }: a home's recorded soul directory, or (operator
3222
- // dispatch) the soul read at its resolved commit, whose temporary copy goes when this process exits.
3223
- let soulDir;
3224
- try { const read = await soul(); soulDir = read.dir; process.once("exit", read.cleanup); }
3227
+ // The soul the command acts for → { dir, cleanup, agent, id }: a home's recorded soul directory, or
3228
+ // (operator dispatch) the soul read at its resolved commit, whose temporary copy goes when this
3229
+ // process exits; with its name and stable id, as the soul's lifecycle hooks get them.
3230
+ let soulDir, soulAgent, soulId;
3231
+ try { const read = await soul(); soulDir = read.dir; soulAgent = read.agent; soulId = read.id; process.once("exit", read.cleanup); }
3225
3232
  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) bail(e.code, e.message, e.details); throw e; }
3226
- // OATS_SOUL is the recorded soul or nothing: an ambient value inherited from the
3227
- // invoking process names some other soul (a coordinator's own), never this one.
3228
- const { OATS_SOUL: _ambientSoul, ...inherited } = process.env;
3233
+ // OATS_SOUL, OATS_AGENT and OATS_SOUL_ID are this command's soul or nothing: an ambient value
3234
+ // inherited from the invoking process names some other soul (a coordinator's own), never this one.
3235
+ const { OATS_SOUL: _ambientSoul, OATS_AGENT: _ambientAgent, OATS_SOUL_ID: _ambientSoulId, ...inherited } = process.env;
3229
3236
  await readSession?.closeBatches(); // no idle `git cat-file --batch` child held for the provider's whole run
3230
3237
  const r = spawnSync("node", [abs, ...rest, ...rawArgs.slice(2)], { stdio: "inherit", env: {
3231
3238
  ...inherited, OATS_CAPABILITY: m.capability,
@@ -3245,6 +3252,10 @@ async function capabilityCommand() {
3245
3252
  // The soul the command acts for (an instance home's recorded soul directory):
3246
3253
  // homes carry no soul link, so providers read it here.
3247
3254
  ...(soulDir ? { OATS_SOUL: soulDir } : {}),
3255
+ // Its name and stable identity, the values its hooks get: what a provider keys durable state
3256
+ // on (OATS_SOUL is a per-commit or temporary copy, so never a key).
3257
+ ...(typeof soulAgent === "string" && soulAgent ? { OATS_AGENT: soulAgent } : {}),
3258
+ ...(typeof soulId === "string" && soulId ? { OATS_SOUL_ID: soulId } : {}),
3248
3259
  } });
3249
3260
  // Child never ran (spawn error): nothing reached stdout — keep the envelope contract.
3250
3261
  if (r.error) bail("E_CAPABILITY_BROKEN", `oats ${cmd} ${sub}: ${r.error.message || r.error}`);
@@ -443,6 +443,36 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
443
443
  preview (only a preview-aware hook does, below); on a real run
444
444
  `OATS_LAUNCH_PREVIEW` is not set.
445
445
 
446
+ A dispatched command (`oats <namespace> <command>`, from an instance home or
447
+ from the deployment directory) receives:
448
+
449
+ - `OATS_CAPABILITY`;
450
+ - `OATS_CLI_BIN`;
451
+ - `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`: the home's recorded payload, or
452
+ the soul's merged payload from the deployment;
453
+ - the team and workspace variables, as hooks get them;
454
+ - `OATS_SOUL`: the home's recorded soul directory, or from the deployment the
455
+ soul's source at the resolved commit (the copy a spawn left under the
456
+ agents root, else a temporary copy removed when the command ends). It is a
457
+ per-commit or temporary path, so a provider never keys durable state on it;
458
+ - `OATS_AGENT` and `OATS_SOUL_ID` (0.43.3), with the values that soul's
459
+ hooks get: the soul's agents-root name (`<package>--<soul>` for a package
460
+ soul, see [Package souls](packages.md#package-souls)) and its stable id
461
+ (`<repoKey>#<soul>`, or `package:<id>#<soul>`; for a home, the id its
462
+ spawn recorded). One soul gives the same values from its home, from the
463
+ deployment (with `--soul` or as the default soul) and in its hooks. Key
464
+ durable per-soul state on `OATS_SOUL_ID`. A provider that relies on them
465
+ declares `compatibility.oats: ">=0.43.3"`: an earlier kernel sets
466
+ neither, so a value a command sees there is the caller's.
467
+
468
+ An `OATS_SOUL`, `OATS_AGENT` or `OATS_SOUL_ID` in the caller's environment is
469
+ removed: it names another soul (a coordinator's, an outer command's). With
470
+ no soul, the variable is absent. The kernel sets no other hook variable
471
+ (`OATS_EVENT`, `OATS_LAYER`, `OATS_LEVEL`, `OATS_CONTEXT`, `OATS_WORKSPACE`,
472
+ `OATS_ROOT`, `OATS_META`, the spawn and launch extras). `OATS_INSTANCE`,
473
+ `OATS_INSTANCE_HOME` and `OATS_HOME` are neither set nor removed: inside an
474
+ instance session they are the session's.
475
+
446
476
  `OATS_SETTINGS_ORIGINS` says where each leaf of
447
477
  `OATS_SETTINGS` came from: a JSON object from a JSON pointer to `{ kind, at }`,
448
478
  `kind` being `manifest-default`, `workspace`, `soul`, `host`, `spawn` or
package/docs/desktop.md CHANGED
@@ -302,8 +302,8 @@ Drag over an agent's output to select it, as in any terminal. The selection
302
302
  stays after you release the mouse. Double-click selects a word, triple-click a
303
303
  line. Nothing is copied yet: copy it with ⌘C or Edit › Copy (macOS),
304
304
  **Ctrl+Shift+C** (Linux and Windows), or right-click › Copy (every platform).
305
- With nothing selected, Ctrl+Shift+C does nothing, and Ctrl+C still interrupts
306
- the program in the pane. Copies trim trailing spaces at line ends, as native
305
+ With nothing selected, Ctrl+Shift+C, ⌘C and Edit › Copy do nothing and leave
306
+ the clipboard as it was, and Ctrl+C still interrupts the program in the pane. Copies trim trailing spaces at line ends, as native
307
307
  terminals do.
308
308
 
309
309
  A drag selects what is on the screen. To select older output, wheel up first
package/docs/knowledge.md CHANGED
@@ -227,7 +227,8 @@ identical copies in both role capabilities.
227
227
  `--soul` naming another soul is refused (`E_HOME_MISMATCH`). The kernel resolves the
228
228
  soul as a spawn would, fetches its module at the locked commit into
229
229
  `<deployment>/.oats/modules/` and runs it with the soul's merged settings
230
- and `OATS_SOUL`, the soul's source at that commit.
230
+ and `OATS_SOUL`, the soul's source at that commit, with the soul's
231
+ `OATS_AGENT` and `OATS_SOUL_ID` as its hooks get them.
231
232
  An unlocked package is `E_PACKAGE_MISSING` until `oats sync`.
232
233
 
233
234
  ### Consult
@@ -0,0 +1,9 @@
1
+ # OATS 0.43.2
2
+
3
+ ## Fixed
4
+
5
+ - In a terminal tab, ⌘C or Edit › Copy with nothing selected no longer
6
+ copies an earlier selection: the clipboard is left as it was
7
+ ([#695](https://github.com/awebai/oats/issues/695)). A copy from the tab's
8
+ banner or from an input in it is no longer replaced by the terminal's
9
+ selection.
@@ -0,0 +1,22 @@
1
+ # OATS 0.43.3
2
+
3
+ ## Added
4
+
5
+ - A dispatched capability command (`oats <namespace> <command>`) now gets
6
+ `OATS_AGENT` and `OATS_SOUL_ID`, with the values its soul's lifecycle hooks
7
+ get: the soul's agents-root name and its stable id (`<repoKey>#<soul>`, or
8
+ `package:<id>#<soul>`). The same soul gives the same values from an
9
+ instance home, from the deployment with `--soul` or as the default soul,
10
+ and in its hooks
11
+ ([#688](https://github.com/awebai/oats/issues/688)). From the deployment,
12
+ `OATS_SOUL` is a per-commit or temporary copy of the soul, so a provider
13
+ keys durable state on `OATS_SOUL_ID` instead: `oats okf harvest` needs this
14
+ to keep its owner across runs
15
+ ([oats-okf#54](https://github.com/awebai/oats-okf/issues/54)).
16
+ See [Commands and hooks](../capabilities.md#commands-and-hooks).
17
+
18
+ ## Changed
19
+
20
+ - An `OATS_AGENT` or `OATS_SOUL_ID` in the caller's environment no longer
21
+ reaches a dispatched command, as an ambient `OATS_SOUL` already did not: it
22
+ named another soul.
package/lib/core.mjs CHANGED
@@ -1547,7 +1547,7 @@ export const workspaceSoulId = (repoKey, name) => `${repoKey}#${name}`;
1547
1547
  export const TRIGGER_EVENT_FILE = "trigger-event.json";
1548
1548
  /** A prepared soul entry's id: `<repoKey>#<name>` for a member or external soul, `package:<id>#<name>`
1549
1549
  * for a package soul (stable across the package's versions and independent of its repo). */
1550
- const preparedSoulIdOf = (entry) => workspaceSoulId(typeof entry.package === "string" ? `package:${entry.package}` : entry.repoKey, entry.name);
1550
+ export const preparedSoulIdOf = (entry) => workspaceSoulId(typeof entry.package === "string" ? `package:${entry.package}` : entry.repoKey, entry.name);
1551
1551
  /** The soul directory an instance incarnates, as spawn recorded it (instance.json
1552
1552
  * `soulDir`): a workspace soul's per-commit copy (agents/<soul>/souls/<commit12>) or
1553
1553
  * the read-only soul inside a capability package. It is what every classic
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.43.1",
3
+ "version": "0.43.3",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",