@jaimevalasek/aioson 1.36.0 → 1.37.1

package/src/agent-execution/manifest.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { AGENTS, validateManifest } = require('./schema');
+const { capabilities } = require('./capabilities');
+const { loadModelCatalog } = require('./model-catalog');
+const { resolveModel, validateReasoningEffort } = require('./model-resolver');
+
+function manifestPath(projectDir, feature) { return path.join(projectDir, '.aioson', 'context', `agent-execution-${feature}.json`); }
+function defaults(feature, host = 'codex') {
+  const agents = {};
+  for (const id of AGENTS) agents[id] = { enabled: true, host, mode: 'external', model: 'configured-default', writable_roots: [], fallbacks: [], report: `.aioson/context/reports/${feature}/{run_id}/${id}.json` };
+  return { version: 1, feature, host, generated_at: new Date().toISOString(), agents, capacity_policy: { strategy: 'pause', max_attempts: 1, backoff_ms: 0 }, cycle_limits: { dev_qa: 3, tester: 3, pentester: 3 }, reporting: { format: 'json', markdown: true } };
+}
+function stable(value) { if (Array.isArray(value)) return value.map(stable); if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(k => [k, stable(value[k])])); return value; }
+function digest(value) { return crypto.createHash('sha256').update(JSON.stringify(stable(value))).digest('hex'); }
+function mergeAdditive(existing, base) {
+  if (Array.isArray(existing)) return existing;
+  if (!existing || typeof existing !== 'object') return existing === undefined ? base : existing;
+  const out = { ...base };
+  for (const [key, value] of Object.entries(existing)) out[key] = value && typeof value === 'object' && !Array.isArray(value) ? mergeAdditive(value, base && base[key]) : value;
+  return out;
+}
+async function initManifest(projectDir, feature, host, { overwrite = false } = {}) {
+  const file = manifestPath(projectDir, feature); const base = defaults(feature, host);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  let value = base;
+  try { const old = JSON.parse(await fs.readFile(file, 'utf8')); if (!overwrite) value = mergeAdditive(old, base); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  await fs.writeFile(file, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  return { path: file, manifest: value, digest: digest(value) };
+}
+async function loadManifest(projectDir, feature) {
+  const file = manifestPath(projectDir, feature);
+  try { const value = JSON.parse(await fs.readFile(file, 'utf8')); const validation = validateManifest(value, feature); return { exists: true, path: file, manifest: value, digest: digest(value), ...validation }; }
+  catch (error) { if (error.code === 'ENOENT') return { exists: false, legacy: true, path: file, ok: true }; return { exists: true, path: file, ok: false, errors: [{ path: '$', message: error.message }] }; }
+}
+function resolveAgent(manifest, agent, overrides = {}) { const entry = manifest.agents[agent]; return { ...entry, host: overrides.host || entry.host || manifest.host, model: overrides.model || entry.model, source: 'manifest' }; }
+async function resolveExecutionEntry(entry, { catalogLoader = loadModelCatalog } = {}) {
+  const cap = capabilities(entry.host);
+  if (entry.reasoning_effort && !cap.reasoning_effort) return { ok: false, reason: 'unsupported_reasoning_effort', host: entry.host, model_requested: entry.model, candidates: [] };
+  const catalog = cap.model_catalog ? await catalogLoader(entry.host) : { available: false, reason: 'unsupported_model_catalog', models: [] };
+  const model = resolveModel(entry.model, catalog);
+  if (!model.ok) return { ...entry, ...model, model_requested: entry.model };
+  const effort = validateReasoningEffort(model, entry.reasoning_effort);
+  if (!effort.ok) return { ...entry, ok: false, reason: effort.reason, supported: effort.supported, candidates: [], model_requested: entry.model, model_resolved: model.resolved };
+  return {
+    ...entry,
+    ok: true,
+    model_requested: entry.model,
+    model: model.resolved,
+    model_resolved: model.resolved,
+    model_resolution_strategy: model.strategy,
+    catalog_source: model.catalog_source,
+    catalog_fetched_at: model.catalog_fetched_at,
+    reasoning_effort: effort.reasoning_effort,
+    reasoning_effort_verification: effort.verification
+  };
+}
+async function resolveAgentExecution(manifest, agent, overrides = {}, options = {}) { return resolveExecutionEntry(resolveAgent(manifest, agent, overrides), options); }
+module.exports = { defaults, digest, initManifest, loadManifest, manifestPath, mergeAdditive, resolveAgent, resolveAgentExecution, resolveExecutionEntry };

package/src/agent-execution/model-catalog.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { REASONING_EFFORTS } = require('./schema');
+
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+const DEFAULT_MAX_MODELS = 1000;
+const SAFE_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/;
+
+function unavailable(reason) {
+  return { available: false, reason, source: null, fetched_at: null, client_version: null, models: [] };
+}
+
+function codexHome(env, home) {
+  const configured = typeof env.CODEX_HOME === 'string' ? env.CODEX_HOME.trim() : '';
+  return configured || path.join(home, '.codex');
+}
+
+function normalizeEfforts(levels) {
+  if (!Array.isArray(levels)) return [];
+  const supported = new Set(REASONING_EFFORTS);
+  return [...new Set(levels.map(level => typeof level === 'string' ? level : level?.effort)
+    .filter(effort => typeof effort === 'string' && supported.has(effort)))];
+}
+
+function sanitizeModels(models) {
+  if (!Array.isArray(models)) return [];
+  const bySlug = new Map();
+  for (const model of models) {
+    const slug = typeof model?.slug === 'string' ? model.slug.trim() : '';
+    if (!SAFE_MODEL_ID.test(slug) || bySlug.has(slug)) continue;
+    const display = typeof model.display_name === 'string' && model.display_name.trim()
+      ? model.display_name.trim().slice(0, 200)
+      : slug;
+    bySlug.set(slug, {
+      slug,
+      display_name: display,
+      supported_efforts: normalizeEfforts(model.supported_reasoning_levels)
+    });
+  }
+  return [...bySlug.values()];
+}
+
+async function loadModelCatalog(host, options = {}) {
+  if (host !== 'codex') return unavailable('unsupported_model_catalog');
+  const env = options.env || process.env;
+  const home = options.home || os.homedir();
+  const file = path.join(codexHome(env, home), 'models_cache.json');
+  const maxBytes = Math.max(1, Number(options.maxBytes) || DEFAULT_MAX_BYTES);
+  const maxModels = Math.max(1, Number(options.maxModels) || DEFAULT_MAX_MODELS);
+  let stat;
+  try {
+    stat = await fs.stat(file);
+  } catch {
+    return unavailable('catalog_unavailable');
+  }
+  if (!stat.isFile()) return unavailable('catalog_unavailable');
+  if (stat.size > maxBytes) return unavailable('catalog_too_large');
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch {
+    return unavailable('catalog_invalid');
+  }
+  if (Array.isArray(parsed?.models) && parsed.models.length > maxModels) return unavailable('catalog_too_many_models');
+  const models = sanitizeModels(parsed?.models);
+  if (!models.length) return unavailable('catalog_incompatible');
+  return {
+    available: true,
+    reason: null,
+    source: 'codex_local_cache',
+    fetched_at: typeof parsed.fetched_at === 'string' ? parsed.fetched_at.slice(0, 100) : null,
+    client_version: typeof parsed.client_version === 'string' ? parsed.client_version.slice(0, 50) : null,
+    models
+  };
+}
+
+module.exports = { DEFAULT_MAX_BYTES, DEFAULT_MAX_MODELS, loadModelCatalog, sanitizeModels };

package/src/agent-execution/model-resolver.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const { MAX_MODEL_NAME_LENGTH, REASONING_EFFORTS } = require('./schema');
+
+const LITERAL_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/;
+const GENERIC_ALIASES = new Set(['gpt', 'model', 'openai', 'codex']);
+
+function tokens(value) {
+  return String(value || '').normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase().match(/[a-z]+|\d+/g) || [];
+}
+
+function normalizeModelName(value) { return tokens(value).join('-'); }
+function numericTokens(value) { return tokens(value).filter(token => /^\d+$/.test(token)); }
+function alphaTokens(value) { return tokens(value).filter(token => /^[a-z]+$/.test(token)); }
+
+function distance(left, right) {
+  const a = String(left); const b = String(right);
+  if (a.length > MAX_MODEL_NAME_LENGTH || b.length > MAX_MODEL_NAME_LENGTH) return Number.POSITIVE_INFINITY;
+  const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+  for (let i = 0; i <= a.length; i++) matrix[i][0] = i;
+  for (let j = 0; j <= b.length; j++) matrix[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        matrix[i][j] = Math.min(matrix[i][j], matrix[i - 2][j - 2] + cost);
+      }
+    }
+  }
+  return matrix[a.length][b.length];
+}
+
+function candidates(models) {
+  return (Array.isArray(models) ? models : []).filter(model => model && typeof model.slug === 'string')
+    .map(model => ({
+      slug: model.slug,
+      display_name: typeof model.display_name === 'string' ? model.display_name : model.slug,
+      supported_efforts: Array.isArray(model.supported_efforts) ? model.supported_efforts : []
+    }));
+}
+
+function uniqueBySlug(models) { return [...new Map(models.map(model => [model.slug, model])).values()]; }
+function diagnosticSlugs(models) { return uniqueBySlug(models).map(model => model.slug).sort().slice(0, 5); }
+
+function success(requested, model, strategy, catalog) {
+  return {
+    ok: true,
+    requested,
+    resolved: model.slug,
+    strategy,
+    catalog_source: catalog?.source || null,
+    catalog_fetched_at: catalog?.fetched_at || null,
+    supported_efforts: model.supported_efforts || []
+  };
+}
+
+function failure(requested, reason, models = [], catalog = null) {
+  return {
+    ok: false,
+    requested,
+    resolved: null,
+    reason,
+    candidates: diagnosticSlugs(models),
+    catalog_source: catalog?.source || null,
+    catalog_fetched_at: catalog?.fetched_at || null
+  };
+}
+
+function resolveModel(value, catalog) {
+  const requested = typeof value === 'string' ? value.trim() : '';
+  if (!requested) return failure(requested, 'invalid_model');
+  if (requested.length > MAX_MODEL_NAME_LENGTH) return failure(requested.slice(0, MAX_MODEL_NAME_LENGTH), 'invalid_model');
+  if (requested === 'configured-default') {
+    return success(requested, { slug: requested, supported_efforts: [] }, 'configured_default', catalog);
+  }
+  if (!catalog?.available) {
+    if (!LITERAL_MODEL_ID.test(requested)) return failure(requested, catalog?.reason || 'catalog_unavailable');
+    return success(requested, { slug: requested, supported_efforts: [] }, 'unverified_literal', null);
+  }
+  const models = candidates(catalog.models);
+  const exact = models.find(model => model.slug === requested);
+  if (exact) return success(requested, exact, 'exact_slug', catalog);
+
+  const requestedKey = normalizeModelName(requested);
+  const normalized = uniqueBySlug(models.filter(model => normalizeModelName(model.slug) === requestedKey
+    || normalizeModelName(model.display_name) === requestedKey));
+  if (normalized.length === 1) return success(requested, normalized[0], 'normalized_name', catalog);
+  if (normalized.length > 1) return failure(requested, 'ambiguous_model', normalized, catalog);
+
+  const requestedTokens = tokens(requested);
+  const isGeneric = requestedTokens.length === 1 && GENERIC_ALIASES.has(requestedTokens[0]);
+  const isUsableAlias = requestedKey.length >= 4 && !isGeneric && requestedTokens.some(token => /^[a-z]+$/.test(token));
+  if (isUsableAlias) {
+    const alias = uniqueBySlug(models.filter(model => {
+      const slugTokens = tokens(model.slug); const displayTokens = tokens(model.display_name);
+      const suffix = list => list.length >= requestedTokens.length
+        && requestedTokens.every((token, index) => token === list[list.length - requestedTokens.length + index]);
+      return suffix(slugTokens) || suffix(displayTokens);
+    }));
+    if (alias.length === 1) return success(requested, alias[0], 'unique_alias', catalog);
+    if (alias.length > 1) return failure(requested, 'ambiguous_model', alias, catalog);
+  }
+
+  const requestedNumbers = numericTokens(requested);
+  const requestedAlpha = alphaTokens(requested);
+  const eligible = models.filter(model => {
+    const modelNumbers = numericTokens(model.slug);
+    if (requestedNumbers.length && requestedNumbers.join('.') !== modelNumbers.join('.')) return false;
+    const modelAlpha = alphaTokens(model.slug);
+    return !requestedAlpha.length || requestedAlpha[0] === modelAlpha[0];
+  });
+  const ranked = eligible.map(model => ({ model, score: distance(requestedKey, normalizeModelName(model.slug)) }))
+    .sort((a, b) => a.score - b.score || a.model.slug.localeCompare(b.model.slug));
+  const maxDistance = Math.min(3, Math.max(1, Math.floor(requestedKey.length * 0.1)));
+  if (!ranked.length || ranked[0].score > maxDistance) return failure(requested, 'model_not_found', [], catalog);
+  const best = ranked.filter(item => item.score === ranked[0].score);
+  if (best.length !== 1) return failure(requested, 'ambiguous_model', best.map(item => item.model), catalog);
+  return success(requested, best[0].model, 'fuzzy_unique', catalog);
+}
+
+function validateReasoningEffort(resolution, effort) {
+  if (effort === undefined || effort === null || effort === '') return { ok: true, reasoning_effort: null, verification: 'inherited' };
+  if (!REASONING_EFFORTS.includes(effort)) return { ok: false, reason: 'invalid_reasoning_effort', supported: REASONING_EFFORTS };
+  if (!resolution?.ok) return { ok: false, reason: resolution?.reason || 'model_resolution_failed', supported: [] };
+  const supported = Array.isArray(resolution.supported_efforts) ? resolution.supported_efforts : [];
+  if (supported.length && !supported.includes(effort)) return { ok: false, reason: 'unsupported_reasoning_effort', supported };
+  return { ok: true, reasoning_effort: effort, verification: supported.length ? 'catalog' : 'unverified' };
+}
+
+module.exports = { distance, normalizeModelName, resolveModel, validateReasoningEffort };

