@awebai/oats 0.24.1 → 0.24.3

package/lib/prepared-bindings.mjs

@@ -37,24 +37,34 @@ export function prepareProviderBindings({seed,plan,manifests,declarations},invok
   const normalized=new Map(),problems=[],requirements=[...plan.requirements],candidates=[...plan.candidates];
   const settingsFor=id=>Object.fromEntries(Object.entries(plan.settings[id] ?? {}).map(([name,key])=>[name,plan.choices[key].value]));
   const run=(id,phase,input)=>invoke({artifacts:seed.artifacts,capability:id,phase,settings:settingsFor(id),input});
-  const refuse=error=>({code:safeCodes.has(error?.code)?error.code:'provider-not-qualified',message:'provider binding could not be prepared',origins:[]});
+  const originsFor=id=>[...new Map((plan.capabilities[id]?.choiceKeys ?? []).flatMap(key=>{
+    const choice=plan.choices[key];return choice?.selectedBy?[choice.selectedBy]:[];
+  }).map(origin=>[canonicalJson(origin),origin])).values()];
+  const problem=(slot,id,code,message,origins=originsFor(id))=>({code,message,origins,slot,capability:id});
+  const refuse=(slot,id,phase,error)=>problem(slot,id,safeCodes.has(error?.code)?error.code:'provider-not-qualified',
+    `${id} ${slot} ${phase} binding could not be prepared`); // Never provider free text.
   for (const [id,manifest] of manifests) {
     if (!Object.hasOwn(seed.artifacts.capabilities,id) || !manifest.layer) continue;
-    if (plan.providers[manifest.layer] !== id) problems.push({code:'needs-configuration',message:'fundamental capability must be selected in its own layer',origins:[]});
+    if (plan.providers[manifest.layer] !== id) problems.push(problem(manifest.layer,id,'needs-configuration','fundamental capability must be selected in its own layer'));
   }
-  if (problems.length) return {plan,seed,problems};
   for (const [slot,id] of Object.entries(plan.providers)) {
     if (id === null) continue;
     const manifest=manifests.get(id);
-    if (manifest?.layer !== slot || !manifest.binding) { problems.push({code:'provider-not-qualified',message:'selected provider has no matching binding interface',origins:[]});continue; }
+    if (manifest?.layer !== slot) { problems.push(problem(slot,id,'provider-not-qualified',`${id} does not declare the selected ${slot} layer`));continue; }
+    if (!manifest.binding) { problems.push(problem(slot,id,'provider-not-qualified',`${id}@${manifest.version} declares no binding interface; ${slot} cannot be prepared`));continue; }
     try {
       const value=run(id,'normalize',{declarations,context:seed.context});
       normalized.set(slot,{id,value}); requirements.push(...value.requirements);candidates.push(...value.candidates);
-    } catch(error) { problems.push(refuse(error)); }
+    } catch(error) { problems.push(refuse(slot,id,'normalize',error)); }
   }
-  if (problems.length) return {plan,seed,problems};
+  // One unsupported slot must not mask another slot's normalized requirements
+  // or invalid choices. The same resolver still decides every value.
   const resolved=resolveChoices({requirements,candidates});
-  if (resolved.status !== 'resolved') return {plan:{...plan,...resolved},seed,problems:resolved.problems};
+  for (const item of resolved.problems) {
+    const slot=Object.keys(plan.providers).find(slot=>bindingField(item.key,slot));
+    if (!slot) throw oatsError('invalid-binding-output','provider choice problem has no owned binding slot');
+    problems.push({...item,slot,capability:plan.providers[slot]});
+  }
   const nextPlan={...plan,...resolved,requirements,candidates},bindings=Object.create(null);
   let messagingChoice={schemaVersion:1,enabled:false};
   const known=[];
@@ -64,6 +74,7 @@ export function prepareProviderBindings({seed,plan,manifests,declarations},invok
   }
   const witnessed=origin=>bindingOriginWitnessed(origin,declarations) || known.some(candidate=>same(candidate,origin));
   for (const [slot,{id,value}] of normalized) {
+    if (resolved.problems.some(item=>bindingField(item.key,slot))) continue;
     try {
       const choices=Object.fromEntries(Object.entries(resolved.choices).filter(([key])=>bindingField(key,slot)));
       const bound=run(id,'bind',{model:value.model,choices,context:seed.context});
@@ -72,7 +83,9 @@ export function prepareProviderBindings({seed,plan,manifests,declarations},invok
       }
       bindings[slot]=bound.binding;
       if (slot === 'messaging') messagingChoice=bound.messagingChoice;
-    } catch(error) { problems.push(refuse(error)); }
+    } catch(error) { problems.push(refuse(slot,id,'bind',error)); }
   }
+  nextPlan.problems=problems;
+  nextPlan.status=problems.some(item=>item.code==='requirement-conflict')?'conflict':problems.length?'needs-configuration':'resolved';
   return {plan:nextPlan,seed:{...seed,choices:resolved.choices,bindings,messagingChoice},problems};
 }

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.3",
   "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