@awebai/oats 0.24.1 → 0.24.2

package/lib/core.mjs

@@ -51,6 +51,7 @@ import { buildCapturedInvocationContext, withCapturedInvocationContextFile } fro
 import { readCapturedInstanceIndex, readCapturedInstanceMetadata, readCapturedInstanceAuthority, assertCapturedInstanceCustody,
   recordCapturedCustodyFailure, markCapturedNativeScaffold, failCapturedNativeIntent, observeCapturedNativeTarget, setCapturedInstanceStatus, admitCapturedInstanceAction, beginCapturedIntent, settleCapturedIntent } from "./captured-instance-index.mjs";
 import { validateExecutionBinding } from "./schedule-capsule.mjs";
+import { parsePortableSource } from "./source-spec.mjs";
 import { validateIntentRef } from "./captured-admission-shape.mjs";
 export { readCapturedInstanceIndex, readCapturedInstanceMetadata, beginCapturedIntent, settleCapturedIntent };
 export { buildCapturedInvocationContext, withCapturedInvocationContextFile };
@@ -112,6 +113,18 @@ export const OATS_VERSION = JSON.parse(readFileSync(join(PKG_ROOT, "package.json
 /** Skills shipped with the kernel. Only oats-getting-started is ambient; spawn composes selected skills locally. */
 export const PACKAGED_SKILLS_DIR = join(PKG_ROOT, "skills");
 
+function soulRequirements(soulDir) {
+  const file = soulDir && join(soulDir, "soul.yaml");
+  return file && existsSync(file) ? withConfigFile(file, () => parseYamlNested(readFileSync(file, "utf8"))).requires : undefined;
+}
+function declaredOperationalCapabilities(soulDir) {
+  const capabilities = soulRequirements(soulDir)?.capabilities ?? {};
+  return ["oats.core", "oats.setup"].filter(id => Object.hasOwn(capabilities, id));
+}
+function legacyOperationalSkills(soulDir) {
+  return declaredOperationalCapabilities(soulDir).length ? [] : ["oats", "oats-config", "oats-packages"].map(name => ({ id: "kernel", path: join(PACKAGED_SKILLS_DIR, name) }));
+}
+
 // ---------- shell helpers ----------
 function sh(cmdline) { return execSync(cmdline, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); }
 function shTry(cmdline) { try { return sh(cmdline); } catch { return undefined; } }
@@ -4083,6 +4096,10 @@ export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode,
   if (!existsSync(agentsMd)) throw new Error(`canonical soul instructions missing: ${agentsMd}`);
   const resolved = resolveOatsConfig(contextDir, soulName);
   const wanted = [];
+  const declaredOperations = declaredOperationalCapabilities(soulDir);
+  const oatsCoreDeclared = declaredOperations.includes("oats.core");
+  if (declaredOperations.length) resolved.kernelInjection = { inject: undefined,
+    provenance: `declared ${declaredOperations.join(", ")} ${declaredOperations.length === 1 ? "capability" : "capabilities"}` };
   const kernelInject = resolved.kernelInjection?.inject;
   if (kernelInject && existsSync(kernelInject)) wanted.push(["kernel:oats", kernelInject]);
   if (kind === "local") {
@@ -4104,7 +4121,7 @@ export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode,
   }
   for (const inj of resolved.injects) wanted.push([`config:${inj.source}`, inj.file]);
   const blocks = wanted.map(([source, file]) => ({ source, file, content: readFileSync(file, "utf8").trim() }));
-  return { text: renderInstructionText(readFileSync(agentsMd, "utf8"), blocks), blocks, resolved };
+  return { text: renderInstructionText(readFileSync(agentsMd, "utf8"), blocks), blocks, resolved, oatsCoreDeclared };
 }
 
 /** The skill entries a tree contributes — THE discovery rule, shared by preflight
@@ -4162,7 +4179,7 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
     }
   };
 
-  for (const path of [join(PACKAGED_SKILLS_DIR, "oats"), join(PACKAGED_SKILLS_DIR, "oats-config"), join(PACKAGED_SKILLS_DIR, "oats-packages")]) {
+  for (const { path } of legacyOperationalSkills(soulDir)) {
     add({ type: "skill-tree", source: "kernel", declared: basename(path), path: existsSync(path) ? path : undefined });
   }
   const soulSkills = soulDir && join(soulDir, "skills");
@@ -5110,15 +5127,31 @@ export function resolveYolo(value) {
   throw new Error("yolo must be true or false");
 }
 
-export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo, description, type, instructions }) {
+/** Creation chooses a declared source, never acquisition/activation or a made-up
+ * future release. Existing definitions (including deliberate removal) are kept. */
+function defaultOatsCoreRequirement() {
+  const mapping = officialCapabilityPackage("oats.core");
+  const entry = mapping.available && mapping.migratedCapability === "oats.core" && officialPackageCatalog()[mapping.package];
+  if (entry && typeof entry.url === "string" && typeof entry.ref === "string" && entry.ref) {
+    const parsed = parsePortableSource(`git:${entry.url}@${entry.ref}#${entry.path ?? DEFAULT_PACKAGE_PATH}`);
+    return { requires: { capabilities: { "oats.core": { source: `${parsed.source}#${parsed.path}` } } }, notes: [] };
+  }
+  return { requires: undefined, notes: [{ code: "needs-configuration", message: "oats.core has no published revision in the official package catalog; no source was invented. Add its explicit requirement after the catalog entry is available, or use --no-oats-core to opt out at creation." }] };
+}
+
+export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo, description, type, instructions, oatsCore = true }) {
   yolo = resolveYolo(yolo);
+  if (typeof oatsCore !== "boolean") throw oatsError("E_BAD_ARGS", "oatsCore must be a boolean");
   const agentDir = agentDirOf(root, name, kind);
-  const soulDir = soulOf(agentDir);
+  const soulDir = soulOf(agentDir), soulFile = join(soulDir, "soul.yaml");
+  const { requires, notes } = existsSync(soulFile)
+    ? { requires: soulRequirements(soulDir), notes: [] }
+    : oatsCore ? defaultOatsCoreRequirement() : { requires: undefined, notes: [] };
   mkdirSync(soulDir, { recursive: true });
   mkdirSync(join(agentDir, "instances"), { recursive: true });
-  writeFileSync(join(soulDir, "soul.yaml"), yamlFlat({
+  writeFileSync(soulFile, yamlFlat({
     name, kind, description, type, repo, work: work || "checkout", runtime: runtime || "pi", model, yolo,
-  }));
+  }) + (requires === undefined ? "" : `requires: ${JSON.stringify(requires)}\n`));
   const agentsMd = join(soulDir, "AGENTS.md");
   if (instructions !== undefined || !existsSync(agentsMd)) {
     writeFileSync(agentsMd, instructions ?? defaultSoulAgentsMd(name, description));
@@ -5132,7 +5165,7 @@ export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo,
     home: soulDir, instance: name, agentName: name, soulDir,
     contextDir: ctx, workspaceDir: workspaceOf(root), rootDir: root, resolved,
   });