package/src/agent-execution/reports.js

@@ -0,0 +1,9 @@
+'use strict';
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const VERDICTS = ['PASS', 'FAIL', 'BLOCKED'];
+const IDENTITY_FIELDS = ['feature','run_id','attempt_id','agent','host','model_resolved','manifest_digest'];
+function validateReport(r, expected = null) { const errors=[]; const req=['version','feature','run_id','attempt_id','agent','host','model_requested','model_resolved','manifest_digest','writable_roots','started_at','finished_at','verdict','findings','evidence'];if(expected?.model_resolution_strategy!==undefined)req.push('model_resolution_strategy'); for(const k of req) if(r?.[k]===undefined) errors.push({path:`$.${k}`,message:'is required'}); if(r && !VERDICTS.includes(r.verdict)) errors.push({path:'$.verdict',message:'must be PASS, FAIL, or BLOCKED'}); if(r && !Array.isArray(r.findings)) errors.push({path:'$.findings',message:'must be an array'});if(r&&!Array.isArray(r.writable_roots))errors.push({path:'$.writable_roots',message:'must be an array'}); if(expected) for(const key of IDENTITY_FIELDS) if(r?.[key]!==expected[key]) errors.push({path:`$.${key}`,message:'does not match the registered attempt'});for(const key of ['model_requested','model_resolution_strategy'])if(expected?.[key]!==undefined&&r?.[key]!==expected[key])errors.push({path:`$.${key}`,message:'does not match the registered attempt'});if(expected&&expected.reasoning_effort&&r?.reasoning_effort!==expected.reasoning_effort)errors.push({path:'$.reasoning_effort',message:'does not match the registered attempt'});if(expected&&JSON.stringify(r?.writable_roots)!==JSON.stringify(expected.writable_roots))errors.push({path:'$.writable_roots',message:'does not match the registered attempt'}); if(expected && !['ready','running'].includes(expected.status)) errors.push({path:'$.attempt_id',message:'attempt is not eligible to report'}); return {ok:errors.length===0,errors}; }
+function safeReportPath(projectDir, relative) { const root=path.resolve(projectDir,'.aioson','context','reports'); const target=path.resolve(projectDir,relative); if(target!==root && !target.startsWith(root+path.sep)) throw new Error('report path escapes report root'); return target; }
+async function writeReport(projectDir, relative, report, expected) { const check=validateReport(report,expected); if(!check.ok){const e=new Error('invalid report');e.errors=check.errors;throw e;} const file=safeReportPath(projectDir,relative); await fs.mkdir(path.dirname(file),{recursive:true}); const handle=await fs.open(file,'wx'); try{await handle.writeFile(`${JSON.stringify(report,null,2)}\n`,'utf8')}finally{await handle.close()} return file; }
+module.exports={validateReport,safeReportPath,writeReport};

