@agilno-tech/rivet 0.1.0-alpha.0

package/src/install/project-runtime.js

@@ -0,0 +1,142 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { basename, dirname, join, resolve, relative, isAbsolute } from 'node:path';
+import { CliError } from '../cli/output.js';
+import { createMutationGuard, ensureContainedDirectory, findProjectRoot, withPinnedTargetDirectory } from '../commands/install.js';
+import { inspectManagedInstall, managedInstall } from './managed.js';
+import { acquireLock, recoverAbandonedLock, StaleLockError } from '../state/lock.js';
+import integrity from './runtime-integrity.cjs';
+import { launcher, reference, runtimeSkill } from './project-reference.js';
+const { runtimeIntegrity } = integrity;
+const NAME = '.rivet.cjs', HASH = /^[a-f0-9]{64}$/;
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const fail = message => { throw new CliError(message, 'REPOSITORY_CONFLICT'); };
+function regular(file, fs, maximum = 16 * 1024 * 1024) {
+  const before = fs.lstatSync(file);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > maximum) fail('Project runtime contains an unsafe file.');
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    const opened = fs.fstatSync(fd), bytes = Buffer.alloc(before.size + 1), length = fs.readSync(fd, bytes, 0, bytes.length, 0), after = fs.fstatSync(fd);
+    if (opened.dev !== before.dev || opened.ino !== before.ino || length !== before.size || after.size !== before.size
+      || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) fail('Project runtime file changed during validation.');
+    return bytes.subarray(0, length);
+  } finally { fs.closeSync(fd); }
+}
+function sourceSnapshot(packageRoot, fs) {
+  const metadataBytes = regular(join(packageRoot, 'package.json'), fs, 65536), pkg = JSON.parse(metadataBytes);
+  if (pkg.name !== '@agilno-tech/rivet' || typeof pkg.version !== 'string' || !Array.isArray(pkg.files)
+    || !['bin/cli.js', './bin/cli.js'].includes(pkg.bin?.rivet)
+    || ['prepare', 'prepack', 'postpack'].some(key => Object.hasOwn(pkg.scripts ?? {}, key))) fail('The running Rivet package cannot be safely pinned.');
+  const files = new Map([['package.json', { bytes: metadataBytes, mode: 0o644 }]]); let total = metadataBytes.length;
+  const visit = ref => {
+    if (typeof ref !== 'string' || !ref || isAbsolute(ref) || /[\u0000-\u001f\u007f\\*?]/.test(ref)
+      || ref.split('/').some(part => !part || part === '.' || part === '..' || part === 'node_modules' || part === '.git')) fail('Unsupported runtime package file selection.');
+    const file = join(packageRoot, ref), stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) fail('The running Rivet package contains unsupported links.');
+    if (stat.isDirectory()) { for (const child of fs.readdirSync(file).sort()) visit(ref + '/' + child); return; }
+    const bytes = regular(file, fs);total += bytes.length;
+    if (files.size >= 20000 || total > 64 * 1024 * 1024) fail('The running Rivet package exceeds snapshot limits.');
+    files.set(ref, { bytes, mode: stat.mode & 0o111 ? 0o755 : 0o644 });
+  };
+  for (const ref of pkg.files) visit(ref.replace(/\/$/, ''));
+  const entries = [...files].sort(([a],[b]) => Buffer.compare(Buffer.from(a),Buffer.from(b)));
+  return { pkg, files: entries, id: hash(JSON.stringify(entries.map(([path, file]) => ({ path, mode: file.mode, sha256: hash(file.bytes) })))) };
+}
+async function command(executable, args, options) {
+  return new Promise((resolveCommand, reject) => {
+    let output = '', errors = '';const child = spawn(executable, args, { cwd: options.cwd, env: options.env, shell: false, detached: true, stdio: ['ignore','pipe','pipe'] });
+    const kill = () => { try { process.kill(-child.pid, 'SIGKILL'); } catch {} };
+    const timer = setTimeout(kill, 180000);const abort = () => kill();options.signal?.addEventListener('abort', abort, { once: true });
+    if (options.signal?.aborted) kill();
+    child.stdout.on('data', bytes => { output += bytes; if (output.length > 2 * 1024 * 1024) kill(); });
+    child.stderr.on('data', bytes => { errors += bytes; if (errors.length > 2 * 1024 * 1024) kill(); });
+    child.on('error', reject);child.on('close', code => { clearTimeout(timer); options.signal?.removeEventListener('abort', abort); if (code !== 0 || options.signal?.aborted) reject(new Error('Private runtime package preparation failed or was interrupted.')); else resolveCommand(output); });
+  });
+}
+async function lock(path) {
+  try { return await acquireLock(path); }
+  catch (error) { if (!(error instanceof StaleLockError)) throw error; await recoverAbandonedLock(path); return acquireLock(path); }
+}
+function verifyReference(root, before, fs) {
+  const after = reference(root, fs);
+  if (Boolean(before) !== Boolean(after) || (before && (before.id !== after.id || before.dev !== after.dev || before.ino !== after.ino))) fail('Project runtime reference changed during installation.');
+}
+export async function projectRuntimeInstall(parsed, dependencies) {
+  if (Number.parseInt(process.versions.node.split('.')[0], 10) < 22) throw new CliError('Node.js 22 or newer is required for a project runtime. Select a supported Node runtime and retry installation.', 'INVALID_INPUT');
+  const { fs } = dependencies;
+  if (parsed.operands?.length || parsed.flags.global || parsed.flags.all || Object.keys(parsed.flags).some(key => !['project-runtime','minimal','project','target','claude','codex','json'].includes(key))) throw new CliError('Use install/uninstall --project-runtime [--project=<path>] [--target=both|claude|codex].', 'INVALID_INPUT');
+  const selected = parsed.flags.project === undefined ? findProjectRoot(dependencies.cwd(), fs) : resolve(dependencies.cwd(), parsed.flags.project);
+  if (!selected || fs.lstatSync(selected).isSymbolicLink() || !fs.lstatSync(selected).isDirectory()) fail('Select an existing project directory.');
+  const root = fs.realpathSync(selected), home = fs.realpathSync(dependencies.home());
+  const projectGuard = createMutationGuard(root, root, fs), rootIdentity = fs.lstatSync(root);
+  const cache = join(home,'.cache','rivet','project-runtimes'), cacheGuard = createMutationGuard(home,cache,fs);
+  const before = reference(root, fs), source = sourceSnapshot(dependencies.packageRoot,fs);
+  const skillBytes = regular(join(dependencies.packageRoot,'templates','harness','SKILL.md'),fs,512*1024);
+  const managedParsed = { ...parsed, flags: { ...parsed.flags, minimal: true, project: root } };
+  const quiet = {log(){},error(){},json(){}};
+  // Validate every selected owned target before any package installation.
+  inspectManagedInstall(managedParsed,{...dependencies,managedSkillBytes:runtimeSkill(skillBytes,before?.id ?? source.id)});
+  const controller = new AbortController(), abort=()=>controller.abort();process.on('SIGINT',abort);process.on('SIGTERM',abort);
+  let projectLock, cacheLock, stage;
+  const completed = await (async () => {
+  try {
+    projectGuard.assertPath(root);projectLock = await lock(join(root,'.rivet-project-runtime.lock'));
+    verifyReference(root,before,fs);
+    if (parsed.command === 'uninstall') {
+      await managedInstall(managedParsed,{...dependencies,output:quiet});
+      // A remaining managed harness still needs the reference.
+      const keep = ['.claude','.agents'].some(target=>fs.existsSync(join(root,target,'skills','rivet','.rivet-install.json')));
+      if (!keep && before) withPinnedTargetDirectory(root,rootIdentity,fs,()=>{verifyReference(root,before,fs);fs.unlinkSync(NAME);});
+      const result={scope:'project',runtimeReference:keep?'retained':'removed',cache:'retained'};
+      return result;
+    }
+    const cacheIdentity=ensureContainedDirectory(cacheGuard,fs);fs.chmodSync(cache,0o700);cacheLock=await lock(join(cache,'.install.lock'));
+    cacheGuard.assertPath(cache);
+    const indexFile=join(cache,`source-${source.id}-${process.platform}-${process.arch}.json`);
+    let runtime;
+    if(fs.existsSync(indexFile)){
+      const id=JSON.parse(regular(indexFile,fs,1024)).runtimeId;if(!HASH.test(id))fail('Private runtime cache index is invalid.');
+      runtime=runtimeIntegrity(join(cache,id),id,source.id);if(runtime.metadata.sourceDigest!==source.id)fail('Private runtime source identity changed.');
+    }else{
+      stage=join(cache,`.stage-${randomUUID()}`);fs.mkdirSync(stage,{mode:0o700});const snapshot=join(stage,'source'),destination=join(stage,'runtime');fs.mkdirSync(snapshot);fs.mkdirSync(destination);
+      for(const [ref,file] of source.files){const target=join(snapshot,ref);fs.mkdirSync(dirname(target),{recursive:true});fs.writeFileSync(target,file.bytes,{flag:'wx',mode:file.mode});}
+      const env={...dependencies.env,PATH:dependencies.env?.PATH??process.env.PATH,npm_config_ignore_scripts:'true',npm_config_update_notifier:'false'};
+      const run=dependencies.runtimeCommand??command, options={cwd:'.',env,signal:controller.signal};
+      const packed=JSON.parse(await withPinnedTargetDirectory(snapshot,fs.lstatSync(snapshot),fs,()=>run('npm',['pack','--ignore-scripts','--json','--pack-destination','..'],options)));
+      if(!Array.isArray(packed)||packed.length!==1||typeof packed[0].filename!=='string'||!/^[A-Za-z0-9._-]+\.tgz$/.test(packed[0].filename))fail('Private package preparation returned an invalid artifact.');
+      const artifact=join(stage,packed[0].filename),artifactDigest=hash(regular(artifact,fs,64*1024*1024));
+      await withPinnedTargetDirectory(stage,fs.lstatSync(stage),fs,()=>run('npm',['install','--prefix','runtime','--omit=dev','--ignore-scripts','--install-links','--no-audit','--no-fund','./'+packed[0].filename],options));
+      if(controller.signal.aborted)fail('Project runtime installation was interrupted; existing reference preserved.');
+      const metadata={schemaVersion:1,sourceDigest:source.id,artifactDigest,package:{name:source.pkg.name,version:source.pkg.version},platform:process.platform,architecture:process.arch};
+      fs.writeFileSync(join(destination,'.rivet-runtime.json'),JSON.stringify(metadata)+'\n',{flag:'wx',mode:0o600});runtime=runtimeIntegrity(destination);
+      withPinnedTargetDirectory(cache,cacheIdentity,fs,()=>{
+        cacheGuard.assertPath(cache);if(fs.existsSync(runtime.id))runtimeIntegrity(join(cache,runtime.id),runtime.id);else fs.renameSync(join(relative(cache,stage),'runtime'),runtime.id);
+        if(fs.existsSync(basename(indexFile)))fail('Private runtime cache index changed during preparation.');
+        const indexStage=join(relative(cache,stage),'index.json');
+        fs.writeFileSync(indexStage,JSON.stringify({runtimeId:runtime.id})+'\n',{flag:'wx',mode:0o600});fs.renameSync(indexStage,basename(indexFile));
+      });
+    }
+    const managedDependencies={...dependencies,managedSkillBytes:runtimeSkill(skillBytes,source.id),output:quiet};
+    verifyReference(root,before,fs);inspectManagedInstall(managedParsed,managedDependencies);
+    // Reference first: any partial skill update still has a working pinned command.
+    withPinnedTargetDirectory(root,rootIdentity,fs,()=>{
+      verifyReference(root,before,fs);const name=`.rivet-reference-${randomUUID()}.tmp`;
+      try{fs.writeFileSync(name,launcher(source.id),{flag:'wx',mode:0o644});fs.renameSync(name,NAME);}finally{if(fs.existsSync(name))fs.unlinkSync(name);}
+    });
+    try{await managedInstall(managedParsed,managedDependencies);}catch(error){throw new CliError('Pinned runtime reference is installed, but harness instruction installation is incomplete. Existing user edits were preserved; retry after resolving the reported conflict.','REPOSITORY_CONFLICT',{cause:error});}
+    const result={scope:'project',runtimeId:runtime.id,sourceDigest:source.id,reference:join(root,NAME),cache:join(cache,runtime.id),invocation:'node .rivet.cjs'};
+    return result;
+  }catch(error){if(error instanceof CliError)throw error;throw new CliError('Project runtime installation stopped. Existing application files are preserved. Inspect the private cache or installation lock before retrying.','REPOSITORY_CONFLICT',{cause:error});}
+  finally{
+    let cleanupError;
+    if(stage){try{cacheGuard.assertPath(stage);fs.rmSync(stage,{recursive:true,force:true});}catch(error){cleanupError=error;}}
+    try{await cacheLock?.release();}catch(error){cleanupError??=error;}
+    try{await projectLock?.release();}catch(error){cleanupError??=error;}
+    process.off('SIGINT',abort);process.off('SIGTERM',abort);
+    if(cleanupError)throw new CliError('Project runtime operation may have completed, but private staging or lock cleanup is incomplete. Inspect the project reference and private cache before retrying.','REPOSITORY_CONFLICT',{cause:cleanupError});
+  }
+  })();
+  if(parsed.flags.json)dependencies.output.json({ok:true,command:parsed.command,result:completed});
+  else dependencies.output.log(parsed.command==='uninstall'?'Removed selected owned project runtime instructions. Shared runtime cache retained.':'Pinned project runtime installed. From the project root: node .rivet.cjs setup. No global Rivet installation is required.');
+  return 0;
+}