-  return { agentDir, soulDir };
+  return { agentDir, soulDir, ...(notes.length ? { notes } : {}) };
 }
 function defaultSoulAgentsMd(name, description) {
   return `# ${name}
@@ -5154,8 +5187,8 @@ export function createAgent(root, o) {
   // kind: "local" → a FULL soul (memory, skills, instances) under the scope's
   // local-agents/ — uncommitted by contract; otherwise a committed persistent soul.
   const kind = o.local || o.kind === "local" ? "local" : "persistent";
-  const { agentDir } = writeSoul(root, { ...o, name, kind });
-  return { agent: name, kind, soul: soulOf(agentDir) };
+  const { agentDir, notes } = writeSoul(root, { ...o, name, kind });
+  return { agent: name, kind, soul: soulOf(agentDir), ...(notes ? { notes } : {}) };
 }
 
 /** Upsert a local agent soul (from raw instructions or a Claude-style def file).
@@ -5182,13 +5215,13 @@ export function upsertLocalAgent(root, o) {
   const existing = findAgent(root, name);
   if (existing && existing.kind !== "local") throw new Error(`"${name}" is a persistent agent — spawn it instead`);
   if (!existing && instructions === undefined) throw new Error(`local agent "${name}" needs instructions (none on disk yet)`);
-  writeSoul(root, {
-    name, kind: "local",
+  const { notes } = writeSoul(root, {
+    name, kind: "local", oatsCore: o.oatsCore,
     repo: repo ?? existing?.repo, work: work ?? existing?.work,
     runtime: runtime ?? existing?.runtime, model: model ?? existing?.model, yolo: yolo ?? existing?.yolo,
     description: description ?? existing?.description, instructions,
   });
-  return findAgent(root, name);
+  return { ...findAgent(root, name), ...(notes ? { notes } : {}) };
 }
 /** Back-compat alias: older installed capabilities (oats-okf ≤1.3.x) call this. */
 export const upsertTmpAgent = upsertLocalAgent;
@@ -6136,7 +6169,7 @@ export function spawnInstance(root, agent, o = {}) {
   symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
 
   // Runtime-neutral exact skill materialization. No harness receives ambient workspace/package skills.
-  const sources = [{ id: "kernel", path: join(PACKAGED_SKILLS_DIR, "oats") }, { id: "kernel", path: join(PACKAGED_SKILLS_DIR, "oats-config") }, { id: "kernel", path: join(PACKAGED_SKILLS_DIR, "oats-packages") }];
+  const sources = legacyOperationalSkills(soulDir);
   const soulSkills = join(soulDir, "skills");
   if (existsSync(soulSkills)) sources.push({ id: "soul", path: soulSkills });
   for (const cap of resolvedCfg.capabilities) for (const path of cap.skills || []) sources.push({ id: cap.id, path });

package/lib/provider-binding-broker.mjs

@@ -1,6 +1,8 @@
 /** Execute only an approved retained provider command. Preparation does not need
  * a fabricated complete resolution merely to obtain its binding. */
 import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { canonicalJson } from './portable-values.mjs';
 import { objectAt } from './portable-shape.mjs';
 import { validateArtifactSet } from './resolution-shape.mjs';
@@ -12,6 +14,9 @@ import { validateBindingInterface } from './provider-binding.mjs';
 import { BINDING_LIMITS, validateBindingRequest, decodeBindingResponse } from './provider-binding-wire.mjs';
 import { oatsError } from './errors.mjs';
 
+// Same kernel-owned CLI locator as lifecycle hooks; never caller env or PATH.
+const CLI_BIN=fileURLToPath(new URL('../bin/oats.mjs',import.meta.url));
+
 export function invokeProviderBinding(options,codecs) {
   canonicalJson(options);
   objectAt(options,['deployment','artifacts','capability','phase','settings','input','timeoutMs'],['deployment','artifacts','capability','phase','settings','input']);
@@ -46,7 +51,7 @@ export function invokeProviderBinding(options,codecs) {
   const [script,...args]=spec.trim().split(/\s+/),file=codecs.executable(manifest,script);
   if (!file) throw oatsError('resource-not-found','provider codec executable is unavailable');
   const environment=Object.fromEntries(Object.entries(process.env).filter(([key])=>! /^(OATS_|OAS_|PI_)/.test(key)));
-  Object.assign(environment,{OATS_CAPABILITY:capability,OATS_CAPABILITY_ROOT:root,OATS_SETTINGS:canonicalJson(settings,BINDING_LIMITS)});
+  Object.assign(environment,{OATS_CAPABILITY:capability,OATS_CAPABILITY_ROOT:root,OATS_SETTINGS:canonicalJson(settings,BINDING_LIMITS),OATS_CLI_BIN:realpathSync(CLI_BIN)});
   let result;
   try {
     result=spawnSync(process.execPath,[file,...args],{cwd:root,env:environment,input:canonicalJson(request,BINDING_LIMITS),

package/lib/setup-expert-source.mjs

@@ -0,0 +1,76 @@
+/** Read the setup edition as data for a CLASSIC local bootstrap copy.
+ * No provider code, workspace activation, enrollment or captured identity. */
+import { lstatSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { parsePortableSoul } from './portable-soul.mjs';
+import { parseRepositorySource, parsePortableSource } from './source-spec.mjs';
+import { createRepositoryTransaction } from './repository-observation.mjs';
+import { createWorkspaceDiscovery } from './workspace-discovery.mjs';
+import { packageIntegrity } from './core.mjs';
+import { oatsError } from './errors.mjs';
+
+export const SETUP_EXPERT = 'oats-setup-expert';
+export const SETUP_CAPABILITIES = Object.freeze(['oats.core', 'oats.setup']);
+const EXPORT = `souls/${SETUP_EXPERT}`;
+function validateEdition(bytes) {
+  const { declaration: soul } = parsePortableSoul(bytes);
+  const required = soul.requires || {}, caps = required.capabilities || {};
+  if (soul.name !== SETUP_EXPERT || soul.work !== 'directory'
+      || Object.keys(required).some(key => key !== 'capabilities')
+      || Object.keys(caps).length !== 2 || SETUP_CAPABILITIES.some(id => caps[id]?.source !== 'repo:oats-package' || Object.keys(caps[id]).some(key => key !== 'source'))
+      || ['knowledge', 'messaging', 'tasks'].some(slot => soul.defaults?.[slot] !== 'none')
+      || Object.keys(soul.defaults || {}).some(key => !['knowledge', 'messaging', 'tasks'].includes(key))
+      || soul.knowledge || soul.teams?.length || soul.resources?.length || soul.yolo === true || soul.backend || soul['launch-config']) {
+    throw oatsError('needs-configuration', 'classic setup bootstrap needs the provider-independent directory edition with only oats.core/oats.setup; use explicit portable preparation for other requirements');
+  }
+  return soul;
+}
+function repositoryRequest(source) {
+  if (typeof source !== 'string' || source.includes('#')) throw oatsError('invalid-source', '--workspace needs a Git repository source, optionally @revision, without a package fragment');
+  try { return { source: parseRepositorySource(source).normalized }; }
+  catch {
+    const parsed = parsePortableSource(source);
+    if (parsed.kind !== 'git') throw oatsError('invalid-source', '--workspace needs an explicit Git repository source');
+    return { source: `git:${parsed.url}`, revision: parsed.selector };
+  }
+}
+
+export function loadSetupExpertEdition(workspace, repositoryOptions = {}) {
+  if (workspace === undefined) {
+    const root = fileURLToPath(new URL(`../${EXPORT}/`, import.meta.url));
+    return { declaration: validateEdition(readFileSync(join(root, 'soul.yaml'))), instructions: readFileSync(join(root, 'AGENTS.md'), 'utf8'),
+      source: { kind: 'packaged-definition', captured: false }, packageIntegrity: null };
+  }
+  const request = repositoryRequest(workspace), scratch = realpathSync(mkdtempSync(join(tmpdir(), 'oats-setup-source-'))), owned = lstatSync(scratch);
+  let transaction;
+  try {
+    transaction = createRepositoryTransaction({ ...repositoryOptions, directory: scratch, accessContextKey: 'explicit-setup-source' });
+    const discovery = createWorkspaceDiscovery(transaction), origin = { kind: 'operator', document: { kind: 'operator', id: 'oats-onboard' }, pointer: '/workspace' };
+    const observed = transaction.observe(request.source, { ...request, origin });
+    const workspaceDoc = transaction.readFile(observed, 'oats-workspace.yaml', { optional: true });
+    const view = workspaceDoc ? discovery.readWorkspace({ ...request, origin }) : null;
+    const reference = view?.parsed.imports.find(item => item.alias === SETUP_EXPERT)
+      ?? { source: request.source, revision: observed.source.commit, soul: EXPORT, alias: SETUP_EXPERT };
+    // A selected workspace import never falls back if its exact source fails.
+    const imported = discovery.importSoul(reference, { origin });
+    if (reference.adoption) throw oatsError('needs-configuration', 'classic setup copies an edition only; provider adoption values require the portable preparation path');
+    const declaration = validateEdition(transaction.readFile(imported.observation, imported.definition).bytes);
+    const projection = join(scratch, 'edition');
+    transaction.materialize(imported.observation, imported.roots, projection);
+    const soulRoot = join(projection, dirname(imported.definition)), body = join(soulRoot, 'AGENTS.md'), alias = join(soulRoot, 'CLAUDE.md');
+    if (!lstatSync(body).isFile() || !lstatSync(alias).isSymbolicLink() || readlinkSync(alias) !== 'AGENTS.md'
+        || readdirSync(soulRoot).some(name => !['soul.yaml', 'AGENTS.md', 'CLAUDE.md'].includes(name))) {
+      throw oatsError('source-incomplete', 'classic setup edition must have canonical AGENTS.md/CLAUDE.md and no omitted private skill or knowledge trees');
+    }
+    return { declaration, instructions: readFileSync(body, 'utf8'), packageIntegrity: packageIntegrity(join(projection, 'oats-package')),
+      source: { kind: 'exported-edition-copy', source: imported.reference.source, revision: imported.observation.source.commit,
+        path: imported.reference.soul, workspaceRevision: view?.source.commit ?? null, captured: false } };
+  } finally {
+    transaction?.close();
+    const current = lstatSync(scratch);
+    if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError('source-unavailable', 'setup source scratch ownership changed');
+    rmSync(scratch, { recursive: true });
+  }
+}

package/package-catalog.json

@@ -8,7 +8,7 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.10.3",
+      "ref": "v1.11.0",
       "path": "oats-package"
     },
     "oats.jira": {
@@ -31,9 +31,9 @@
       "ref": "v1.0.0",
       "path": "oats-package"
     },
-    "oats.knowledge-theory": {
+    "oats.framework": {
       "url": "https://github.com/awebai/oats.git",
-      "ref": "v0.23.0",
+      "ref": "oats-framework/v1.1.1",
       "path": "oats-package"
     }
   },
@@ -66,6 +66,9 @@
     "oas.review": {
       "package": "oats.dev",
       "capability": "oats.review"
-    }
+    },
+    "oats.knowledge-theory": "oats.framework",
+    "oats.core": "oats.framework",
+    "oats.setup": "oats.framework"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.24.1",
+  "version": "0.24.2",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",
@@ -36,6 +36,8 @@
     "docs/",
     "README.md",
     "package-catalog.json",
+    "souls/oats-setup-expert/soul.yaml",
+    "souls/oats-setup-expert/AGENTS.md",
     "packages/record/bin/",
     "packages/record/lib/",
     "packages/record/docs/",

package/souls/oats-setup-expert/AGENTS.md

@@ -0,0 +1,60 @@
+# OATS Setup Expert
+
+Help an operator turn an empty deployment into a deliberately configured OATS
+workspace. Explain the next small decision, inspect the existing state, obtain
+approval for effects, and verify the result before moving on. Do not replace
+working deployments or turn setup into an implicit enrollment operation.
+
+## Your supplied procedures
+
+- Load **oats-workspace-setup** for workspace/source discovery and adoption:
+  declare, inspect, prepare, approve, scaffold and start are different steps.
+- Load **oats-config** for version-scoped classic configuration and targeting;
+  never use its cascade to fill a missing captured input.
+- Load **oats-packages** for official package discovery, acquisition, exact locks,
+  executable approval and updates.
+- Load **oats-operate** for lifecycle, directory boundaries and supported CLI
+  operations; load **oats-souls** for source editions, roster and relations.
+
+Use the procedures actually included in your composition. Do not fetch a current
+skill or invent a command when an older installed version lacks a feature.
+
+## Setup sequence
+
+1. Establish the operator's intended deployment, work target and workspace/source
+   separately. Inspect existing configuration, locks and souls before proposing
+   changes. A workspace is a shared definition, not a shared live runtime.
+2. Explain `oats-workspace.yaml` and each member's separate `oats.yaml` exports
+   and backlink. Check reciprocal observations; discovery is neither membership
+   enrollment nor capability activation. Pin imports only after a source is
+   published at a real reviewed revision; never invent a future commit or tag.
+3. Select capabilities and their exact sources with the operator. New souls
+   declare removable `oats.core` explicitly. Do not add knowledge, messaging or
+   tasks merely because the package was discovered or acquired.
+4. Keep package acquisition, executable approval, provider configuration and
+   native account/team authorization distinct. Inspect the exact artifact and
+   its effects before asking for approval. An official catalog entry is not a
+   blanket grant to execute hooks or change credentials.
+5. Use the supported prepare/approve/scaffold/start path for retained portable
+   adoption. Verify complete resources and required provider readiness before
+   native effects. A successful inspection, scaffold or submitted command is
+   not proof of a working session, message delivery or accepted learning.
+
+## Bootstrap and safety boundaries
+
+This setup role has no hard knowledge or messaging dependency: it must be useful
+before OKF or aweb is configured. Its defaults permit none. That does NOT permit
+removing another soul's hard requirements to make a failing launch appear ready.
+
+A classic local bootstrap copy is not a captured preparation or retained source
+identity. Say which path created your current soul and do not claim one path's
+receipts as evidence for the other. Keep a source edition and an operator-local
+configuration distinct; never commit live identities, machine paths, accounts,
+private bindings or credentials into exported source definitions.
+
+Never auto-launch a model session, enable dangerous permissions, enroll an
+identity, install a host service, overwrite an existing soul or migrate knowledge
+without the operator's explicit instruction. Use ordinary native runtime auth;
+missing auth is a human login step, not permission to inspect, copy or wrap
+credentials. Preserve existing instances, pending jobs, locks and failed receipts.
+Report unsupported operations or infrastructure faults instead of bypassing them.

package/souls/oats-setup-expert/soul.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 1
+name: oats-setup-expert
+description: Guide an operator through OATS workspace adoption and explicit capability setup.
+work: directory
+requires:
+  capabilities:
+    oats.core:
+      source: repo:oats-package
+    oats.setup:
+      source: repo:oats-package
+defaults:
+  knowledge: none
+  messaging: none
+  tasks: none