package/src/agent-execution/schema.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const HOSTS = ['claude', 'codex', 'opencode'];
+const MODES = ['fresh-session', 'subagent', 'external', 'current-session'];
+const AGENTS = ['dev', 'qa', 'tester', 'pentester', 'validator'];
+const REASONING_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
+const MAX_MODEL_NAME_LENGTH = 200;
+const ROOT_KEYS = ['version','feature','host','generated_at','agents','capacity_policy','cycle_limits','reporting'];
+const AGENT_KEYS = ['enabled','host','mode','model','reasoning_effort','writable_roots','fallbacks','report'];
+const SECRET_KEY = /token|secret|password|authorization|api[_-]?key/i;
+
+function validateManifest(value, expectedFeature) {
+  const errors = [];
+  const add = (path, message) => errors.push({ path, message });
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { ok: false, errors: [{ path: '$', message: 'must be an object' }] };
+  const scanSecrets=(node,p='$')=>{if(!node||typeof node!=='object')return;for(const [key,child] of Object.entries(node)){if(SECRET_KEY.test(key))add(`${p}.${key}`,'secret fields are forbidden; use environment configuration');scanSecrets(child,`${p}.${key}`)}};scanSecrets(value);
+  for (const key of Object.keys(value)) if (!ROOT_KEYS.includes(key)) add(`$.${key}`, SECRET_KEY.test(key) ? 'secret fields are forbidden; use environment configuration' : 'unknown field');
+  if (value.version !== 1) add('$.version', 'must equal 1');
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value.feature || '')) add('$.feature', 'must be a kebab-case slug');
+  if (expectedFeature && value.feature !== expectedFeature) add('$.feature', `must equal ${expectedFeature}`);
+  if (!HOSTS.includes(value.host)) add('$.host', `must be one of ${HOSTS.join(', ')}`);
+  if (!value.agents || typeof value.agents !== 'object') add('$.agents', 'must be an object');
+  else for(const key of Object.keys(value.agents)) if(!AGENTS.includes(key)) add(`$.agents.${key}`,'unknown agent');
+  for (const id of AGENTS) {
+    const agent = value.agents && value.agents[id];
+    if (!agent || typeof agent !== 'object') { add(`$.agents.${id}`, 'is required'); continue; }
+    for (const key of Object.keys(agent)) if (!AGENT_KEYS.includes(key)) add(`$.agents.${id}.${key}`, SECRET_KEY.test(key) ? 'secret fields are forbidden; use environment configuration' : 'unknown field');
+    if (typeof agent.enabled !== 'boolean') add(`$.agents.${id}.enabled`, 'must be boolean');
+    if (!HOSTS.includes(agent.host)) add(`$.agents.${id}.host`, `must be one of ${HOSTS.join(', ')}`);
+    if (!MODES.includes(agent.mode)) add(`$.agents.${id}.mode`, `must be one of ${MODES.join(', ')}`);
+    if (typeof agent.model !== 'string' || !agent.model.trim()) add(`$.agents.${id}.model`, 'must be a non-empty model id');
+    else if (agent.model.length > MAX_MODEL_NAME_LENGTH) add(`$.agents.${id}.model`, `must be at most ${MAX_MODEL_NAME_LENGTH} characters`);
+    if (agent.reasoning_effort !== undefined && !REASONING_EFFORTS.includes(agent.reasoning_effort)) add(`$.agents.${id}.reasoning_effort`, `must be one of ${REASONING_EFFORTS.join(', ')}`);
+    if(!Array.isArray(agent.writable_roots))add(`$.agents.${id}.writable_roots`,'must be an array');else agent.writable_roots.forEach((root,index)=>{if(typeof root!=='string'||!root.trim())add(`$.agents.${id}.writable_roots[${index}]`,'must be a non-empty path')});
+    if (!Array.isArray(agent.fallbacks)) add(`$.agents.${id}.fallbacks`, 'must be an array');
+    else agent.fallbacks.forEach((fallback,index)=>{const p=`$.agents.${id}.fallbacks[${index}]`;if(!fallback||typeof fallback!=='object'||Array.isArray(fallback)){add(p,'must be {host, model}');return}for(const key of Object.keys(fallback))if(!['host','model'].includes(key))add(`${p}.${key}`,'unknown field');if(!HOSTS.includes(fallback.host))add(`${p}.host`,`must be one of ${HOSTS.join(', ')}`);if(typeof fallback.model!=='string'||!fallback.model.trim())add(`${p}.model`,'must be a non-empty model id');else if(fallback.model.length>MAX_MODEL_NAME_LENGTH)add(`${p}.model`,`must be at most ${MAX_MODEL_NAME_LENGTH} characters`)});
+    if (typeof agent.report !== 'string' || !agent.report.includes('{run_id}')) add(`$.agents.${id}.report`, 'must include {run_id}');
+  }
+  const limits = value.cycle_limits;
+  if (!limits || typeof limits !== 'object') add('$.cycle_limits', 'is required');
+  else for (const [key, number] of Object.entries(limits)) if (!Number.isInteger(number) || number < 0) add(`$.cycle_limits.${key}`, 'must be a non-negative integer');
+  if (!value.capacity_policy || !['pause', 'retry', 'wait', 'fallback'].includes(value.capacity_policy.strategy)) add('$.capacity_policy.strategy', 'must be pause, retry, wait, or fallback');
+  else { for(const key of Object.keys(value.capacity_policy)) if(!['strategy','max_attempts','backoff_ms','allow_cross_host'].includes(key)) add(`$.capacity_policy.${key}`,'unknown field'); if(!Number.isInteger(value.capacity_policy.max_attempts)||value.capacity_policy.max_attempts<1)add('$.capacity_policy.max_attempts','must be a positive integer'); if(!Number.isInteger(value.capacity_policy.backoff_ms)||value.capacity_policy.backoff_ms<0)add('$.capacity_policy.backoff_ms','must be a non-negative integer'); }
+  if(!value.reporting||typeof value.reporting!=='object')add('$.reporting','is required');else for(const key of Object.keys(value.reporting))if(!['format','markdown'].includes(key))add(`$.reporting.${key}`,'unknown field');
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = { AGENTS, HOSTS, MAX_MODEL_NAME_LENGTH, MODES, REASONING_EFFORTS, validateManifest };