package/src/install/runtime-integrity.cjs

@@ -0,0 +1,141 @@
+// Self-contained so the generated project reference can verify a cache before
+// importing any cached JavaScript. Keep all dependencies inside this function.
+function runtimeIntegrity(root, expectedId, expectedSource) {
+  const fs = require('node:fs'), path = require('node:path'), crypto = require('node:crypto'), os = require('node:os');
+  const fail = () => { throw new Error('Pinned Rivet runtime is missing or changed. Reinstall the approved project runtime.'); };
+  const digest = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+  const inside = value => value === root || (value.startsWith(root + path.sep));
+  const rootStat = fs.lstatSync(root);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || fs.realpathSync(root) !== root) fail();
+  const manifestPath = path.join(root, '.rivet-runtime.json');
+  const regular = (file, maximum) => {
+    const before = fs.lstatSync(file);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > maximum) fail();
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const opened = fs.fstatSync(fd);
+      if (opened.dev !== before.dev || opened.ino !== before.ino) fail();
+      const bytes = Buffer.alloc(before.size + 1), length = fs.readSync(fd, bytes, 0, bytes.length, 0);
+      const after = fs.fstatSync(fd);
+      if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) fail();
+      return bytes.subarray(0, length);
+    } finally { fs.closeSync(fd); }
+  };
+  const metadata = JSON.parse(regular(manifestPath, 16384).toString('utf8'));
+  if (metadata.schemaVersion !== 1 || metadata.platform !== process.platform || metadata.architecture !== process.arch
+    || !/^[a-f0-9]{64}$/.test(metadata.sourceDigest) || !/^[a-f0-9]{64}$/.test(metadata.artifactDigest)
+    || !['@agilno-tech/rivet', '@agilno/rivet'].includes(metadata.package?.name)) fail();
+  const entries = []; let total = 0;
+  const visit = (directory, relative = '') => {
+    for (const name of fs.readdirSync(directory).sort()) {
+      if (name === '.rivet-runtime.json' && !relative) continue;
+      if (!name || /[\u0000-\u001f\u007f\\]/.test(name)) fail();
+      const ref = relative ? relative + '/' + name : name, file = path.join(directory, name), stat = fs.lstatSync(file);
+      if (entries.length >= 20000) fail();
+      if (stat.isSymbolicLink()) {
+        if (!ref.startsWith('node_modules/') || !inside(fs.realpathSync(file))) fail();
+        entries.push({ path: ref, kind: 'link', target: fs.readlinkSync(file) });
+      } else if (stat.isDirectory()) { entries.push({ path: ref, kind: 'directory' }); visit(file, ref); }
+      else {
+        const bytes = regular(file, 16 * 1024 * 1024); total += bytes.length;
+        if (total > 128 * 1024 * 1024) fail();
+        entries.push({ path: ref, kind: 'file', executable: Boolean(stat.mode & 0o111), sha256: digest(bytes) });
+      }
+    }
+  };
+  visit(root);
+  const id = digest(JSON.stringify({ metadata, entries }));
+  if (expectedId !== undefined && id !== expectedId) fail();
+  const packageRoot = path.join(root, 'node_modules', ...metadata.package.name.split('/'));
+  const entry = path.join(packageRoot, 'bin', 'cli.js');
+  if (!inside(fs.realpathSync(entry))) fail();
+  const pkg = JSON.parse(regular(path.join(packageRoot, 'package.json'), 65536));
+  if (pkg.name !== metadata.package.name || pkg.version !== metadata.package.version || !Array.isArray(pkg.files)) fail();
+  // Bind the installed Rivet code to the portable project source pin. Runtime
+  // dependencies and platform remain independently pinned in the private cache.
+  const sourceFiles = new Map();
+  const sourceVisit = ref => {
+    if (typeof ref !== 'string' || !ref || path.isAbsolute(ref) || /[\u0000-\u001f\u007f\\*?]/.test(ref)
+      || ref.split('/').some(part => !part || part === '.' || part === '..' || part === '.git' || part === 'node_modules')) fail();
+    const file = path.join(packageRoot, ref), stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) fail();
+    if (stat.isDirectory()) { for (const name of fs.readdirSync(file).sort()) sourceVisit(ref + '/' + name); return; }
+    sourceFiles.set(ref, { path: ref, mode: stat.mode & 0o111 ? 0o755 : 0o644, sha256: digest(regular(file,16*1024*1024)) });
+  };
+  sourceVisit('package.json');
+  for (const ref of pkg.files) sourceVisit(ref.replace(/\/$/, ''));
+  const sourceDigest = digest(JSON.stringify([...sourceFiles.values()].sort((a,b)=>Buffer.compare(Buffer.from(a.path),Buffer.from(b.path)))));
+  if (sourceDigest !== metadata.sourceDigest || (expectedSource !== undefined && sourceDigest !== expectedSource)) fail();
+  return { id, entry, metadata };
+}
+// Frozen ownership renderer for unchanged project references from the former scope.
+// Do not edit this function: its exact source bytes are embedded in those files.
+const legacyRuntimeIntegrity = function runtimeIntegrity(root, expectedId, expectedSource) {
+  const fs = require('node:fs'), path = require('node:path'), crypto = require('node:crypto'), os = require('node:os');
+  const fail = () => { throw new Error('Pinned Rivet runtime is missing or changed. Reinstall the approved project runtime.'); };
+  const digest = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+  const inside = value => value === root || (value.startsWith(root + path.sep));
+  const rootStat = fs.lstatSync(root);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || fs.realpathSync(root) !== root) fail();
+  const manifestPath = path.join(root, '.rivet-runtime.json');
+  const regular = (file, maximum) => {
+    const before = fs.lstatSync(file);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > maximum) fail();
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const opened = fs.fstatSync(fd);
+      if (opened.dev !== before.dev || opened.ino !== before.ino) fail();
+      const bytes = Buffer.alloc(before.size + 1), length = fs.readSync(fd, bytes, 0, bytes.length, 0);
+      const after = fs.fstatSync(fd);
+      if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) fail();
+      return bytes.subarray(0, length);
+    } finally { fs.closeSync(fd); }
+  };
+  const metadata = JSON.parse(regular(manifestPath, 16384).toString('utf8'));
+  if (metadata.schemaVersion !== 1 || metadata.platform !== process.platform || metadata.architecture !== process.arch
+    || !/^[a-f0-9]{64}$/.test(metadata.sourceDigest) || !/^[a-f0-9]{64}$/.test(metadata.artifactDigest)
+    || metadata.package?.name !== '@agilno/rivet') fail();
+  const entries = []; let total = 0;
+  const visit = (directory, relative = '') => {
+    for (const name of fs.readdirSync(directory).sort()) {
+      if (name === '.rivet-runtime.json' && !relative) continue;
+      if (!name || /[\u0000-\u001f\u007f\\]/.test(name)) fail();
+      const ref = relative ? relative + '/' + name : name, file = path.join(directory, name), stat = fs.lstatSync(file);
+      if (entries.length >= 20000) fail();
+      if (stat.isSymbolicLink()) {
+        if (!ref.startsWith('node_modules/') || !inside(fs.realpathSync(file))) fail();
+        entries.push({ path: ref, kind: 'link', target: fs.readlinkSync(file) });
+      } else if (stat.isDirectory()) { entries.push({ path: ref, kind: 'directory' }); visit(file, ref); }
+      else {
+        const bytes = regular(file, 16 * 1024 * 1024); total += bytes.length;
+        if (total > 128 * 1024 * 1024) fail();
+        entries.push({ path: ref, kind: 'file', executable: Boolean(stat.mode & 0o111), sha256: digest(bytes) });
+      }
+    }
+  };
+  visit(root);
+  const id = digest(JSON.stringify({ metadata, entries }));
+  if (expectedId !== undefined && id !== expectedId) fail();
+  const entry = path.join(root, 'node_modules', '@agilno', 'rivet', 'bin', 'cli.js');
+  if (!inside(fs.realpathSync(entry))) fail();
+  const pkg = JSON.parse(regular(path.join(root, 'node_modules', '@agilno', 'rivet', 'package.json'), 65536));
+  if (pkg.name !== metadata.package.name || pkg.version !== metadata.package.version || !Array.isArray(pkg.files)) fail();
+  // Bind the installed Rivet code to the portable project source pin. Runtime
+  // dependencies and platform remain independently pinned in the private cache.
+  const packageRoot = path.join(root, 'node_modules', '@agilno', 'rivet');
+  const sourceFiles = new Map();
+  const sourceVisit = ref => {
+    if (typeof ref !== 'string' || !ref || path.isAbsolute(ref) || /[\u0000-\u001f\u007f\\*?]/.test(ref)
+      || ref.split('/').some(part => !part || part === '.' || part === '..' || part === '.git' || part === 'node_modules')) fail();
+    const file = path.join(packageRoot, ref), stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) fail();
+    if (stat.isDirectory()) { for (const name of fs.readdirSync(file).sort()) sourceVisit(ref + '/' + name); return; }
+    sourceFiles.set(ref, { path: ref, mode: stat.mode & 0o111 ? 0o755 : 0o644, sha256: digest(regular(file,16*1024*1024)) });
+  };
+  sourceVisit('package.json');
+  for (const ref of pkg.files) sourceVisit(ref.replace(/\/$/, ''));
+  const sourceDigest = digest(JSON.stringify([...sourceFiles.values()].sort((a,b)=>Buffer.compare(Buffer.from(a.path),Buffer.from(b.path)))));
+  if (sourceDigest !== metadata.sourceDigest || (expectedSource !== undefined && sourceDigest !== expectedSource)) fail();
+  return { id, entry, metadata };
+};
+module.exports = { runtimeIntegrity, legacyRuntimeIntegrity };

