@awebai/oats 0.27.1 → 0.28.0

package/lib/workspace.mjs

@@ -15,7 +15,7 @@ import { dirname, join, resolve } from "node:path";
 import { parseConfigData } from "./config-data.mjs";
 import { oatsError } from "./errors.mjs";
 import * as defaultRemote from "./remote.mjs";
-import { bindRemote, classifyPackageValue } from "./packages.mjs";
+import { bindRemote, classifyPackageValue, lockedPackageRef } from "./packages.mjs";
 import { manifestContractProblems } from "./capability-contract.mjs";
 
 /* ───────────────────────────── errors ─────────────────────────────────── */
@@ -612,6 +612,75 @@ export async function discoverRepo(ref, { at, remote: injected, remoteOptions }
   return { key: obs.key, commit: obs.commit, membership, ...items, problems: [...problems, ...items.problems] };
 }
 
+/** The agents-root directory (and agent name) of a package soul: `<package>--<soul>`, the package id
+ *  with every character outside [a-z0-9-] as `-` (`oats.okf/knowledge-maintainer` →
+ *  `oats-okf--knowledge-maintainer`). A soul name is a slug and never holds `--`, so this can never be
+ *  a member soul's directory; instances are named by the slug of it (`oats-okf-knowledge-maintainer-<purpose>`). */
+export const PACKAGE_SOUL_SEPARATOR = "--";
+export function packageSoulAgentName(id, soul) { return `${String(id).replace(/[^a-z0-9-]/g, "-")}${PACKAGE_SOUL_SEPARATOR}${soul}`; }
+
+/**
+ * Package souls (0.28.0): the souls the lock records for each package the workspace STILL declares,
+ * read at the locked commit. A package soul is listed like a member soul, with its package origin
+ * (`package`, `version`) and its qualified name `<package>/<soul>`; its labels are its soul.yaml's
+ * own `team` (a package has no membership default) and each must be declared (E_TEAM_UNKNOWN).
+ * Nothing here trusts the lock's digests — a spawn verifies the fetched soul against them.
+ * `lock` null (or no workspace) → nothing. → { souls: [SoulEntry], problems }
+ */
+export async function discoverPackageSouls(workspace, lock, { remote: injected, remoteOptions } = {}) {
+  const souls = [], problems = [];
+  if (!isObject(lock?.packages) || !isObject(workspace)) return { souls, problems };
+  const remote = remoteOf({ remote: injected, remoteOptions });
+  const declared = isObject(workspace.packages) ? workspace.packages : {};
+  const teams = isObject(workspace.teams) ? Object.keys(workspace.teams) : [];
+  for (const id of Object.keys(lock.packages).sort()) {
+    const entry = lock.packages[id];
+    if (!Array.isArray(entry?.souls) || entry.souls.length === 0 || !Object.hasOwn(declared, id)) continue;
+    const at = (rel) => `package:${id}:${rel}`;
+    const problem = (code, path, message) => problems.push({ code, repoKey: null, package: id, path: at(path), message });
+    const ref = lockedPackageRef(entry);
+    if (!ref) { problem("E_PACKAGE_MISSING", entry.path, `the lock records no url for ${id} — run \`oats sync\``); continue; }
+    let key;
+    try { key = remote.parseRepoRef(ref).key; }
+    catch (e) { if (e?.code === "E_REPO_REF") { problem("E_REPO_REF", entry.path, e.message); continue; } throw e; }
+    for (const locked of entry.souls) {
+      const path = `${entry.path}/${locked.path}`;
+      const file = `${path}/soul.yaml`;
+      let bytes;
+      try { ({ bytes } = await remote.readRemoteFile(ref, entry.commit, file)); }
+      catch (e) {
+        if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) { problem(e.code, file, e.message); continue; }
+        throw e;
+      }
+      const read = readDeclaration("soul", bytes, { kind: "soul", repoKey: key, commit: entry.commit, path: file });
+      if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); continue; }
+      const definition = read.value;
+      if (definition.name !== locked.name) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(locked.name)}`); continue; }
+      const labels = labelList(definition.team) ?? [];
+      for (const [label, where] of labelPaths(definition, labels, file)) {
+        if (!teams.includes(label)) problems.push({ code: "E_TEAM_UNKNOWN", repoKey: null, package: id, path: at(where), message: `team ${show(label)} is not declared in the workspace's teams (${teams.join(", ") || "none"}) — declare it in oats-workspace.yaml teams: to spawn ${id}/${locked.name}` });
+      }
+      souls.push({
+        name: locked.name, path, repoKey: key, ref, commit: entry.commit, team: labels[0] ?? null, labels, private: false, definition,
+        package: id, version: entry.version, qualifiedName: `${id}/${locked.name}`, agentName: packageSoulAgentName(id, locked.name), digest: locked.digest,
+      });
+    }
+  }
+  // Two packages whose ids differ only where the directory name sanitises (`a.b`, `a-b`) and that
+  // ship a same-named soul would share one agent directory: both are listed, neither is spawnable.
+  const byDir = new Map();
+  for (const s of souls) byDir.set(s.agentName, [...(byDir.get(s.agentName) || []), s]);
+  for (const [dir, group] of byDir) {
+    if (group.length < 2) continue;
+    const qualified = group.map((s) => s.qualifiedName).sort();
+    for (const s of group) {
+      s.collides = qualified;
+      problems.push({ code: "E_SOUL_AMBIGUOUS", repoKey: null, package: s.package, path: `package:${s.package}:${s.path}/soul.yaml`, message: `package souls ${qualified.join(" and ")} would share the agent directory agents/${dir}/ — keep one of the packages in packages:` });
+    }
+  }
+  return { souls, problems };
+}
+
 /**
  * The whole picture in one access context.
  * → { workspace, members: [{ key, commit, confirmed, reason?, team, souls, capabilities, publishes }], external: [...],
@@ -619,7 +688,7 @@ export async function discoverRepo(ref, { at, remote: injected, remoteOptions }
  * `publishes` = { package, version } when the member carries oats-package/oats-package.json (informational:
  * the package's capabilities are NOT member capabilities — non-collapse rule), else null.
  */