package/src/agent-execution/telemetry-bridge.js

@@ -0,0 +1,15 @@
+'use strict';
+const crypto=require('node:crypto');
+const {openRuntimeDb,createExecutionRun,attachExecutionProcess,transitionExecutionRun,appendExecutionEvent,attachExecutionReport,pruneExecutionTelemetry}=require('../runtime-store');
+const DEFAULTS={maxQueueBytes:256*1024,maxEventBytes:16*1024,maxPersistedBytes:1024*1024,maxPendingBytes:64*1024,flushMs:100};
+function redact(value){return String(value||'').replace(/(authorization\s*[:=]\s*(?:bearer\s+)?|api[_-]?key\s*[:=]\s*|token\s*[:=]\s*|password\s*[:=]\s*)[^\s,;]+/gi,'$1[REDACTED]').replace(/\b(sk-[A-Za-z0-9_-]{8,})\b/g,'[REDACTED]');}
+function fingerprint(pid,startedAt){return crypto.createHash('sha256').update(`${pid}:${startedAt}`).digest('hex').slice(0,24);}
+async function createTelemetryBridge(projectDir,correlation,options={}){
+ const cfg={...DEFAULTS,...options};const opened=await openRuntimeDb(projectDir);const db=opened.db;pruneExecutionTelemetry(db,{retentionDays:options.retentionDays||14,batch:100});const run=createExecutionRun(db,correlation);let queue=[],queued=0,persisted=0,dropped=0,closed=false,timer=null;const pendingByStream=new Map();
+ const flush=()=>{if(!queue.length&&!dropped)return;const items=queue;queue=[];queued=0;for(const item of items){appendExecutionEvent(db,run.telemetry_run_id,item);persisted+=item.bytes;}if(dropped){appendExecutionEvent(db,run.telemetry_run_id,{type:'output_truncated',safe_summary:`${dropped} output bytes dropped`,bytes:Math.min(dropped,cfg.maxEventBytes)});db.prepare('UPDATE agent_execution_runs SET truncated_bytes=truncated_bytes+?,dropped_events=dropped_events+1 WHERE telemetry_run_id=?').run(dropped,run.telemetry_run_id);dropped=0;}};
+ const schedule=()=>{if(!timer)timer=setTimeout(()=>{timer=null;try{flush();}catch{}},cfg.flushMs)};
+ const enqueue=(stream,text)=>{let safe=redact(text);let bytes=Buffer.byteLength(safe);if(bytes>cfg.maxEventBytes){dropped+=bytes-cfg.maxEventBytes;safe=Buffer.from(safe).subarray(0,cfg.maxEventBytes).toString();bytes=Buffer.byteLength(safe)}if(persisted+queued+bytes>cfg.maxPersistedBytes||queued+bytes>cfg.maxQueueBytes){dropped+=bytes;return}queue.push({type:'output',stream,safe_summary:safe,bytes});queued+=bytes};
+ const output=(stream,chunk)=>{if(closed)return;let pending=(pendingByStream.get(stream)||'')+String(chunk||'');if(Buffer.byteLength(pending)>cfg.maxPendingBytes){dropped+=Buffer.byteLength(pending);pendingByStream.set(stream,'');return schedule()}let newline;while((newline=pending.indexOf('\n'))>=0){enqueue(stream,pending.slice(0,newline+1));pending=pending.slice(newline+1)}pendingByStream.set(stream,pending);schedule();};
+ return {run,output,onSpawn(pid,startedAt=new Date().toISOString()){return attachExecutionProcess(db,correlation,{pid,fingerprint:fingerprint(pid,startedAt)})},event(type,summary,payload){appendExecutionEvent(db,correlation,{type,safe_summary:redact(summary),payload})},transition(next,reason){flush();return transitionExecutionRun(db,correlation,next,reason)},report(report,path,digest){flush();return attachExecutionReport(db,correlation,{...report,path,digest})},close(){if(closed)return;closed=true;if(timer)clearTimeout(timer);for(const [stream,pending] of pendingByStream)if(pending)enqueue(stream,pending);flush();db.close();}};
+}
+module.exports={createTelemetryBridge,redact,fingerprint};