package/src/integrations/capabilities.js

@@ -0,0 +1,69 @@
+export class IntegrationError extends Error {
+  constructor(reason = 'INPUT') {
+    super(`Integration ${reason.toLowerCase().replaceAll('_', ' ')}. Check project scope, provider selection, authentication and tool inventory.`);
+    this.name = 'IntegrationError';
+    this.code = `ERR_INTEGRATION_${reason}`;
+    this.safeMessage = this.message;
+  }
+}
+export function fail(reason) { throw new IntegrationError(reason); }
+export function snapshot(value, maxBytes = 65536) {
+  // Accept plain JSON data only. Never invoke getters or toJSON methods.
+  let nodes = 0;
+  const walk = (item, depth = 0) => {
+    if (++nodes > 10000 || depth > 20) fail('INPUT');
+    if (item === null || typeof item === 'boolean' || typeof item === 'string') return item;
+    if (typeof item === 'number' && Number.isFinite(item)) return item;
+    if (!item || typeof item !== 'object' || ![Object.prototype, Array.prototype, null].includes(Object.getPrototypeOf(item))) fail('INPUT');
+    const array = Array.isArray(item);
+    if (array && (item.length > 10000 || Object.keys(item).length !== item.length
+      || Object.keys(item).some((key,index) => key !== String(index)))) fail('INPUT');
+    const result = array ? [] : Object.create(null);
+    for (const key of Reflect.ownKeys(item)) {
+      if (Array.isArray(item) && key === 'length') continue;
+      if (typeof key !== 'string' || ['__proto__','constructor','prototype'].includes(key)) fail('INPUT');
+      const descriptor = Object.getOwnPropertyDescriptor(item, key);
+      if (!descriptor?.enumerable || !Object.hasOwn(descriptor,'value')) fail('INPUT');
+      result[key] = walk(descriptor.value, depth + 1);
+    }
+    return result;
+  };
+  try {
+    const result = walk(value);
+    if (Buffer.byteLength(JSON.stringify(result)) > maxBytes) fail('INPUT');
+    return result;
+  } catch { fail('INPUT'); }
+}
+export function fields(value, allowed, required = allowed) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(key => !allowed.includes(key)) || required.some(key => !Object.hasOwn(value,key))) fail('INPUT');
+}
+export function safeUrl(value, { endpoint = false } = {}) {
+  try {
+    if (typeof value !== 'string' || value.length > 2048 || /[\s\u0000-\u001f]/.test(value)) fail('INPUT');
+    const url = new URL(value);
+    if (!['https:','http:'].includes(url.protocol) || url.username || url.password || url.hash) fail('INPUT');
+    const secretKey = /(?:password|passwd|secret|api[-_]?key|authorization|cookie|credential|access[-_]?token|api[-_]?token|token)/i;
+    const secretValue = /^(?:bearer\s+|basic\s+|gh[pousr]_|github_pat_|sk-[A-Za-z0-9]|xox[baprs]-|AKIA[0-9A-Z]{16})/i;
+    for (const [key, value] of url.searchParams) {
+      if (secretKey.test(key) || secretValue.test(value)) fail('INPUT');
+      if (!endpoint && (!['node-id','pageId'].includes(key) || !/^[A-Za-z0-9:_-]{1,128}$/.test(value))) fail('INPUT');
+    }
+    if (!endpoint && url.protocol !== 'https:') fail('INPUT');
+    let path = url.pathname;
+    for (let pass = 0; pass < 4; pass += 1) {
+      const decoded = decodeURIComponent(path);
+      if (decoded === path) break;
+      path = decoded;
+    }
+    if (/%[0-9a-f]{2}/i.test(path)) fail('INPUT');
+    for (const component of path.split('/')) {
+      if (secretValue.test(component) || (/[=:]/.test(component) && secretKey.test(component.split(/[=:]/)[0]))) fail('INPUT');
+    }
+    return url;
+  } catch { fail('INPUT'); }
+}
+export function negotiateCapabilities(provider, inventory) {
+  const tools = provider.tools ?? [];
+  return tools.filter(tool => inventory?.tools.includes(tool));
+}

