@awebai/oats 0.43.2 → 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 +22 -11
- package/docs/capabilities.md +30 -0
- package/docs/knowledge.md +2 -1
- package/docs/release-notes/v0.43.3.md +22 -0
- package/lib/core.mjs +1 -1
- package/package.json +1 -1
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
|
-
|
|
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
|
-
|
|
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
|
|
3222
|
-
// dispatch) the soul read at its resolved commit, whose temporary copy goes when this
|
|
3223
|
-
|
|
3224
|
-
|
|
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
|
|
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}`);
|
package/docs/capabilities.md
CHANGED
|
@@ -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/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,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.
|
|
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",
|