package/src/agents.js

@@ -67,7 +67,7 @@ function buildAgentPrompt(agent, tool, options = {}) {
     '',
     `**Language boundary:** Agent instructions are canonical in English. All user-facing communication must be in ${interactionLanguage}.`,
     '',
-    `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.${autoHandoff ? ' Exception: autopilot handoff is active for this stage — follow `.aioson/docs/autopilot-handoff.md` and auto-invoke the next agent\'s skill when no stop condition applies. The chain stops before the first `@dev` activation (human clears context and starts implementation) and continues through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their triggers fire → `@validator`); it NEVER auto-runs `feature:close`/publish — those require explicit human approval.' : ''}`,
+    `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.${autoHandoff ? ' Exception: autopilot handoff is active for this stage — follow `.aioson/docs/autopilot-handoff.md` and auto-invoke the next agent\'s skill when no stop condition applies. The chain runs the whole feature: the spec authority (`@sheldon`/`@orchestrator`) seeds the agentic scheme and crosses into `@dev` via the `dev-state.md` cold-start packet once its own gates/decisions are settled, and the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their triggers fire → `@validator`) continues automatically. It stops only for a genuine human decision or a stop condition, and NEVER auto-runs `feature:close`/publish — those require explicit human approval.' : ''}`,
   ].join('\n');
 
   if (safeTool === 'claude') {

package/src/artifact-kinds.js

@@ -29,7 +29,8 @@ const AGENT_ARTIFACT_KIND = {
   'design-hybrid-forge': { kind: 'hybrid-skill', needs: 'slug' },
   copywriter: { kind: 'copy', needs: 'slug' },
   orache: { kind: 'orache-report', needs: 'file' },
-  'site-forge': { kind: 'site', needs: 'dir', opts: { noBuild: true } }
+  'site-forge': { kind: 'site', needs: 'dir', opts: { noBuild: true } },
+  'briefing-refiner': { kind: 'review', needs: 'slug' }
 };
 
 const NEEDS_FLAG = { slug: '--slug=<slug>', file: '--file=<path>', dir: '--dir=<dir>' };

package/src/autopilot-signal.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * Autopilot activation signal — the single source of truth for "is autopilot
+ * on?" outside the agent markdown files.
+ *
+ * Contract (docs/autopilot-handoff.md "Activation"), highest precedence first:
+ *   - A scheme for the CURRENT feature with `agentic_policy.enabled: false`
+ *     (the `--step` disarm) → OFF, even over `auto_handoff: true` — an explicit
+ *     per-feature choice always wins over the project default.
+ *   - `auto_handoff: true` in project.context.md frontmatter → ON (project default).
+ *   - `auto_handoff: false` → OFF, even if a seeded scheme is lying around
+ *     (step-by-step is the standing choice; a leftover scheme must not override it).
+ *   - flag absent → ON only when `.aioson/context/workflow-execute.json` exists
+ *     with `agentic_policy.enabled: true` (the per-feature "Autopilot" choice,
+ *     which deliberately does NOT persist the frontmatter flag). When a slug is
+ *     provided, the scheme counts only if it was seeded for THAT feature — a
+ *     scheme left by a different/closed feature does not.
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { validateProjectContextFile } = require('./context');
+
+const EXECUTION_STATE_RELATIVE_PATH = '.aioson/context/workflow-execute.json';
+
+async function readSeededScheme(targetDir) {
+  try {
+    const raw = await fs.readFile(path.join(targetDir, EXECUTION_STATE_RELATIVE_PATH), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function resolveAutopilotSignal(targetDir, { slug = null, projectContext = null } = {}) {
+  let flag;
+  try {
+    const context = projectContext || await validateProjectContextFile(targetDir);
+    flag = context && context.data && Object.prototype.hasOwnProperty.call(context.data, 'auto_handoff')
+      ? context.data.auto_handoff === true
+      : null;
+  } catch {
+    flag = null;
+  }
+
+  const scheme = await readSeededScheme(targetDir);
+  const slugMatches = Boolean(
+    scheme && (!slug || !scheme.feature || String(scheme.feature) === String(slug))
+  );
+
+  // Explicit per-feature disarm (--step) beats the project-wide flag.
+  if (
+    scheme && scheme.agentic_policy && scheme.agentic_policy.enabled === false &&
+    slugMatches
+  ) {
+    return { enabled: false, source: 'scheme_disarmed' };
+  }
+
+  if (flag === true) return { enabled: true, source: 'frontmatter' };
+  if (flag === false) return { enabled: false, source: 'frontmatter_off' };
+
+  const schemeEnabled = Boolean(scheme && scheme.agentic_policy && scheme.agentic_policy.enabled === true);
+  if (!schemeEnabled) return { enabled: false, source: null };
+  if (!slugMatches) return { enabled: false, source: 'scheme_other_feature' };
+  return { enabled: true, source: 'seeded_scheme' };
+}
+
+module.exports = {
+  resolveAutopilotSignal
+};

package/src/cli.js

@@ -188,7 +188,8 @@ const { runPreflight } = require('./commands/preflight');
 const { runClassify } = require('./commands/classify');
 const { runPrototypeCheck } = require('./commands/prototype-check');
 const { runVerifyImplementation } = require('./commands/verify-implementation');
-const { runVerificationPlan } = require('./commands/verification-plan');
+const { runVerificationPlan } = require('./commands/verification-plan');
+const { runAgentExecution } = require('./commands/agent-execution');
 const { runSizing } = require('./commands/sizing');
 const { runDetectTestRunner } = require('./commands/detect-test-runner');
 const { runPulseUpdate } = require('./commands/pulse-update');
@@ -237,7 +238,7 @@ const { runGenomePublish, runGenomeInstallStore, runGenomeInstall, runGenomeList
 const { runSkillPublish, runSkillInstallStore, runSkillListRemote } = require('./commands/store-skill');
 const { runSquadPublish, runSquadInstall, runSquadGrant, runSquadList } = require('./commands/store-squad');
 const { runSystemPackage, runSystemPublish, runSystemList, runSystemInstall } = require('./commands/store-system');
-const { runBriefingApprove, runBriefingUnapprove } = require('./commands/briefing');
+const { runBriefingApprove, runBriefingUnapprove, runBriefingReview, runBriefingApplyFeedback } = require('./commands/briefing');
 const { runCompressAgents } = require('./commands/compress-agents');
 
 const JSON_SUPPORTED_COMMANDS = new Set([
@@ -354,6 +355,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'audit-code',
   'verify:artifact',
   'verify-artifact',
+  'briefing:review',
+  'briefing-review',
+  'briefing:apply-feedback',
+  'briefing-apply-feedback',
   'review:feature',
   'review-feature',
   'config',
@@ -669,7 +674,21 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'verify:implementation',
   'verify-implementation',
   'verification:plan',
-  'verification-plan',
+  'verification-plan',
+  'agent:execution:init',
+  'agent-execution-init',
+  'agent:execution:validate',
+  'agent-execution-validate',
+  'agent:execution:show',
+  'agent-execution-show',
+  'agent:execution:dispatch',
+  'agent-execution-dispatch',
+  'agent:execution:resume',
+  'agent-execution-resume',
+  'agent:execution:status',
+  'agent-execution-status',
+  'agent:execution:events',
+  'agent-execution-events',
   'sizing',
   'detect:test-runner',
   'detect-test-runner',
@@ -1622,8 +1641,11 @@ async function main() {
       result = await runPreflight({ args, options, logger: commandLogger });
     } else if (command === 'classify') {
       result = await runClassify({ args, options, logger: commandLogger });
-    } else if (command === 'verification:plan' || command === 'verification-plan') {
-      result = await runVerificationPlan({ args, options, logger: commandLogger });
+    } else if (command === 'verification:plan' || command === 'verification-plan') {
+      result = await runVerificationPlan({ args, options, logger: commandLogger });
+    } else if (command.startsWith('agent:execution:') || command.startsWith('agent-execution-')) {
+      const sub = command.replace(/^agent:execution:|^agent-execution-/, '');
+      result = await runAgentExecution({ args, options: { ...options, sub }, logger: commandLogger });
     } else if (command === 'prototype:check' || command === 'prototype-check') {
       result = await runPrototypeCheck({ args, options, logger: commandLogger });
     } else if (command === 'verify:implementation' || command === 'verify-implementation') {
@@ -1770,6 +1792,10 @@ async function main() {
       result = await runBriefingApprove({ args, options, logger: commandLogger });
     } else if (command === 'briefing:unapprove' || command === 'briefing-unapprove') {
       result = await runBriefingUnapprove({ args, options, logger: commandLogger });
+    } else if (command === 'briefing:review' || command === 'briefing-review') {
+      result = await runBriefingReview({ args, options, logger: commandLogger });
+    } else if (command === 'briefing:apply-feedback' || command === 'briefing-apply-feedback') {
+      result = await runBriefingApplyFeedback({ args, options, logger: commandLogger });
     } else {
       const message = t('cli.unknown_command', { command });
       if (jsonMode) {

package/src/commands/agent-execution.js

@@ -0,0 +1,36 @@
+'use strict';
+const path=require('node:path');
+const {initManifest,loadManifest,resolveAgentExecution}=require('../agent-execution/manifest');
+const {dispatch,readState}=require('../agent-execution/dispatcher');
+const {openRuntimeDb,getExecutionSnapshot,listExecutionEvents}=require('../runtime-store');
+async function resolveAllAgents(manifest,catalogLoader){
+ const entries=await Promise.all(Object.keys(manifest.agents).map(async id=>[id,await resolveAgentExecution(manifest,id,{}, {catalogLoader})]));
+ return Object.fromEntries(entries);
+}
+function resolutionErrors(resolutions){
+ return Object.entries(resolutions).filter(([,value])=>!value.ok).map(([id,value])=>({path:`$.agents.${id}.model`,message:value.reason,candidates:value.candidates||[],supported:value.supported||[]}));
+}
+async function runAgentExecution({args,options={},logger,catalogLoader}){
+ const projectDir=path.resolve(process.cwd(),args[0]||'.'); const sub=options.sub||'show'; const feature=String(options.feature||options.slug||'').trim();
+ if(!feature)return {ok:false,reason:'feature_required',message:'Use --feature=<slug>'};
+ if(sub==='init'){const created=await initManifest(projectDir,feature,String(options.host||'codex')); const result={ok:true,feature,path:path.relative(projectDir,created.path),digest:created.digest,manifest:created.manifest,availability:'validated_at_dispatch'}; if(!options.json)logger.log(`Agent execution manifest: ${result.path}\nValidate: aioson agent:execution:validate . --feature=${feature}`); return result;}
+ const loaded=await loadManifest(projectDir,feature);
+ if(sub==='validate'){
+  let resolutions={};let errors=loaded.errors||[];
+  if(loaded.exists&&loaded.ok){resolutions=await resolveAllAgents(loaded.manifest,catalogLoader);errors=resolutionErrors(resolutions)}
+  const result={ok:Boolean(loaded.exists&&loaded.ok&&!errors.length),feature,path:path.relative(projectDir,loaded.path),legacy:!loaded.exists,digest:loaded.digest||null,errors,resolutions,availability:'validated_at_dispatch'};
+  if(!options.json)(result.ok?logger.log(`Valid: ${result.path} (models resolved against the current runtime catalog).`):logger.error(JSON.stringify(result.errors,null,2)));return result;
+ }
+ if(sub==='show'){
+  if(!loaded.exists)return {ok:true,legacy:true,feature,path:path.relative(projectDir,loaded.path),message:'Manifest absent; legacy configured-default remains active.'};
+  if(!loaded.ok)return {ok:false,feature,errors:loaded.errors};
+  const agents=await resolveAllAgents(loaded.manifest,catalogLoader);const errors=resolutionErrors(agents);
+  return {ok:!errors.length,feature,path:path.relative(projectDir,loaded.path),digest:loaded.digest,agents,errors,availability:'validated_at_dispatch'};
+ }
+ if(sub==='dispatch')return dispatch({projectDir,feature,agent:options.agent||'dev',runId:options['run-id'],promptPath:options.prompt,catalogLoader});
+ if(sub==='resume'){const state=await readState(projectDir,feature);if(!state)return {ok:false,reason:'state_missing'};return dispatch({projectDir,feature,agent:options.agent||state.attempts.at(-1)?.agent||'dev',runId:state.run_id,promptPath:options.prompt,catalogLoader});}
+ if(sub==='status'){const {db}=await openRuntimeDb(projectDir);try{return{ok:true,schema_version:1,feature,runs:getExecutionSnapshot(db,{feature,agent:options.agent,state:options.state,limit:options.limit})}}finally{db.close()}}
+ if(sub==='events'){const state=await readState(projectDir,feature);const run=String(options.run||state?.attempts?.at(-1)?.telemetry_run_id||'');if(!run)return{ok:false,reason:'telemetry_run_required'};const {db}=await openRuntimeDb(projectDir);try{const owned=getExecutionSnapshot(db,{feature,limit:200}).some(item=>item.telemetry_run_id===run);if(!owned)return{ok:false,reason:'telemetry_run_not_found'};return{ok:true,schema_version:1,trust:'sanitized_untrusted_output',feature,telemetry_run_id:run,...listExecutionEvents(db,run,{after:options.after,limit:options.limit})}}finally{db.close()}}
+ return {ok:false,reason:'invalid_subcommand',valid:['init','validate','show','dispatch','resume','status','events']};
+}
+module.exports={runAgentExecution};

package/src/commands/agents.js

@@ -12,7 +12,8 @@ const {
 const { normalizeInteractionLanguage } = require('../locales');
 const { validateProjectContextFile, getInteractionLanguage } = require('../context');
 const { exists } = require('../utils');
-const { loadOrCreateState, runWorkflowNext } = require('./workflow-next');
+const { AUTOPILOT_HANDOFF_STAGES, loadOrCreateState, runWorkflowNext } = require('./workflow-next');
+const { resolveAutopilotSignal } = require('../autopilot-signal');
 const {
   bootstrapDirectAgentPrompt,
   classifyDirectAgentRuntime
@@ -278,12 +279,27 @@ async function runAgentPrompt({ args, options, logger, t }) {
       manifest,
       requestedMode: promptAgent.id === 'scope-check' && getScopeCheckModeOption(options) ? null : options.mode || null
     });
+    // Direct handoffs carry the autopilot exception too — without it the
+    // injected scope boundary instructs a manual stop and overrides the agent
+    // .md's autopilot section even when the flag/scheme says to chain.
+    let autoHandoff = false;
+    if (AUTOPILOT_HANDOFF_STAGES.has(promptAgent.id)) {
+      try {
+        const signal = await resolveAutopilotSignal(targetDir, {
+          slug: options.feature ? String(options.feature).trim() : null
+        });
+        autoHandoff = signal.enabled;
+      } catch {
+        autoHandoff = false;
+      }
+    }
     prompt = buildAgentPrompt(promptAgent, tool, {
       instructionPath,
       interactionLanguage: locale,
       autonomyMode: effectiveMode,
       capabilitySummary: buildAgentCapabilitySummary(manifest, tool),
-      activationContext
+      activationContext,
+      autoHandoff
     });
     const runtimeClass = classifyDirectAgentRuntime(promptAgent.id);
     const handoffLabel = runtimeClass.source === 'squad_session'