package/src/integrations/host-observation.js

@@ -0,0 +1,26 @@
+import { containsSecretMaterial } from '../clients/contract.js';
+import { createHash } from 'node:crypto';
+import { fail, fields, safeUrl, snapshot } from './capabilities.js';
+import { deepFreeze } from '../config/defaults.js';
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+export function normalizeHostObservation(input, { provider, projectId }) {
+  const value = snapshot(input);
+  if (containsSecretMaterial(JSON.stringify(value))) fail('INPUT');
+  fields(value,['schemaVersion','providerId','projectId','tool','resourceId','sourceUrl','revision','capturedAt','content']);
+  if (value.schemaVersion !== 1 || value.providerId !== provider.id || value.projectId !== projectId
+    || provider.transport !== 'harness-mcp' || provider.mode === 'disabled'
+    || (provider.projectIds?.length && !provider.projectIds.includes(projectId))
+    || !provider.tools?.includes(value.tool)
+    || (provider.resourceIds?.length && !provider.resourceIds.includes(value.resourceId))) fail('INPUT');
+  for (const key of ['resourceId','revision','capturedAt']) {
+    if (typeof value[key] !== 'string' || !value[key].length || value[key].length > 256 || /[\u0000-\u001f]/.test(value[key])) fail('INPUT');
+  }
+  if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{3})?Z$/.test(value.capturedAt) || !Number.isFinite(Date.parse(value.capturedAt))) fail('INPUT');
+  const url = safeUrl(value.sourceUrl);
+  if (provider.endpoint && safeUrl(provider.endpoint, {endpoint:true}).origin !== url.origin) fail('INPUT');
+  return deepFreeze({...value,provider:provider.kind,transport:'harness-mcp',assurance:'harness-observed',contentDigest:createHash('sha256').update(canonical(value.content)).digest('hex')});
+}

