@awebai/oats 0.69.9 → 0.69.11
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/README.md +1 -1
- package/bin/oats.mjs +1 -1
- package/docs/capabilities.md +27 -5
- package/docs/capability-manifest.schema.json +8 -0
- package/docs/configuration.md +1 -1
- package/docs/desktop-cli-api.md +3 -1
- package/docs/integrations.md +13 -2
- package/docs/oats-local.schema.json +2 -2
- package/docs/oats-membership.schema.json +1 -1
- package/docs/oats-workspace.schema.json +7 -3
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.10.md +66 -0
- package/docs/release-notes/v0.69.11.md +107 -0
- package/docs/schedules.md +25 -6
- package/docs/souls-and-instances.md +2 -1
- package/docs/upgrading.md +15 -5
- package/docs/workspaces.md +20 -5
- package/lib/instance-resolution.mjs +1 -1
- package/lib/kernel-features.mjs +1 -1
- package/lib/resolve.mjs +51 -8
- package/lib/schedule.mjs +69 -28
- package/lib/workspace.mjs +10 -1
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +684 -385
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.
|
|
57
|
+
oats.framework: v1.21.0 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v5.7.0
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
@@ -78,6 +78,8 @@ stores: # knowledge stores, declared once
|
|
|
78
78
|
|
|
79
79
|
messaging: # an opaque provider payload for the messaging slot
|
|
80
80
|
private: per-human
|
|
81
|
+
tasks: # the same, for whichever capability fills the tasks slot
|
|
82
|
+
team: engineering # (ignored while the slot is empty, as here unless a soul fills it)
|
|
81
83
|
|
|
82
84
|
external: # souls borrowed from NON-members; revision REQUIRED
|
|
83
85
|
- source: git:github.com/oss-collective/experts@9c4e1f2a9c4e1f2a9c4e1f2a9c4e1f2a9c4e1f2a
|
|
@@ -625,10 +627,23 @@ Why it is shaped this way: [team model 3](design/2026-10-02-team-model-3.md).
|
|
|
625
627
|
| A fact about this machine | `oats-local.yaml` → `settings.<cap>.<key>` (absolute paths are refused in the workspace file) | `settings.oats.okf.state-dir: /Users/ana/.oats/okf` |
|
|
626
628
|
| A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` |
|
|
627
629
|
|
|
628
|
-
The merged payload is
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
630
|
+
The merged payload is the manifest's setting defaults ⊕ the workspace's
|
|
631
|
+
`messaging:` (for the messaging-slot capability only) or `tasks:` (for the
|
|
632
|
+
tasks-slot capability only) ⊕ soul slot payload ⊕ `local.settings[cap]` ⊕
|
|
633
|
+
`spawn.providers[cap]` — objects deep-merge, later wins on scalars and arrays.
|
|
634
|
+
There is no workspace `knowledge:` payload. A workspace `tasks:` needs a kernel
|
|
635
|
+
with the feature `workspace-tasks-payload`: an older one refuses the file
|
|
636
|
+
(unknown property). The provider's own `binding` contract (its readiness
|
|
637
|
+
check) runs over the merged payload.
|
|
638
|
+
|
|
639
|
+
A capability's manifest may pin a setting to one of these layers. A key it
|
|
640
|
+
marks `hostOnly` comes only from `oats-local.yaml`; a key it marks
|
|
641
|
+
`committedOnly` never comes from `oats-local.yaml` or `--provider`: it is set
|
|
642
|
+
in the workspace's `messaging:` or `tasks:`, a soul's slot payload, or left at
|
|
643
|
+
the manifest default, so every deployment shares one value. Either one set in
|
|
644
|
+
the wrong layer is refused (`E_WORKSPACE_SCHEMA`, reason `host-only-key` or
|
|
645
|
+
`committed-only-key`), naming the key, where it was set and where it may be set
|
|
646
|
+
([Commands and hooks](capabilities.md#commands-and-hooks)). Teams are **not** settings:
|
|
632
647
|
they reach the provider beside them, in its environment ([Teams](#teams)).
|
|
633
648
|
Where a provider keeps its own state (for oats.aweb, its identity roots) is the
|
|
634
649
|
provider's concern; see its documentation.
|
|
@@ -121,7 +121,7 @@ export function soulCandidates(discovery) {
|
|
|
121
121
|
}
|
|
122
122
|
for (const x of discovery.external || []) {
|
|
123
123
|
if (!x.soul?.name) continue;
|
|
124
|
-
const repoKey = x.soul.repoKey ?? parseRepoRef(x.source.replace(
|
|
124
|
+
const repoKey = x.soul.repoKey ?? parseRepoRef(x.source.replace(/@[0-9a-f]{40}$/, "")).key;
|
|
125
125
|
out.push({
|
|
126
126
|
entry: { ...x.soul, repoKey, commit: x.commit, external: true },
|
|
127
127
|
matches: (name) => { const [repoPart, soulPart] = splitSoulName(name); return x.soul.name === soulPart && (!repoPart || sameRepo(repoKey, repoPart) || (x.source && String(x.source).includes(repoPart))); },
|
package/lib/kernel-features.mjs
CHANGED
|
@@ -5,6 +5,6 @@
|
|
|
5
5
|
* (test/cli-json-contract.test.mjs). Kernel-private, not exported from `./core`. Dependency-free. */
|
|
6
6
|
import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
|
|
7
7
|
|
|
8
|
-
export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution"]);
|
|
8
|
+
export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only"]);
|
|
9
9
|
/** The warm reader's protocol (`oats reader --stdio`, lib/reader.mjs): `readerApi` in the probe and in the reader's hello. */
|
|
10
10
|
export const READER_API = 1;
|
package/lib/resolve.mjs
CHANGED
|
@@ -44,8 +44,10 @@
|
|
|
44
44
|
* everything, while a preview can say WHAT changed since the previous instance (declarations | payload | both).
|
|
45
45
|
*
|
|
46
46
|
* Payloads (decision 14), later wins on scalars/arrays, objects deep-merge:
|
|
47
|
-
* workspace
|
|
47
|
+
* manifest defaults ⊕ workspace.<slot> (messaging and tasks slots only: WORKSPACE_PAYLOAD_SLOTS)
|
|
48
48
|
* ⊕ soul.<slot> ⊕ local.settings[cap] ⊕ spawn.providers[cap]
|
|
49
|
+
* A manifest settings key marked hostOnly comes only from local.settings[cap]; one marked committedOnly
|
|
50
|
+
* never comes from local.settings[cap] or spawn.providers[cap] (#1719).
|
|
49
51
|
*
|
|
50
52
|
* This module shells out to nothing. Remote access is injected (`remote`, default
|
|
51
53
|
* lib/remote.mjs; `remoteOptions` threaded into every call). `resolveSoul` is
|
|
@@ -65,6 +67,8 @@ import { currentRepoKey, sameRepo } from "./repo-moves.mjs";
|
|
|
65
67
|
|
|
66
68
|
export const RESOLUTION_API = 1;
|
|
67
69
|
export const SLOTS = Object.freeze(["knowledge", "messaging", "tasks"]);
|
|
70
|
+
/** The slots whose payload oats-workspace.yaml may carry at its root (`messaging:`, `tasks:` since #1719). */
|
|
71
|
+
const WORKSPACE_PAYLOAD_SLOTS = Object.freeze(["messaging", "tasks"]);
|
|
68
72
|
const CONTRACT_DOC = "docs/design/2026-09-23-workspace-module-contracts.md";
|
|
69
73
|
|
|
70
74
|
/* ───────────────────────────── helpers ────────────────────────────────── */
|
|
@@ -179,6 +183,34 @@ function assertNoHostOnlyKey(value, path, hostOnly, capability) {
|
|
|
179
183
|
}
|
|
180
184
|
}
|
|
181
185
|
|
|
186
|
+
/** Settings keys a manifest marks `committedOnly: true` (#1719): the mirror of hostOnly. */
|
|
187
|
+
export function committedOnlyKeys(manifest) {
|
|
188
|
+
const out = new Set();
|
|
189
|
+
const decl = isObject(manifest?.settings) ? manifest.settings : {};
|
|
190
|
+
for (const [key, spec] of Object.entries(decl)) if (isObject(spec) && spec.committedOnly === true) out.add(key);
|
|
191
|
+
return out;
|
|
192
|
+
}
|
|
193
|
+
/** Where a committedOnly key of a capability with this layer may be set: the committed payload layers the
|
|
194
|
+
* resolver merges for it (`at` strings, as payloadOrigins names them), and the words for the refusal. */
|
|
195
|
+
function committedOnlyHomes(layer, key) {
|
|
196
|
+
if (WORKSPACE_PAYLOAD_SLOTS.includes(layer)) {
|
|
197
|
+
return { allowed: [`oats-workspace.yaml#/${layer}`, `soul.yaml#/${layer}`], where: `oats-workspace.yaml under ${layer}: or a soul's ${layer}: payload`, fix: `Set it in oats-workspace.yaml under ${layer}:, or remove it` };
|
|
198
|
+
}
|
|
199
|
+
if (layer) return { allowed: [`soul.yaml#/${layer}`], where: `a soul's ${layer}: payload`, fix: `Set it in the soul's ${layer}: payload, or remove it` };
|
|
200
|
+
return { allowed: [`oats.json#/settings/${key.replace(/~/g, "~0").replace(/\//g, "~1")}/default`], where: "its manifest default (the capability has no layer, so no committed payload reaches it)", fix: "Remove it" };
|
|
201
|
+
}
|
|
202
|
+
/** Refuse a committedOnly key in the host or spawn layer: only committed, reviewed files may set it (#1719). */
|
|
203
|
+
function assertNoCommittedOnlyKey(value, { path, layer, at, committedOnly, capability, capabilityLayer }) {
|
|
204
|
+
if (!committedOnly.size || !isObject(value)) return;
|
|
205
|
+
for (const key of committedOnly) {
|
|
206
|
+
if (!Object.hasOwn(value, key)) continue;
|
|
207
|
+
const homes = committedOnlyHomes(capabilityLayer, key);
|
|
208
|
+
const setIn = layer === "host" ? `oats-local.yaml settings.${capability}` : `--provider ${capability}`;
|
|
209
|
+
throw fail("E_WORKSPACE_SCHEMA", `${path}/${key}: ${show(key)} is a committed-only setting of ${capability} (its manifest marks it committedOnly): it was set in ${setIn}, and may be set only in a committed file — ${homes.where}. ${homes.fix} from ${setIn}`,
|
|
210
|
+
{ path: `${path}/${key}`, key, capability, reason: "committed-only-key", layer, at, allowed: homes.allowed });
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
|
|
182
214
|
/** Canonical JSON: object keys sorted (recursively), arrays in order, no whitespace. */
|
|
183
215
|
export function canonicalJson(value) {
|
|
184
216
|
if (value === undefined) return "null";
|
|
@@ -737,7 +769,7 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
|
|
|
737
769
|
seenSkills.set(s.name, s);
|
|
738
770
|
}
|
|
739
771
|
|
|
740
|
-
// Payloads (decision 14; addendum 5): manifest defaults ⊕ workspace
|
|
772
|
+
// Payloads (decision 14; addendum 5): manifest defaults ⊕ workspace.<slot> (messaging and tasks slots) ⊕ soul.<slot>
|
|
741
773
|
// ⊕ local.settings[cap] ⊕ spawn.providers[cap], each leaf's origin kept in payloadOrigins.
|
|
742
774
|
const settings = isObject(local?.settings) ? local.settings : {};
|
|
743
775
|
const providers = isObject(spawn.providers) ? spawn.providers : {};
|
|
@@ -767,15 +799,26 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
|
|
|
767
799
|
// provider receives one merged payload without provenance and cannot enforce this itself.
|
|
768
800
|
const hostOnly = hostOnlyKeys(m.manifest);
|
|
769
801
|
const committed = (payload, path, origin) => { assertNoHostOnlyKey(payload, path, hostOnly, m.name); add(payload, origin); };
|
|
770
|
-
//
|
|
802
|
+
// #1719: the mirror — a key marked `committedOnly` must be the same for every deployment (a shared
|
|
803
|
+
// task list), so the host layer and --provider are refused with it present, BEFORE the merge, for the
|
|
804
|
+
// same reason. Marked both, no layer but the manifest default could set it: a fault of the manifest.
|
|
805
|
+
const committedOnly = committedOnlyKeys(m.manifest);
|
|
806
|
+
for (const key of committedOnly) {
|
|
807
|
+
if (hostOnly.has(key)) throw fail(m.from.kind === "package" ? "E_PACKAGE_MANIFEST" : "E_CAPABILITY_MISSING", `${m.name} marks setting ${show(key)} both hostOnly and committedOnly, so no layer but its manifest default could set it — drop one of the two flags`, { capability: m.name, key, why: "settings-flag-conflict" });
|
|
808
|
+
}
|
|
809
|
+
const notCommitted = (payload, path, layer, at) => assertNoCommittedOnlyKey(payload, { path, layer, at, committedOnly, capability: m.name, capabilityLayer: m.layer });
|
|
810
|
+
// The provider's settings are base ⊕ workspace ⊕ soul ⊕ host ⊕ spawn. Teams are not settings: they reach the
|
|
771
811
|
// provider beside them (OATS_DEFAULT_TEAM*, OATS_TEAMS).
|
|
772
|
-
if (m.layer
|
|
773
|
-
assertNoReservedKey(workspace.
|
|
774
|
-
committed(workspace.
|
|
812
|
+
if (WORKSPACE_PAYLOAD_SLOTS.includes(m.layer) && isObject(workspace?.[m.layer])) {
|
|
813
|
+
assertNoReservedKey(workspace[m.layer], `/${m.layer}`);
|
|
814
|
+
committed(workspace[m.layer], `/${m.layer}`, { kind: "workspace", at: `oats-workspace.yaml#/${m.layer}` });
|
|
775
815
|
}
|
|
776
816
|
if (m.layer && isObject(definition[m.layer])) { assertNoReservedKey(definition[m.layer], `/${m.layer}`); committed(definition[m.layer], `/${m.layer}`, { kind: "soul", at: `soul.yaml#/${m.layer}` }); }
|
|
777
|
-
if (Object.hasOwn(settings, m.name) && isObject(settings[m.name])) { assertNoReservedKey(settings[m.name], `/settings/${m.name}`); add(settings[m.name], { kind: "host", at: `oats-local.yaml#/settings/${m.name}` }); } // the host layer: hostOnly keys are legal here
|
|
778
|
-
if (Object.hasOwn(providers, m.name) && isObject(providers[m.name]))
|
|
817
|
+
if (Object.hasOwn(settings, m.name) && isObject(settings[m.name])) { assertNoReservedKey(settings[m.name], `/settings/${m.name}`); notCommitted(settings[m.name], `/settings/${m.name}`, "host", `oats-local.yaml#/settings/${m.name}`); add(settings[m.name], { kind: "host", at: `oats-local.yaml#/settings/${m.name}` }); } // the host layer: hostOnly keys are legal here, committedOnly ones are not
|
|
818
|
+
if (Object.hasOwn(providers, m.name) && isObject(providers[m.name])) {
|
|
819
|
+
notCommitted(providers[m.name], `/spawn/providers/${m.name}`, "spawn", `--provider ${m.name}`);
|
|
820
|
+
committed(providers[m.name], `/spawn/providers/${m.name}`, { kind: "spawn", at: `--provider ${m.name}` });
|
|
821
|
+
}
|
|
779
822
|
payloads[m.name] = mergePayload(...layers);
|
|
780
823
|
origins[m.name] = payloadOrigins(sourced);
|
|
781
824
|
// A value outside the manifest's `settings.<key>.values` is refused where it was set: a
|
package/lib/schedule.mjs
CHANGED
|
@@ -341,7 +341,7 @@ function storedHerdrBackend(ws, id, def) {
|
|
|
341
341
|
|
|
342
342
|
/** Validate and normalize one definition against its scope. `backendSource` names the file and key
|
|
343
343
|
* a definition read from elsewhere sets its backend in (default: this scope's definitions file). */
|
|
344
|
-
export function validateDefinition(ws, def, { checkAgent = true, backendSource } = {}) {
|
|
344
|
+
export function validateDefinition(ws, def, { checkAgent = true, backendSource, io } = {}) {
|
|
345
345
|
if (!def || typeof def !== "object" || Array.isArray(def)) throw scheduleError("E_SCHEDULE_INVALID", "definition must be an object", { field: "definition" });
|
|
346
346
|
if (def.kind === "trigger") throw scheduleError("E_SCHEDULE_INVALID", "kind: a trigger is added with `oats trigger add`, not `oats schedule add`", { field: "kind" });
|
|
347
347
|
const id = def.id;
|
|
@@ -385,7 +385,7 @@ export function validateDefinition(ws, def, { checkAgent = true, backendSource }
|
|
|
385
385
|
validateCron(w.cron, w.tz, "wake.cron"); validateMessage(w.message, "wake.message");
|
|
386
386
|
out.wake = { cron: w.cron.trim(), tz: w.tz.trim(), message: w.message };
|
|
387
387
|
}
|
|
388
|
-
if (checkAgent)
|
|
388
|
+
if (checkAgent) confirmScheduledSoul(ws, out, io);
|
|
389
389
|
} else if (def.kind === "command") {
|
|
390
390
|
if (typeof def.cwd !== "string" || !isAbsolute(def.cwd) || !inside(ws, def.cwd) || !existsSync(def.cwd)) throw scheduleError("E_SCHEDULE_INVALID", "cwd: an existing absolute directory inside the scope", { field: "cwd" });
|
|
391
391
|
if (!Array.isArray(def.argv) || !def.argv.length || def.argv.some((a) => typeof a !== "string" || a.includes("\0")) || def.argv[0] !== "oats") throw scheduleError("E_SCHEDULE_INVALID", "argv: oats-only argument list starting with \"oats\"", { field: "argv" });
|
|
@@ -468,16 +468,31 @@ export function validateWorkspaceSchedule(dep, a) {
|
|
|
468
468
|
|
|
469
469
|
/** The soul a spawn job launches, under the deployment's one agents root
|
|
470
470
|
* (a definition's agentsRoot, when given, must be that root). `repo` is the
|
|
471
|
-
* work repository and never selects a soul.
|
|
471
|
+
* work repository and never selects a soul. Every spawn job names its soul as
|
|
472
|
+
* `oats spawn <soul>` does: the spawn resolves it through discovery (a member or
|
|
473
|
+
* package soul), whether or not this deployment has spawned it before; the
|
|
474
|
+
* agents/<soul>/soul copy is only spawn's per-commit cache. A local job still
|
|
475
|
+
* passes --agents-root (spawn checks it is its root). */
|
|
472
476
|
export function resolveScheduledAgent(ws, def) {
|
|
473
477
|
const [root] = scopeRoots(ws);
|
|
474
|
-
// A workspace schedule (0.29.0) names its soul as `oats spawn <soul>` does: discovery resolves
|
|
475
|
-
// it (a member or package soul), whether or not this deployment has spawned it before.
|
|
476
478
|
if (def.workspace) return { root, agent: { name: def.agent }, discover: true };
|
|
477
479
|
if (def.agentsRoot && resolve(def.agentsRoot) !== root) throw scheduleError("E_SCHEDULE_INVALID", `agentsRoot: ${def.agentsRoot} is not this deployment's agents root (${root})`, { field: "agentsRoot" });
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
480
|
+
return { root, agent: { name: def.agent } };
|
|
481
|
+
}
|
|
482
|
+
/** The save-time check of a local spawn job's soul (`add`, `update`): refuse what `oats spawn`
|
|
483
|
+
* would refuse. A soul already under the agents root is accepted without a child, so offline
|
|
484
|
+
* adds and stale cached souls stay accepted; any other name goes through spawn's own preview,
|
|
485
|
+
* with the job's selectors (a selector the run needs, such as its repo, would otherwise fail
|
|
486
|
+
* the preview's checks). */
|
|
487
|
+
function confirmScheduledSoul(ws, def, io) {
|
|
488
|
+
const { root, discover } = resolveScheduledAgent(ws, def);
|
|
489
|
+
if (findAgent(root, def.agent)) return;
|
|
490
|
+
try { spawnPreview(ws, def, { root, discover }, io); }
|
|
491
|
+
catch (e) {
|
|
492
|
+
if (e.unconfirmed) throw scheduleError("E_SCHEDULE_INVALID", `agent: soul ${JSON.stringify(def.agent)} could not be confirmed: ${e.message}`, { field: "agent" });
|
|
493
|
+
if (e.refusal) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${e.message}`, { field: "agent", details: { code: e.code } });
|
|
494
|
+
throw e;
|
|
495
|
+
}
|
|
481
496
|
}
|
|
482
497
|
|
|
483
498
|
// ----------------------------------------------------------------- time
|
|
@@ -556,6 +571,37 @@ export function workspaceSpawnContext(ws) {
|
|
|
556
571
|
try { const found = loadLocal(ws); return { kind: "local", local: found.path, dir: dirname(found.path) }; }
|
|
557
572
|
catch (e) { return { kind: "local", local: null, dir: ws, error: { code: e.code || "E_WORKSPACE_SCHEMA", message: e.message } }; }
|
|
558
573
|
}
|
|
574
|
+
/** The `oats spawn` selectors a spawn job's run passes (beside its purpose, task and launch
|
|
575
|
+
* flags), so a preview checks what the run will: one builder for the run and its previews.
|
|
576
|
+
* Every value travels as ONE `--flag=value` token. */
|
|
577
|
+
function spawnSelectorArgs(opts) {
|
|
578
|
+
const argv = [];
|
|
579
|
+
if (opts.launchConfig) argv.push(`--launch-config=${opts.launchConfig}`);
|
|
580
|
+
if (opts.harness) argv.push(`--harness=${opts.harness}`);
|
|
581
|
+
if (opts.model) argv.push(`--model=${opts.model}`);
|
|
582
|
+
if (opts.backend) argv.push(`--backend=${opts.backend}`);
|
|
583
|
+
if (opts.repo) argv.push(`--repo=${opts.repo}`);
|
|
584
|
+
return argv;
|
|
585
|
+
}
|
|
586
|
+
/** The kernel's own `oats spawn <agent> --preview --json` in the deployment, with the job's
|
|
587
|
+
* selectors (spawnSelectorArgs): what the run's spawn would resolve and refuse, written nowhere.
|
|
588
|
+
* Answers the preview's result; throws spawn's refusal (its code and message, `refusal: true`),
|
|
589
|
+
* an unconfirmed answer (`unconfirmed: true`: interrupted, timed out, no envelope), or the
|
|
590
|
+
* deployment's own error. */
|
|
591
|
+
function spawnPreview(ws, def, { root, discover }, io) {
|
|
592
|
+
const context = workspaceSpawnContext(ws);
|
|
593
|
+
if (context.error) throw scheduleError(context.error.code, context.error.message);
|
|
594
|
+
if (String(def.agent).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(def.agent)} is not a soul name`, { field: "agent" });
|
|
595
|
+
const argv = ["spawn", def.agent, `--dir=${context.dir}`, ...(discover ? [] : [`--agents-root=${root}`]), "--preview", "--json", ...spawnSelectorArgs(def)];
|
|
596
|
+
const r = runScheduleCommand(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, graceMs: io?.commandGraceMs, maxBuffer: 16 * 1024 * 1024, env: childEnv() });
|
|
597
|
+
const unconfirmed = (message) => scheduleError("E_SPAWN_FAILED", message, { unconfirmed: true });
|
|
598
|
+
if (r.interrupted === true) throw unconfirmed("the spawn preview was interrupted; its result is unconfirmed");
|
|
599
|
+
if (r.error?.code === "ETIMEDOUT" || (r.status === null && ["SIGTERM", "SIGKILL"].includes(r.signal))) throw unconfirmed("the spawn preview timed out; its result is unconfirmed");
|
|
600
|
+
const envelope = parseEnvelopeText(r.stdout);
|
|
601
|
+
if (!envelope || typeof envelope.ok !== "boolean") throw unconfirmed(`the spawn preview answered no valid envelope (exit ${r.status ?? r.signal})`);
|
|
602
|
+
if (!envelope.ok) throw scheduleError(envelope.error?.code || "E_SPAWN_FAILED", String(envelope.error?.message || "spawn preview failed"), { refusal: true });
|
|
603
|
+
return envelope.result;
|
|
604
|
+
}
|
|
559
605
|
/** A workspace spawn materializes EXACTLY like `oats spawn` — prepareInstance →
|
|
560
606
|
* ensureWorkspaceSoul → spawnInstanceAsync (resolve over the remotes, copy every
|
|
561
607
|
* module whole into the home, compose AGENTS.md from the modules' injects).
|
|
@@ -572,12 +618,7 @@ function spawnViaCli(ws, root, agent, opts, context, io) {
|
|
|
572
618
|
// Every value travels as ONE `--flag=value` token, so no value can be read as a flag of its own;
|
|
573
619
|
// the soul is the one positional, and an option-shaped one is refused.
|
|
574
620
|
if (String(agent.name).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(agent.name)} is not a soul name`, { field: "agent" });
|
|
575
|
-
const argv = ["spawn", agent.name, `--dir=${context.dir}`, ...(opts.discover ? [] : [`--agents-root=${root}`]), `--purpose=${opts.purpose}`, "--json"];
|
|
576
|
-
if (opts.launchConfig) argv.push(`--launch-config=${opts.launchConfig}`);
|
|
577
|
-
if (opts.harness) argv.push(`--harness=${opts.harness}`);
|
|
578
|
-
if (opts.model) argv.push(`--model=${opts.model}`);
|
|
579
|
-
if (opts.backend) argv.push(`--backend=${opts.backend}`);
|
|
580
|
-
if (opts.repo) argv.push(`--repo=${opts.repo}`);
|
|
621
|
+
const argv = ["spawn", agent.name, `--dir=${context.dir}`, ...(opts.discover ? [] : [`--agents-root=${root}`]), `--purpose=${opts.purpose}`, "--json", ...spawnSelectorArgs(opts)];
|
|
581
622
|
if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
|
|
582
623
|
if (opts.launch === false) argv.push("--no-launch");
|
|
583
624
|
// The task is multi-line text of arbitrary size: it travels as a private file, never in argv.
|
|
@@ -1089,6 +1130,7 @@ export function reconcile(ws, qid, { io, now = new Date(), clear = false, ctx =
|
|
|
1089
1130
|
});
|
|
1090
1131
|
if (homes.length === 1) adopted = { instance: `${def.agent}-${purpose}`, home: homes[0] };
|
|
1091
1132
|
else if (homes.length > 1) ambiguous = `${homes.length} homes named ${def.agent}-${purpose}: ${homes.join(", ")}`;
|
|
1133
|
+
else if (!clear && !runNameProven(ws, def)) return { schedule: describeHere(), reconciled: "unknown", remedy: `spawn names the runs of soul ${def.agent} after its own stem, not ${def.agent}-${purpose}, so the spawn's effects cannot be proven from its name; check the roster and the host by hand, then run oats schedule reconcile ${id} --clear to record launch-failed and free the slot, or oats schedule remove --force ${id}` };
|
|
1092
1134
|
} else if (attemptKind === "command" || attemptKind === "operation") {
|
|
1093
1135
|
const named = namedHomes(ws, js);
|
|
1094
1136
|
if (named.length === 1) adopted = named[0];
|
|
@@ -1111,6 +1153,16 @@ export function reconcile(ws, qid, { io, now = new Date(), clear = false, ctx =
|
|
|
1111
1153
|
});
|
|
1112
1154
|
}
|
|
1113
1155
|
|
|
1156
|
+
/** Whether a spawn job's runs are named `<agent>-<purpose>`, so a home's absence proves a lost
|
|
1157
|
+
* receipt launched nothing: only for a bare name of a member soul under the agents root, whose
|
|
1158
|
+
* agent name is that name. Spawn names a run after the soul's stem (core.mjs
|
|
1159
|
+
* deriveInstanceName): a qualified name is resolved by spawn, and a package soul homes at
|
|
1160
|
+
* <package>--<soul>, its runs named <package>-<soul>-<purpose>. */
|
|
1161
|
+
function runNameProven(ws, def) {
|
|
1162
|
+
if (typeof def.agent !== "string" || def.agent.includes("/") || def.agent.includes("--")) return false;
|
|
1163
|
+
const [root] = scopeRoots(ws);
|
|
1164
|
+
return findAgent(root, def.agent)?.name === def.agent;
|
|
1165
|
+
}
|
|
1114
1166
|
/** The homes in the scope of the instance a command attempt's answer named: its only adoptable
|
|
1115
1167
|
* receipt. Exactly one is adoptable; none or several leave its effects unproven. */
|
|
1116
1168
|
function namedHomes(ws, js) {
|
|
@@ -1235,18 +1287,7 @@ export function testSchedule(ws, qid, io, { now = new Date(), ctx = null } = {})
|
|
|
1235
1287
|
soul = { name: def.agent, origin: row.soul?.origin ?? null, resolves: false, error: null };
|
|
1236
1288
|
try {
|
|
1237
1289
|
const { root, discover } = resolveScheduledAgent(ws, def);
|
|
1238
|
-
|
|
1239
|
-
if (context.error) throw scheduleError(context.error.code, context.error.message);
|
|
1240
|
-
if (String(def.agent).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(def.agent)} is not a soul name`, { field: "agent" });
|
|
1241
|
-
const argv = ["spawn", def.agent, `--dir=${context.dir}`, ...(discover ? [] : [`--agents-root=${root}`]), "--preview", "--json"];
|
|
1242
|
-
if (def.launchConfig) argv.push(`--launch-config=${def.launchConfig}`);
|
|
1243
|
-
if (def.harness) argv.push(`--harness=${def.harness}`);
|
|
1244
|
-
if (def.model) argv.push(`--model=${def.model}`);
|
|
1245
|
-
const r = runScheduleCommand(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, graceMs: io?.commandGraceMs, maxBuffer: 16 * 1024 * 1024, env: childEnv() });
|
|
1246
|
-
if (r.interrupted === true) throw scheduleError("E_SPAWN_FAILED", "the spawn preview was interrupted; its result is unconfirmed");
|
|
1247
|
-
const envelope = parseEnvelopeText(r.stdout);
|
|
1248
|
-
if (!envelope || typeof envelope.ok !== "boolean") throw scheduleError("E_SPAWN_FAILED", `the spawn preview answered no valid envelope (exit ${r.status ?? r.signal})`);
|
|
1249
|
-
if (!envelope.ok) throw scheduleError(envelope.error?.code || "E_SPAWN_FAILED", String(envelope.error?.message || "spawn preview failed"));
|
|
1290
|
+
spawnPreview(ws, def, { root, discover }, io);
|
|
1250
1291
|
soul.resolves = true;
|
|
1251
1292
|
} catch (e) {
|
|
1252
1293
|
soul.error = { code: e.code || "E_SPAWN_FAILED", message: e.message };
|
|
@@ -1352,7 +1393,7 @@ export function listSchedules(ws, io, { now = new Date(), ctx = null } = {}) {
|
|
|
1352
1393
|
return { scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, integrity: scheduleIntegrity(ws), host: { name: ctx?.host?.name ?? null, ghUser: ctx?.ghUsers ? ctx.ghUsers() : {} }, schedules: [...local, ...workspace], triggers: { count: triggers, command: "oats trigger list" }, snapshot: ctx?.snapshot ? { takenAt: ctx.snapshot.takenAt, problems: (ctx.snapshot.problems || []).length } : null, scheduler: schedulerStatus(ws, io) };
|
|
1353
1394
|
}
|
|
1354
1395
|
export function addSchedule(ws, spec, io) {
|
|
1355
|
-
const def = validateDefinition(ws, spec);
|
|
1396
|
+
const def = validateDefinition(ws, spec, { io });
|
|
1356
1397
|
return withScopeLock(ws, () => {
|
|
1357
1398
|
const defs = readDefinitions(ws);
|
|
1358
1399
|
if (defs.jobs[def.id]) throw scheduleError("E_SCHEDULE_EXISTS", `schedule ${def.id} already exists in ${ws}`);
|
|
@@ -1368,7 +1409,7 @@ export function addSchedule(ws, spec, io) {
|
|
|
1368
1409
|
* while the job holds a slot or has an unresolved attempt; timing and text can. */
|
|
1369
1410
|
export function updateSchedule(ws, qid, spec, io) {
|
|
1370
1411
|
const id = localScheduleId(qid, "update");
|
|
1371
|
-
const def = validateDefinition(ws, { ...spec, id });
|
|
1412
|
+
const def = validateDefinition(ws, { ...spec, id }, { io });
|
|
1372
1413
|
return withHostLock(() => withScopeLock(ws, () => {
|
|
1373
1414
|
const defs = readDefinitions(ws);
|
|
1374
1415
|
if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
|
package/lib/workspace.mjs
CHANGED
|
@@ -223,7 +223,7 @@ function keyOrProblem(remote, ref, path, problems) {
|
|
|
223
223
|
/** Schema + domain problems for an oats-workspace.yaml value. Refs are parsed with `remote`
|
|
224
224
|
* (default lib/remote.mjs) so duplicate members and malformed refs are always caught. */
|
|
225
225
|
export function validateWorkspace(value, { remote = defaultRemote } = {}) {
|
|
226
|
-
const problems = validateAgainst(schemaFor("workspace"), value);
|
|
226
|
+
const problems = validateAgainst(schemaFor("workspace"), value).map(newerRootKeyHint);
|
|
227
227
|
if (!isObject(value)) return problems;
|
|
228
228
|
if (value.schemaVersion !== 2) return referenceProblems(problems, refFields(value));
|
|
229
229
|
// Absolute-path refusal applies to REF/PATH fields only (L2): never to descriptions or the provider payload.
|
|
@@ -250,6 +250,7 @@ export function validateWorkspace(value, { remote = defaultRemote } = {}) {
|
|
|
250
250
|
if (isObject(value.messaging) && Object.hasOwn(value.messaging, "byTeam")) {
|
|
251
251
|
problems.push({ path: "/messaging/byTeam", reason: "removed-key", message: "messaging.byTeam was removed in 0.30: a team's provider id is teams.<label>.team (committed, shared) or oats-local.yaml teams.<label>.team (local)" });
|
|
252
252
|
}
|
|
253
|
+
if (isObject(value.tasks)) reservedKeyProblems(value.tasks, "/tasks", problems);
|
|
253
254
|
if (Array.isArray(value.external)) value.external.forEach((entry, i) => {
|
|
254
255
|
if (!isObject(entry)) return;
|
|
255
256
|
if (typeof entry.source === "string") {
|
|
@@ -264,6 +265,14 @@ export function validateWorkspace(value, { remote = defaultRemote } = {}) {
|
|
|
264
265
|
sharedLabelProblems(value, problems);
|
|
265
266
|
return referenceProblems(withRemovedKeys(problems, value, REMOVED_KEYS.workspace), refFields(value));
|
|
266
267
|
}
|
|
268
|
+
/** An unknown key at the workspace file's root is most often one a newer kernel added (a slot payload, a
|
|
269
|
+
* new section): the problem says so, beside the schema's own "unknown property" text. Nested keys keep it
|
|
270
|
+
* bare, and a removed key's own message (withRemovedKeys) replaces it. */
|
|
271
|
+
const KERNEL = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
|
|
272
|
+
function newerRootKeyHint(problem) {
|
|
273
|
+
if (!/^\/[^/]+$/.test(problem.path) || !problem.message.startsWith("unknown property ")) return problem;
|
|
274
|
+
return { ...problem, reason: "unknown-root-key", message: `${problem.message} — if this is not a typo, the workspace uses a feature newer than this kernel (OATS ${KERNEL}): upgrade OATS` };
|
|
275
|
+
}
|
|
267
276
|
/** Team model 3: every label `defaultTeam` and `souls:` name is a shared team of this same file, so an
|
|
268
277
|
* unknown label is refused when the file is read, never at a spawn on someone else's machine. */
|
|
269
278
|
function sharedLabelProblems(value, problems) {
|
package/package-catalog.json
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
10
10
|
"url": "https://github.com/awebai/oats-aweb.git",
|
|
11
|
-
"ref": "v1.
|
|
11
|
+
"ref": "v1.35.0",
|
|
12
12
|
"path": "oats-package"
|
|
13
13
|
},
|
|
14
14
|
"oats.jira": {
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
},
|
|
49
49
|
"oats.framework": {
|
|
50
50
|
"url": "https://github.com/awebai/oats.git",
|
|
51
|
-
"ref": "oats-framework/v1.
|
|
51
|
+
"ref": "oats-framework/v1.21.0",
|
|
52
52
|
"path": "oats-package"
|
|
53
53
|
}
|
|
54
54
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.69.
|
|
3
|
+
"version": "0.69.11",
|
|
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",
|