-export async function discoverWorkspace(ref, { at, local, remote: injected, remoteOptions } = {}) {
+export async function discoverWorkspace(ref, { at, local, lock = null, remote: injected, remoteOptions } = {}) {
   const remote = remoteOf({ remote: injected, remoteOptions });
   const wsObs = await observeWorkspace(ref, { at, remote });
   const workspace = wsObs.workspace;
@@ -671,7 +740,15 @@ export async function discoverWorkspace(ref, { at, local, remote: injected, remo
     for (const label of labels) if (!teams.includes(label)) pushProblem("E_TEAM_UNKNOWN", `${file}#/team`, `team ${show(label)} is not declared in the workspace's teams`);
     externalRows.push({ source: entry.source, key, commit, soul: { name: read.value.name, path: entry.soul, repoKey: key, commit, team: labels[0] ?? null, labels, private: false, definition: read.value } });
   }
-  return { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, problems, warnings: [...unmappedLabelWarnings(workspace, members, externalRows, teams), ...privateSoulWarnings([...members.filter((m) => m.confirmed).flatMap((m) => m.souls), ...externalRows.map((e) => e.soul)])] };
+  const pkg = await discoverPackageSouls(workspace, lock, { remote });
+  problems.push(...pkg.problems);
+  return { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, packageSouls: pkg.souls, problems, warnings: workspaceWarnings(workspace, members, externalRows, pkg.souls, teams) };
+}
+
+/** The discovery's warnings: unmapped team labels and ignored `private:`, over every listed soul. */
+export function workspaceWarnings(workspace, members, externalRows, packageSouls, teams = isObject(workspace?.teams) ? Object.keys(workspace.teams) : []) {
+  const extra = (packageSouls || []).map((soul) => ({ soul }));
+  return [...unmappedLabelWarnings(workspace, members, [...externalRows, ...extra], teams), ...privateSoulWarnings([...members.filter((m) => m.confirmed).flatMap((m) => m.souls), ...externalRows.map((e) => e.soul), ...(packageSouls || [])])];
 }
 
 /** Teams contract decision 5: a soul label the workspace declares in `teams:` but does not map in

package/package-catalog.json

@@ -3,7 +3,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v2.1.5",
+      "ref": "v3.0.0",
       "path": "oats-package"
     },
     "oats.aweb": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",