package/src/integrations/registry.js

@@ -0,0 +1,56 @@
+import Ajv from 'ajv';
+import { readFileSync } from 'node:fs';
+import { deepFreeze } from '../config/defaults.js';
+import { fail, fields, negotiateCapabilities, safeUrl, snapshot } from './capabilities.js';
+const validate = new Ajv({strict:true}).compile(JSON.parse(readFileSync(new URL('../../schemas/integration.schema.json',import.meta.url))));
+export function createIntegrationRegistry({config,projectId,environment = {},host}) {
+  if (typeof projectId !== 'string' || !projectId || projectId.length > 200) fail('INPUT');
+  const providers = snapshot(config?.providers?.providers,262144);
+  if (!Array.isArray(providers) || providers.length > 64 || new Set(providers.map(p=>p.id)).size !== providers.length) fail('INPUT');
+  let inventory;
+  if (host !== undefined) {
+    inventory = snapshot(host);
+    fields(inventory,['projectId','providers']);
+    if (inventory.projectId !== projectId || !Array.isArray(inventory.providers) || inventory.providers.length > 64) fail('INPUT');
+    const ids = new Set();
+    for (const item of inventory.providers) {
+      fields(item,['id','authenticated','tools']);
+      if (!providers.some(p=>p.id===item.id) || ids.has(item.id) || typeof item.authenticated !== 'boolean'
+        || !Array.isArray(item.tools) || item.tools.length > 64 || item.tools.some(t=>typeof t!=='string'|| !/^[A-Za-z0-9_.:-]{1,128}$/.test(t))) fail('INPUT');
+      ids.add(item.id);
+    }
+  }
+  const rows = providers.map(raw => {
+    if (!validate(raw)) fail('INPUT');
+    const provider = {...raw,transport:raw.transport ?? 'direct-api'};
+    if (provider.endpoint) safeUrl(provider.endpoint, {endpoint:true});
+    const observed = inventory?.providers.find(item=>item.id===provider.id);
+    const tools = negotiateCapabilities(provider,observed);
+    let readiness; let remedy;
+    if (provider.mode === 'disabled') {readiness='disabled';remedy='Enable this integration only when needed.';}
+    else if (provider.projectIds?.length && !provider.projectIds.includes(projectId)) {readiness='out-of-scope';remedy='Select an integration configured for this project.';}
+    else if (provider.transport === 'local-cli') {readiness='unsupported-transport';remedy='Local CLI descriptors are not executable yet.';}
+    else if (provider.transport === 'harness-mcp') {
+      readiness = !observed ? 'host-unavailable' : !observed.authenticated ? 'authentication-unavailable' : !tools.length ? 'unsupported-tools' : 'host-observed';
+      remedy = readiness === 'host-observed' ? 'Host-reported access; not independently verified.' : 'Supply current project-scoped authenticated host inventory with configured tools.';
+    } else {
+      const refs=Object.values(provider.credentials ?? {});
+      const present=refs.length > 0 && refs.every(ref=>{
+        const value=Object.getOwnPropertyDescriptor(environment,ref)?.value;
+        return typeof value === 'string' && value.length > 0 && value.length <= 8192 && !/[\u0000\r\n]/.test(value);
+      });
+      readiness=present ? 'credentials-present' : 'authentication-unavailable';
+      remedy=present ? 'Credentials are present; network access has not been checked.' : 'Configure referenced environment credentials when this integration is needed.';
+    }
+    return deepFreeze({...provider,availableTools:tools,readiness,remedy,assurance:provider.transport === 'harness-mcp' && observed ? 'harness-observed' : 'configured'});
+  });
+  return Object.freeze({list:()=>rows.slice(),check:()=>rows.slice(),resolve(options) {
+    const query=snapshot(options); fields(query,['providerId','kind','capability','tool'],['capability']);
+    const matches=rows.filter(row=>(!query.providerId||row.id===query.providerId)&&(!query.kind||row.kind===query.kind)&&row.capabilities.includes(query.capability));
+    if(matches.length>1) fail('AMBIGUOUS');
+    if(matches.length!==1) fail('NOT_FOUND');
+    const selected=matches[0];
+    if(!['host-observed','credentials-present'].includes(selected.readiness) || (query.tool && !selected.availableTools.includes(query.tool))) fail('UNAVAILABLE');
+    return selected;
+  }});
+}

package/src/models/delegate.js

@@ -0,0 +1,102 @@
+import { createModelRegistry } from './registry.js';
+import { buildModelRequest, parseModelResponse } from './protocols.js';
+import { requestModelJson } from './transport.js';
+import { containsSecretMaterial } from '../clients/contract.js';
+const IMPLEMENTED = new Set(['anthropic', 'openai', 'gemini', 'ollama', 'openai-compatible']);
+const MESSAGES = Object.freeze({
+  'invalid-input': 'Invalid text delegation input.',
+  'unsupported-provider': 'This provider does not support direct text delegation.',
+  'unsupported-budget': 'A monetary limit cannot be enforced for this model profile. Remove maxCostUsd or use another workflow.',
+  'unsupported-timeout': 'Direct text delegation requires timeoutMs at most 120000.',
+  'sensitive-prompt': 'The prompt contains credential-shaped text. Remove secrets before delegation.',
+  'credential-unavailable': 'The configured model credential is missing or invalid.',
+  'aborted': 'Text delegation was cancelled.',
+  'timeout': 'Text delegation exceeded its deadline.',
+  'request-failed': 'The model request failed or returned an unsupported response. No fallback was attempted.',
+});
+export class ModelDelegationError extends Error {
+  constructor(reason) {
+    super(MESSAGES[reason] ?? MESSAGES['request-failed']);
+    this.name = 'ModelDelegationError'; this.reason = reason;
+    this.code = `ERR_MODEL_DELEGATION_${reason.replaceAll('-', '_').toUpperCase()}`;
+    this.safeMessage = this.message;
+  }
+}
+const fail = reason => { throw new ModelDelegationError(reason); };
+const ABORTED = Object.getOwnPropertyDescriptor(AbortSignal.prototype, 'aborted').get;
+const ADD = EventTarget.prototype.addEventListener, REMOVE = EventTarget.prototype.removeEventListener;
+function capture(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(input))) fail('invalid-input');
+  const output = {};
+  for (const key of Reflect.ownKeys(input)) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (!['profile','prompt','environment','signal','transport'].includes(key)
+      || !descriptor?.enumerable || !Object.hasOwn(descriptor,'value')) fail('invalid-input');
+    output[key] = descriptor.value;
+  }
+  return output;
+}
+
+export async function delegateText(input) {
+  let config, profile;
+  try {
+    config = capture(input);
+    profile = createModelRegistry().resolve(config.profile, { requiredCapabilities: ['text'] }).profile;
+  } catch { fail('invalid-input'); }
+  if (!IMPLEMENTED.has(profile.provider)) fail('unsupported-provider');
+  if (profile.maxCostUsd !== undefined) fail('unsupported-budget');
+  if (profile.timeoutMs > 120000) fail('unsupported-timeout');
+  if (typeof config.prompt !== 'string' || !config.prompt.trim() || config.prompt.includes('\0')
+    || Buffer.byteLength(config.prompt, 'utf8') > 64 * 1024) fail('invalid-input');
+  if (containsSecretMaterial(config.prompt)) fail('sensitive-prompt');
+  const environment = config.environment;
+  if (!environment || typeof environment !== 'object' || Array.isArray(environment)) fail('invalid-input');
+  let credential;
+  try {
+    if (profile.credentialEnv !== undefined) {
+      const value = Object.getOwnPropertyDescriptor(environment, profile.credentialEnv);
+      if (!value || !Object.hasOwn(value, 'value') || typeof value.value !== 'string'
+        || !/^[!-~]{1,4096}$/.test(value.value)) fail('credential-unavailable');
+      credential = value.value;
+    } else if (['anthropic','openai','gemini'].includes(profile.provider)) fail('credential-unavailable');
+  } catch { fail('credential-unavailable'); }
+  if (credential?.length >= 8 && config.prompt.includes(credential)) fail('sensitive-prompt');
+  const controller = new AbortController();
+  let timedOut = false, timer;
+  const deadline = Date.now() + profile.timeoutMs;
+  const abort = () => controller.abort();
+  try {
+    if (config.signal !== undefined) {
+      try {
+        if (Reflect.apply(ABORTED, config.signal, [])) fail('aborted');
+        Reflect.apply(ADD, config.signal, ['abort', abort, { once: true }]);
+        if (Reflect.apply(ABORTED, config.signal, [])) abort();
+      } catch (error) { if (error instanceof ModelDelegationError) throw error; fail('invalid-input'); }
+    }
+    timer = setTimeout(() => { timedOut = true; controller.abort(); }, profile.timeoutMs);
+    const request = buildModelRequest(profile, config.prompt, credential);
+    if (Date.now() >= deadline) fail('timeout');
+    const data = await requestModelJson({ provider: profile.provider, request, timeoutMs: profile.timeoutMs,
+      signal: controller.signal, ...(config.transport === undefined ? {} : { transport: config.transport }) });
+    if (controller.signal.aborted) fail(timedOut ? 'timeout' : 'aborted');
+    const result = parseModelResponse(profile, data);
+    if (Date.now() >= deadline) fail('timeout');
+    if (credential?.length >= 8 && JSON.stringify(result).includes(credential)) fail('request-failed');
+    if (typeof result.text !== 'string' || Buffer.byteLength(result.text) > 256 * 1024
+      || !Number.isSafeInteger(result.usage?.inputTokens) || result.usage.inputTokens < 0
+      || !Number.isSafeInteger(result.usage?.outputTokens) || result.usage.outputTokens < 0
+      || result.usage.outputTokens > profile.maxOutputTokens) fail('request-failed');
+    return Object.freeze({ provider: profile.provider, requestedModel: profile.model, model: result.model,
+      text: result.text, usage: Object.freeze({ ...result.usage }), verified: false });
+  } catch (error) {
+    if (error instanceof ModelDelegationError) throw error;
+    if (controller.signal.aborted) fail(timedOut ? 'timeout' : 'aborted');
+    fail('request-failed');
+  } finally {
+    clearTimeout(timer);
+    if (config.signal !== undefined) {
+      try { Reflect.apply(REMOVE, config.signal, ['abort', abort]); } catch {}
+    }
+  }
+}

package/src/models/profiles.js

@@ -0,0 +1,53 @@
+import { createModelRegistry } from './registry.js';
+
+const ID = /^[a-z][a-z0-9-]{0,63}$/;
+function fail() { throw new TypeError('Invalid model role configuration.'); }
+function record(input, allowed) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(input))) fail();
+  const keys = Reflect.ownKeys(input);
+  if (keys.length > 64) fail();
+  const result = Object.create(null);
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (typeof key !== 'string' || !ID.test(key) || ['constructor', 'prototype'].includes(key)
+      || (allowed && !allowed.includes(key)) || !descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) fail();
+    result[key] = descriptor.value;
+  }
+  return result;
+}
+
+// Explicit role selection is separate from automatic workflow-node routing.
+// Unassigned roles stay with the caller's active harness and spawn nothing.
+export function resolveRoleProfile(input, role) {
+  try {
+    if (typeof role !== 'string' || !ID.test(role)) fail();
+    // schemaVersion is the sole camel-case field in this versioned envelope.
+    const version = Object.getOwnPropertyDescriptor(input ?? {}, 'schemaVersion');
+    if (!version?.enumerable || !Object.hasOwn(version, 'value') || version.value !== 1) fail();
+    if (!input || ![Object.prototype, null].includes(Object.getPrototypeOf(input))
+      || Reflect.ownKeys(input).length !== 3) fail();
+    const profilesField = Object.getOwnPropertyDescriptor(input, 'profiles');
+    const rolesField = Object.getOwnPropertyDescriptor(input, 'roles');
+    if (!profilesField?.enumerable || !Object.hasOwn(profilesField, 'value')
+      || !rolesField?.enumerable || !Object.hasOwn(rolesField, 'value')) fail();
+    const registry = createModelRegistry();
+    const profiles = record(profilesField.value);
+    for (const key of Object.keys(profiles)) {
+      const resolved = registry.resolve(profiles[key], { requiredCapabilities: ['text'] });
+      if (resolved.provider.kind === 'harness') fail();
+      profiles[key] = resolved.profile;
+    }
+    const roles = record(rolesField.value);
+    for (const key of Object.keys(roles)) {
+      const target = record(roles[key], ['kind', 'profile', 'harness']);
+      if (target.kind === 'active-harness' && Object.keys(target).length === 1) roles[key] = Object.freeze({ kind: target.kind });
+      else if (target.kind === 'harness' && Object.keys(target).length === 2 && ['claude', 'codex'].includes(target.harness)) {
+        roles[key] = Object.freeze({ kind: target.kind, harness: target.harness });
+      } else if (target.kind === 'text' && Object.keys(target).length === 2 && typeof target.profile === 'string' && Object.hasOwn(profiles, target.profile)) {
+        roles[key] = Object.freeze({ kind: target.kind, profileId: target.profile, profile: profiles[target.profile] });
+      } else fail();
+    }
+    return Object.freeze({ role, target: roles[role] ?? Object.freeze({ kind: 'active-harness' }) });
+  } catch { fail(); }
+}