agent-policy-kit 0.0.0-stage → 0.2.0

package/src/native.mjs

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { ROLES, rolePreference } from './policy.mjs';
+import {ROLE_DEFINITIONS,ROLE_IDS} from './roles.mjs';
+
+export const BEGIN = '<!-- BEGIN agent-policy-kit -->';
+export const END = '<!-- END agent-policy-kit -->';
+const directory = {codex:'.codex',claude:'.claude',kimi:'.kimi-code',agy:'.gemini',grok:'.grok'};
+export function nativeHomeConflict(client,home,env) {
+  const variable={codex:'CODEX_HOME',claude:'CLAUDE_CONFIG_DIR',kimi:'KIMI_CODE_HOME',grok:'GROK_HOME'}[client];
+  const active=variable&&env[variable];
+  return typeof active==='string'&&active.length>0&&path.resolve(active)!==path.resolve(home,directory[client]);
+}
+export function nativeLocations(client,home) {
+  const root=path.join(home,directory[client]);
+  return {
+    config:client==='agy'?null:path.join(root,client==='claude'?'settings.json':'config.toml'),
+    instructions:path.join(root,client==='claude'?'CLAUDE.md':'AGENTS.md'),
+    roles:Object.keys(ROLES).map(role=>path.join(root,client==='agy'?'config/agents':'agents',`apk-${role}.${client==='codex'?'toml':'md'}`))
+  };
+}
+export function nativeRoles(client,config,selectedRoles=ROLE_IDS) {
+  return selectedRoles.map(role=>{
+    const selected=rolePreference(config,role),name='apk-'+role;
+    const {description,prompt}=ROLE_DEFINITIONS.find(value=>value.id===role);
+    if(client==='codex') return Object.entries({name,description,model:selected.model,...(selected.effort===null?{}:{model_reasoning_effort:selected.effort}),developer_instructions:prompt}).map(([k,v])=>`${k} = ${JSON.stringify(v)}\n`).join('');
+    const fields=[`name: ${name}`,`description: ${JSON.stringify(description)}`];
+    // Grok selects the model from config.toml [subagents.models]; read-only roles use the bundled plan permission mode.
+    if(client==='grok') {
+      if(['reviewer','explorer'].includes(role))fields.push('permission_mode: plan');
+    } else if(client==='kimi') {
+      if(['reviewer','explorer'].includes(role))fields.push('tools: [Read, Grep, Glob]');
+    } else {
+      fields.push(`model: ${JSON.stringify(selected.model)}`);
+      if(client==='claude') {
+        if(selected.effort!==null)fields.push(`effort: ${selected.effort}`);
+        if(['reviewer','explorer'].includes(role))fields.push('tools: Read, Grep, Glob');
+      } else fields.push('subagent: true');
+    }
+    const routing=client==='kimi'?`\nThe parent must select configured pool alias ${selected.model} for this role; Markdown frontmatter does not select a model. Requested effort: ${selected.effort??'native default'}.\n`:'';
+    return `---\n${fields.join('\n')}\n---\n\n${prompt}\n${routing}`;
+  });
+}
+export function instructionBlock(client,config,maxConcurrent,selectedRoles=ROLE_IDS) {
+  const routing=ROLE_DEFINITIONS.filter(role=>selectedRoles.includes(role.id)).map(role=>`apk-${role.id} for ${role.assignment}`).join(', ');
+  const text=[BEGIN,'These preferences apply only if you choose to delegate to subagents. They do not require delegation or change how you handle work directly.',`When delegating, use ${routing}.`,`When delegating, run at most ${maxConcurrent} subagents concurrently in this session. Give each agent one concrete result and explicit file ownership. Preserve other agents' work. Child agents must return further delegation to the parent.`];
+  if(client==='kimi') {
+    for(const role of selectedRoles) {const selected=rolePreference(config,role);text.push(`For apk-${role}, select pool alias ${selected.model} (effort ${selected.effort??'native default'}).`);}
+    text.push('Roles sharing an alias share its native effort default; an explicit effort pin for that alias also affects its native-default roles.');
+    text.push("Use the Agent tool's model selection when spawning; the role file alone does not select a model. The concurrency limit is guidance; no native Agent cap is configured.");
+  } else if(client==='agy') {
+    for(const role of selectedRoles)text.push(`When delegating to apk-${role}, use model tier ${rolePreference(config,role).model}.`);
+    text.push('Per-role effort and a hard concurrency cap are not supported by the documented native agent settings.');
+  }
+  else if(client==='grok')text.push('Use the named role definitions for model selection. Per-role effort is not supported by the documented native agent settings; subagents use the main session effort. Explicit spawn settings and higher-priority instructions can supersede user defaults.');
+  else if(client==='claude')text.push('Use the named role definitions for model and effort selection. Session, project, managed settings, environment overrides and some spawn paths can supersede these user defaults; the native cap applies to ordinary Agent-tool spawns with documented exceptions.');
+  else text.push('Use the named role definitions for model and effort selection. Explicit spawn settings and higher-priority instructions can supersede user defaults.');
+  if(client==='codex'||client==='claude')text.push('An omitted role effort uses the native client default; it does not pin a level.');
+  if(config.avoidModels.length)text.push(`Avoid these models when delegating: ${config.avoidModels.join(', ')}. This is routing guidance.`);
+  text.push(END);
+  return text.join('\n')+'\n';
+}
+export function nativeWarnings(client) {
+  return client==='kimi'?['kimi-concurrency-guidance-only','kimi-model-pool-routing-guidance']:client==='agy'?['agy-concurrency-guidance-only','agy-per-role-effort-unsupported']:client==='grok'?['grok-per-role-effort-unsupported','grok-native-precedence-limits']:client==='claude'?['claude-native-precedence-limits']:['codex-native-precedence-limits'];
+}

package/src/output.mjs

@@ -0,0 +1,108 @@
+import {PRESETS} from './release.mjs';
+const LABELS={codex:'Codex',claude:'Claude Code',kimi:'Kimi',agy:'Antigravity',grok:'Grok Build'};
+const label=client=>LABELS[client]??'Tool';
+const code=value=>typeof value==='string'&&/^[A-Za-z][A-Za-z0-9_-]{0,127}$/.test(value)?value:'OPERATION_FAILED';
+const PRESET_LABELS=Object.fromEntries(PRESETS.map(entry=>[entry.id,entry.label]));
+const preset=value=>Object.hasOwn(PRESET_LABELS,value)?' · '+PRESET_LABELS[value]:'';
+const NOTES={
+ 'codex-native-precedence-limits':'Project and explicit client settings can override these defaults.',
+ 'claude-native-precedence-limits':'Project and explicit client settings can override these defaults.',
+ 'kimi-concurrency-guidance-only':'Kimi: the concurrency limit is guidance.',
+ 'kimi-model-pool-routing-guidance':'Kimi: the parent selects the model alias for each role.',
+ 'agy-concurrency-guidance-only':'Antigravity: the concurrency limit is guidance.',
+ 'agy-per-role-effort-unsupported':'Antigravity: native tiers do not support per-role effort.',
+ 'grok-per-role-effort-unsupported':'Grok Build: native agent settings do not support per-role effort.',
+ 'grok-native-precedence-limits':'Project and explicit client settings can override these defaults.',
+ 'kimi-catalog-alias-resolved':'Kimi: an existing matching model alias was selected.',
+};
+const REASONS={
+ OWNED_DRIFT:'Local edits prevent an update',
+ 'kimi-provisioned-models-required':'Required model aliases are missing',
+ 'native-home-override-unsupported':'The active client profile uses a nonstandard location',
+ 'client-not-selected':'This tool is not selected in the configuration',
+ 'claude-force-model-conflict':'A forced model conflicts with the selected roles',
+ 'kimi-supported-effort-required':'A selected alias does not declare the required effort support',
+ 'kimi-main-effort-conflict':'The requested effort would change the main model defaults',
+ 'kimi-thinking-disabled':'Thinking is disabled for a model that requires it',
+ 'kimi-mixed-native-default-effort':'A shared effort override conflicts with native-default roles',
+ 'kimi-catalog-alias-ambiguous':'More than one existing model alias matches',
+ 'kimi-resolved-model-avoided':'The matching alias is on the avoid list',
+ 'kimi-resolved-effort-conflict':'Roles sharing an alias request conflicting effort levels',
+ INSTALLATION_CONFLICT:'Installed preferences differ from this request',
+ POLICY_CONFLICT:'Saved preferences differ from this request',
+ RECOVERY_REQUIRED:'An interrupted transaction requires recovery',
+ INSTALL_LOCKED:'Another configuration operation holds the lock',
+};
+export const useJsonOutput=({isTTY,json=false}={})=>json||!isTTY;
+function reason(value){const id=code(value);return (REASONS[id]??'Configuration could not be completed')+` (${id})`;}
+function row(client,text,mark='✓'){return `${mark} ${label(client).padEnd(14)} ${text}`;}
+function setup(result,{apply}){
+ const results=result.results??[],failed=results.some(r=>['error','prerequisite','invalid','timeout'].includes(r.status));
+ const changed=results.filter(r=>r.status==='configured');
+ const heading=failed?'Setup incomplete':result.status==='no_clients'?'No supported selected tools found':!apply?'Preview · no files changed':changed.length?'Configuration applied':'Already up to date';
+ const lines=[heading,''],missing=[],notes=new Set();
+ for(const r of results){
+  if(r.status==='not_selected')continue;
+  if(r.status==='not_found'){missing.push(label(r.client));continue;}
+  const warnings=r.warnings??r.plan?.warnings??[];
+  let text,mark='✓';
+  if(r.status==='configured')text='Configuration applied'+preset(r.appliedPreset);
+  else if(r.status==='unchanged'||r.status==='planned'&&r.plan?.files?.length===0)text='Already up to date'+preset(r.appliedPreset);
+  else if(r.status==='planned'){text='Would configure'+preset(r.targetPreset);mark='·';}
+  else if(r.status==='invalid'){text='Client executable identity could not be verified';mark='!';}
+  else if(r.status==='timeout'){text='Client detection timed out';mark='!';}
+  else {text=reason(r.error??warnings[0]);mark='!';}
+  lines.push(row(r.client,text,mark));
+  if(r.status==='prerequisite'&&r.appliedReleaseVersion&&/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(r.appliedReleaseVersion))lines.push(`  Existing configuration retained · ${r.appliedReleaseVersion}${preset(r.appliedPreset)}`);
+  if(['configured','unchanged','planned'].includes(r.status))for(const warning of warnings)notes.add(NOTES[warning]??`Client note: ${code(warning)}`);
+ }
+ if(missing.length)lines.push(`Skipped: ${missing.join(', ')} — not installed.`);
+ if(changed.length)lines.push('',`Open a new session in ${changed.map(r=>label(r.client)).join(', ')} to load the changes.`);
+ if(results.some(r=>r.error==='OWNED_DRIFT'))lines.push('Review local edits before retrying; APK will not overwrite them.');
+ if(results.some(r=>(r.warnings??r.plan?.warnings??[]).includes('kimi-provisioned-models-required')))lines.push('Configure the selected model aliases in Kimi, then run the same command again.');
+ if(notes.size)lines.push('',...notes);
+ lines.push('Native configuration only; model execution was not checked.');
+ return lines;
+}
+function uninstall(result,{apply}){
+ const results=result.results??(result.client?[result]:[]);
+ const lines=[!apply?'Preview · no files changed':result.status==='partial'?'Removal incomplete':result.status==='not_installed'?'Nothing to remove':'Configuration removal',''];
+ for(const r of results){const bad=r.status==='error';lines.push(row(r.client,bad?reason(r.error):r.status==='unchanged'||r.files?.length===0?'Nothing to remove':apply?'Configuration removed':'Would remove',bad?'!':apply?'✓':'·'));}
+ return lines;
+}
+const setting=value=>typeof value==='string'&&/^[A-Za-z0-9][A-Za-z0-9 _.:@/\[\]-]{0,127}$/.test(value)?value:'native default';
+function show(result){
+ const lines=['User configuration · subagents',''];
+ for(const[id,c]of Object.entries(result.clients??{})){
+  lines.push(`${label(id)}${c.status==='attention'?' · incomplete read':c.status==='not_configured'?' · no explicit subagent settings':''}`);
+  if(c.status!=='not_configured'){
+   if(c.defaults.enabled===false)lines.push('  Subagents explicitly disabled.');
+   lines.push(`  Default model: ${setting(c.defaults.model)} · effort: ${setting(c.defaults.effort)}`);
+   lines.push(`  Max concurrent: ${Number.isSafeInteger(c.concurrency.value)?c.concurrency.value:'not explicitly set'}${c.concurrency.kind==='guidance'?' (guidance)':' (native setting)'}`);
+   for(const role of c.roles)lines.push(`  ${setting(role.name).padEnd(22)} ${setting(role.model)} · ${setting(role.effort)}${role.modelSelection==='guidance'?' (routing guidance)':role.modelSelection==='parent'?' (parent selects model)':''}${role.enabled===false?' (delegation disabled)':''}`);
+   for(const entry of c.pool)lines.push(`  Pool: ${setting(entry.alias)} · ${setting(entry.effort)}${entry.configured?'':' · alias not provisioned'}`);
+   for(const[field,value]of Object.entries(c.overrides??{}))lines.push(`  Override ${field}: ${typeof value==='boolean'?String(value):typeof value==='number'?value:setting(value)}`);
+  }
+  if(c.apk.status==='modified')lines.push('  APK-managed files have local edits; the values above come from current files.');
+  for(const warning of c.warnings)lines.push(`  ! ${code(warning)}`);
+  lines.push('');
+ }
+ lines.push('User-level files only; project, managed and session settings may override them.','Native configuration only; model execution was not checked.');
+ return lines;
+}
+export function formatResult(command,result,{version='',apply=false}={}){
+ let lines;
+ if(result.error)lines=[`Operation failed (${code(result.error)})`];
+ else if(command==='setup'||command==='install')lines=setup(result,{apply});
+ else if(command==='uninstall')lines=uninstall(result,{apply});
+ else if(command==='show')lines=show(result);
+ else if(command==='init')lines=['Preferences created.'];
+ else if(command==='detect')lines=result.map(r=>row(r.client,r.status==='detected'?`Detected${typeof r.version==='string'&&/^[0-9A-Za-z.+-]{1,128}$/.test(r.version)?' · '+r.version:''}`:r.status==='not_found'?'Not installed':r.status==='timeout'?'Detection timed out':'Identity unverified',r.status==='detected'?'✓':r.status==='not_found'?'·':'!'));
+ else if(command==='doctor'){
+  lines=['Configuration check',''];
+  for(const[client,r]of Object.entries(result.clients??{})){const c=r.configuration;lines.push(row(client,c.status==='verified'?`Verified${preset(c.preset)}`:c.status==='not_configured'?'Not configured':reason(c.reason),c.status==='attention'?'!':c.status==='verified'?'✓':'·'));}
+  lines.push('Native configuration only; model execution was not checked.');
+ }else if(command==='release')lines=[`Configuration release ${/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(result.version)?result.version:''}${preset(result.preset)}`,'','Use setup --release to preview; add --apply to configure.'];
+ else lines=['Operation completed.'];
+ return [`Agent Policy Kit${/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(version)?' · '+version:''}`,'',...lines].join('\n')+'\n';
+}

package/src/policy.mjs

@@ -0,0 +1,45 @@
+import catalog from '../models/catalog.json' with {type:'json'};
+import {ROLES,ROLE_IDS,selectedRoleIds} from './roles.mjs';
+export {ROLES} from './roles.mjs';
+export const CLIENTS = Object.freeze(['codex', 'claude', 'kimi', 'agy', 'grok']);
+export const rolePreference=(config,role)=>config.roles?.[role]??config[ROLES[role]];
+export const NATIVE_EFFORTS=Object.freeze(Object.fromEntries(CLIENTS.map(client=>[client,Object.freeze([...catalog.clients[client].efforts])])));
+const identifier = /^[A-Za-z0-9][A-Za-z0-9._:@/\[\]-]{0,127}$/;
+function invalid() { throw Object.assign(new Error('Invalid shared preferences.'), {code:'INVALID_POLICY'}); }
+function object(value, fields) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype,null].includes(Object.getPrototypeOf(value))) invalid();
+  for (const [key,descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+    if (!fields.includes(key) || descriptor.get || descriptor.set) invalid();
+  }
+}
+function model(value) { if (typeof value !== 'string' || !identifier.test(value)) invalid(); }
+function freeze(value) { for (const child of Object.values(value)) if (child && typeof child === 'object') freeze(child); return Object.freeze(value); }
+export function validatePolicy(value) {
+  object(value,['schemaVersion','maxConcurrent','clients','selectedRoles']);
+  if (value.schemaVersion !== 1 || !Number.isInteger(value.maxConcurrent) || value.maxConcurrent < 1 || value.maxConcurrent > 32) invalid();
+  if(value.selectedRoles!==undefined&&(!Array.isArray(value.selectedRoles)||!value.selectedRoles.length||value.selectedRoles.length>ROLE_IDS.length||new Set(value.selectedRoles).size!==value.selectedRoles.length||value.selectedRoles.some(role=>!ROLE_IDS.includes(role))))invalid();
+  object(value.clients,CLIENTS);
+  if (!Object.keys(value.clients).length) invalid();
+  for (const [client,config] of Object.entries(value.clients)) {
+    object(config,['code','light','roles','avoidModels','maxConcurrent']);
+    if(config.maxConcurrent!==undefined&&(!Number.isInteger(config.maxConcurrent)||config.maxConcurrent<1||config.maxConcurrent>32))invalid();
+    if(config.roles!==undefined)object(config.roles,Object.keys(ROLES));
+    for (const selected of [config.code,config.light,...Object.values(config.roles??{})]) {
+      object(selected,['model','effort']); model(selected.model);
+      if (client === 'kimi' && selected.model === 'primary') invalid();
+      if(client==='agy'&&!['pro','flash','flash_lite','inherit'].includes(selected.model))invalid();
+      if(selected.effort!==null){
+        if(!NATIVE_EFFORTS[client].includes(selected.effort))invalid();
+        const known=catalog.clients[client].models.find(model=>model.id===selected.model);
+        if(known&&!known.efforts.includes(selected.effort))invalid();
+      }
+    }
+    if (!Array.isArray(config.avoidModels) || config.avoidModels.length > 32 || new Set(config.avoidModels).size !== config.avoidModels.length) invalid();
+    config.avoidModels.forEach(model);
+    const effective=selectedRoleIds(value).map(role=>rolePreference(config,role));
+    if (effective.some(selected=>config.avoidModels.includes(selected.model))) invalid();
+    const pinned=effective.filter(value=>value.effort!==null);
+    if (client==='kimi'&&new Set(pinned.map(v=>v.model+'\0'+v.effort)).size!==new Set(pinned.map(v=>v.model)).size) invalid();
+  }
+  return freeze(JSON.parse(JSON.stringify(value)));
+}

package/src/release.mjs

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import {createHash} from 'node:crypto';
+import {validatePolicy} from './policy.mjs';
+
+export const PACKAGE_VERSION=JSON.parse(fs.readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
+const canonical=value=>Array.isArray(value)?value.map(canonical):value&&typeof value==='object'?Object.fromEntries(Object.keys(value).sort().map(key=>[key,canonical(value[key])])):value;
+export const PRESETS=Object.freeze([{id:'fast',label:'Light',description:'Light models for every role. Limits last longest.'},{id:'balanced',label:'Standard',description:'Stronger models for code, review, tests and docs. Fits most plans.'},{id:'quality',label:'Top-tier',description:'High-end models for most roles. Uses limits fastest.',topModels:Object.freeze({codex:'gpt-6-astra',claude:'claude-fable-5-1',kimi:'kimi-code/k3.1-pro'})}].map(Object.freeze));
+export function presetPreferences(id='balanced'){
+  if(!PRESETS.some(preset=>preset.id===id))throw Object.assign(new Error('Unknown preset.'),{code:'UNKNOWN_PRESET'});
+  return validatePolicy(JSON.parse(fs.readFileSync(new URL(`../policies/${id}.json`,import.meta.url),'utf8')));
+}
+export function modelCatalog(){return JSON.parse(fs.readFileSync(new URL('../models/catalog.json',import.meta.url),'utf8'));}
+
+export function bundledReleaseInfo(preset='balanced'){
+  const preferences=presetPreferences(preset);
+  return {schemaVersion:1,version:PACKAGE_VERSION,preset,presets:PRESETS,catalogReviewedAt:modelCatalog().reviewedAt,
+    preferencesHash:createHash('sha256').update(JSON.stringify(canonical(preferences))).digest('hex'),
+    notes:fs.readFileSync(new URL('../CHANGELOG.md',import.meta.url),'utf8')};
+}

package/src/roles.mjs

@@ -0,0 +1,13 @@
+const noChildren=' Do not create child agents; return any need for further delegation to the parent.';
+export const ROLE_DEFINITIONS=Object.freeze([
+ {id:'worker',name:'Coder',kind:'code',assignment:'scoped implementation and fixes',description:'Implements scoped changes, preserves peers\' edits, and verifies the result.',prompt:'Implement the assigned change or fix within the assigned files. You share the workspace with other agents: preserve their edits. Verify the result and report changes, checks, and remaining limitations.'},
+ {id:'reviewer',name:'Reviewer',kind:'code',assignment:'read-only correctness, security and regression review',description:'Reviews correctness, security and regressions without edits; reports actionable evidence.',prompt:'Review the assigned change without editing files. Find actionable correctness, security, and regression issues. Report each finding with file and line evidence and explain its impact; distinguish confirmed issues from uncertainty.'},
+ {id:'explorer',name:'Code explorer',kind:'light',assignment:'read-only code and documentation discovery',description:'Maps code and documentation, cites sources, and separates facts from uncertainty.',prompt:'Explore the assigned code and documentation without editing files. Return a concise map or factual answer with source paths or citations. Distinguish verified facts from assumptions and unknowns.'},
+ {id:'tester',name:'Test writer',kind:'code',assignment:'test creation and targeted execution',description:'Writes behavior and edge-case tests, reproduces issues, and runs targeted checks.',prompt:'Own the assigned tests and targeted execution. Reproduce the issue or establish a baseline, then test observable behavior and edge cases. Never weaken checks to make them pass. Do not edit application code unless explicitly assigned. Preserve peers\' edits and report results and limitations.'},
+ {id:'writer',name:'Docs writer',kind:'light',assignment:'assigned documentation, examples and release notes',description:'Updates assigned docs and examples, verifies claims, and keeps terminology consistent.',prompt:'Update only the assigned documentation, examples, or release notes. Verify claims against code or cited sources and use consistent terminology. Do not edit application code. Preserve peers\' edits and report changes and unknowns.'},
+ {id:'routine',name:'Task runner',kind:'light',assignment:'explicit commands and mechanical edits',description:'Runs prescribed commands and mechanical edits; returns ambiguous decisions to the parent.',prompt:'Execute only the prescribed commands or clearly specified mechanical edits. Preserve other agents\' work and report the outcome. Do not make ambiguous design or behavior decisions; return those decisions to the parent.'}
+].map(role=>Object.freeze({...role,prompt:role.prompt+noChildren})));
+export const ROLES=Object.freeze(Object.fromEntries(ROLE_DEFINITIONS.map(role=>[role.id,role.kind])));
+export const ROLE_IDS=Object.freeze(Object.keys(ROLES));
+export const LEGACY_ROLE_IDS=Object.freeze(['worker','reviewer','explorer','routine']);
+export const selectedRoleIds=policy=>ROLE_IDS.filter(role=>policy.selectedRoles===undefined||policy.selectedRoles.includes(role));

package/src/setup.mjs

@@ -0,0 +1,66 @@
+import { detectClients, resolveClient, summarizeDetection } from './detect.mjs';
+import { planInstall, applyInstall, summarizePlan, inspectConfiguration } from './install.mjs';
+import { nativeHomeConflict } from './native.mjs';
+import { PACKAGE_VERSION } from './release.mjs';
+import { CLIENTS } from './policy.mjs';
+
+const ERRORS = new Set(['INVALID_PRESET','INVALID_RELEASE','LEGACY_RUNTIME_RECEIPT','INVALID_CLIENT','INVALID_POLICY','INVALID_JSON','INVALID_TOML','UNSUPPORTED_CONFIG','UNSUPPORTED_TOML_STRUCTURE','UNSUPPORTED_TOML_VALUE','CODEX_CAP_ALIAS_CONFLICT','OWNERSHIP_CONFLICT','INVALID_RECEIPT','OWNED_DRIFT','INSTALLATION_CONFLICT','POLICY_CONFLICT','UNSAFE_PATH','UNSAFE_FILE','STALE_PLAN','RECOVERY_REQUIRED','ROLLBACK_CONFLICT','INVALID_PLAN','PLATFORM_UNSUPPORTED','INSTALL_LOCKED','INSTALL_FAILED','EACCES','EPERM','ENOENT','ENOSPC','EIO','EROFS']);
+const safeError = error => ERRORS.has(error?.code) ? error.code : 'SETUP_FAILED';
+function actions(client,warnings) {
+  return warnings.map(code=>({client,code,automatable:false}));
+}
+
+const RELEASE_FIELDS=['targetReleaseVersion','targetSource','previousReleaseVersion','previousSource','appliedReleaseVersion','appliedSource','targetPreset','previousPreset','appliedPreset'];
+function releaseMetadata(value) {return Object.fromEntries(RELEASE_FIELDS.map(key=>[key,value[key]??null]));}
+
+export async function setupDetected({home,stateDir,policyPath,apply=false,client=null,env=process.env,hostHome,explicitHome=false,releaseVersion,replace=false,source='release',enabledClients=CLIENTS,preset=null} = {}) {
+  if(!Array.isArray(enabledClients)||enabledClients.some(value=>!CLIENTS.includes(value))||new Set(enabledClients).size!==enabledClients.length)throw Object.assign(new Error('INVALID_CLIENT'),{code:'INVALID_CLIENT'});
+  const selectionConflict=client!==null&&!enabledClients.includes(client);
+  const records = client === null ? await detectClients({env,hostHome}) : [await resolveClient(client,{env,hostHome})];
+  const detected = summarizeDetection(records), results = [], requiredActions = [];
+  const available = records.filter(r=>r.status === 'detected'&&enabledClients.includes(r.client));
+  for (const record of records) {
+    if(!enabledClients.includes(record.client)) {
+      if(selectionConflict) {const warnings=['client-not-selected'];results.push({client:record.client,status:'prerequisite',warnings});requiredActions.push(...actions(record.client,warnings));}
+      else results.push({client:record.client,status:'not_selected'});
+      continue;
+    }
+    let retained;
+    if(record.status!=='detected'||(!explicitHome&&nativeHomeConflict(record.client,home,env))) {
+      try {
+        const applied=await inspectConfiguration({client:record.client,home,stateDir});
+        retained={targetReleaseVersion:releaseVersion??PACKAGE_VERSION,targetSource:source,previousReleaseVersion:applied.releaseVersion,previousSource:applied.source,appliedReleaseVersion:applied.releaseVersion,appliedSource:applied.source,targetPreset:preset,previousPreset:applied.preset,appliedPreset:applied.preset};
+      } catch(error) {
+        const code=safeError(error);results.push({client:record.client,status:'error',error:code});requiredActions.push({client:record.client,code,automatable:false});continue;
+      }
+    }
+    if (record.status !== 'detected') {
+      results.push({client:record.client,status:record.status,...retained});
+      if (record.status === 'invalid' || record.status === 'timeout') requiredActions.push({client:record.client,code:record.status === 'timeout' ? 'native_client_detection_timeout' : 'native_client_identity_unverified',automatable:true});
+      continue;
+    }
+    if(!explicitHome&&nativeHomeConflict(record.client,home,env)) {
+      const warnings=['native-home-override-unsupported'];
+      results.push({client:record.client,status:'prerequisite',warnings,...retained});
+      requiredActions.push(...actions(record.client,warnings));
+      continue;
+    }
+    try {
+      // Planning and applying are sequential per client: the preceding transaction
+      // can create shared policy/receipts that the next plan must capture afresh.
+      const plan = await planInstall({client:record.client,home,stateDir,policyPath,releaseVersion,replace,source,preset});
+      requiredActions.push(...actions(record.client,plan.warnings));
+      if (plan.status === 'prerequisite') { results.push({client:record.client,status:'prerequisite',plan:summarizePlan(plan),...releaseMetadata(plan)}); continue; }
+      if (apply) {
+        const result = await applyInstall(plan);
+        results.push({client:record.client,status:result.status === 'unchanged' ? 'unchanged' : 'configured',changedFiles:result.changedFiles,warnings:[...result.warnings],...releaseMetadata(result)});
+      } else results.push({client:record.client,status:'planned',plan:summarizePlan(plan),...releaseMetadata(plan)});
+    } catch (error) {
+      const code = safeError(error);
+      results.push({client:record.client,status:'error',error:code});
+      requiredActions.push({client:record.client,code,automatable:false});
+    }
+  }
+  const failed = results.some(r=>['error','prerequisite','invalid','timeout'].includes(r.status));
+  return {schemaVersion:1,status:selectionConflict ? 'partial' : available.length === 0 ? 'no_clients' : failed ? 'partial' : apply ? 'configured' : 'planned',detected,results,requiredActions,exitCode:available.length === 0 || failed ? 3 : 0};
+}

package/src/share.mjs

@@ -0,0 +1,172 @@
+// Pure URL state codec, also embedded in the offline configuration page.
+const SHARE_BYTES=65536,SHARE_TOKEN=87384;
+const SHARE_VERSION=/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?$/;
+const SHARE_UNSAFE=new Set(['__proto__','constructor','prototype']);
+function invalidShare(){throw Object.assign(new Error('Invalid shared configuration link.'),{code:'INVALID_SHARE_LINK'});}
+
+// Inspect descriptors before reading any user-supplied value. UI-only cached data is
+// allowed, but accessors, exotic prototypes, sparse arrays and hidden fields are not.
+function shareData(value,depth=0,budget={left:100000}){
+ if(--budget.left<0||depth>32)invalidShare();
+ if(value===null||value===undefined||typeof value==='string'||typeof value==='boolean')return;
+ if(typeof value==='number'){if(!Number.isFinite(value))invalidShare();return;}
+ if(typeof value!=='object')invalidShare();
+ const array=Array.isArray(value),prototype=Object.getPrototypeOf(value);
+ if(array?prototype!==Array.prototype:prototype!==Object.prototype&&prototype!==null)invalidShare();
+ const fields=Object.getOwnPropertyDescriptors(value),keys=Reflect.ownKeys(fields);
+ if(array&&(keys.length!==value.length+1||value.length>100000))invalidShare();
+ for(const key of keys){
+  if(typeof key!=='string'||SHARE_UNSAFE.has(key))invalidShare();
+  const field=fields[key];
+  if(!Object.hasOwn(field,'value')||(!field.enumerable&&!(array&&key==='length')))invalidShare();
+  if(array&&key!=='length'&&!/^(0|[1-9]\d*)$/.test(key))invalidShare();
+  if(key!=='length'||!array)shareData(field.value,depth+1,budget);
+ }
+}
+function shareRecord(value,keys){
+ if(!value||typeof value!=='object'||Array.isArray(value))invalidShare();
+ if(keys&&(Object.keys(value).length!==keys.length||keys.some(key=>!Object.hasOwn(value,key))))invalidShare();
+ return value;
+}
+function shareList(value,known){
+ if(!Array.isArray(value)||value.length>known.length||new Set(value).size!==value.length||value.some(id=>typeof id!=='string'||!known.includes(id)))invalidShare();
+ return [...value];
+}
+function shareRelease(release){
+ shareData(release);shareRecord(release);
+ if(typeof release.version!=='string'||!SHARE_VERSION.test(release.version))invalidShare();
+ const preferences=shareRecord(release.preferences),clients=Object.keys(shareRecord(preferences.clients));
+ const catalog=shareRecord(shareRecord(release.catalog).clients);
+ if(!clients.length||clients.some(id=>!Object.hasOwn(catalog,id)||!Array.isArray(catalog[id].efforts)||catalog[id].efforts.some(level=>typeof level!=='string')))invalidShare();
+ if(!Array.isArray(release.roles)||!release.roles.length||!Array.isArray(release.presets)||!release.presets.length)invalidShare();
+ const roles=new Map(),presets=new Map();
+ for(const role of release.roles){
+  shareRecord(role);if(typeof role.id!=='string'||!role.id||SHARE_UNSAFE.has(role.id)||roles.has(role.id)||!['code','light'].includes(role.kind))invalidShare();
+  roles.set(role.id,role);
+ }
+ for(const preset of release.presets){
+  shareRecord(preset);if(typeof preset.id!=='string'||!preset.id||preset.id==='custom'||SHARE_UNSAFE.has(preset.id)||presets.has(preset.id))invalidShare();
+  shareRecord(shareRecord(preset.preferences).clients);
+  if(preset.topModels!==undefined&&Object.values(shareRecord(preset.topModels)).some(model=>typeof model!=='string'))invalidShare();
+  presets.set(preset.id,preset);
+ }
+ if(!presets.has(release.preset))invalidShare();
+ return {clients,roles,presets,catalog};
+}
+function shareChoice(choice,id,metadata){
+ shareRecord(choice,['model','effort']);
+ if(typeof choice.model!=='string'||choice.model.length>128||(choice.effort!==null&&(['agy','grok'].includes(id)||!metadata.catalog[id].efforts.includes(choice.effort))))invalidShare();
+ return {model:choice.model,effort:choice.effort};
+}
+function sharePayload(payload,release,metadata){
+ shareRecord(payload);const legacy=payload.v===1;
+ if(!legacy&&payload.v!==2)invalidShare();
+ shareRecord(payload,legacy?['v','release','roles','tools','scope','maxConcurrent']:['v','release','roles','tools','scope']);
+ if(typeof payload.release!=='string'||payload.release.length>128||!SHARE_VERSION.test(payload.release))invalidShare();
+ if(legacy&&(!Number.isInteger(payload.maxConcurrent)||payload.maxConcurrent<1||payload.maxConcurrent>32))invalidShare();
+ if(payload.release!==release.version){
+  // Validate the wire shape without imposing today's models or preset values on
+  // an older release. Invalid links must never turn into navigation.
+  const identifier=value=>typeof value==='string'&&/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value);
+  if(!Array.isArray(payload.roles)||payload.roles.length>1000||payload.roles.some(role=>!identifier(role)))invalidShare();
+  const roles=shareList(payload.roles,payload.roles),ids=[];
+  if(!Array.isArray(payload.tools)||payload.tools.length>32)invalidShare();
+  for(const tool of payload.tools){
+   shareRecord(tool,legacy?['id','mode','base','choices']:['id','mode','base','choices','maxConcurrent']);if(!legacy&&(!Number.isInteger(tool.maxConcurrent)||tool.maxConcurrent<1||tool.maxConcurrent>32))invalidShare();if(!identifier(tool.id)||ids.includes(tool.id)||!identifier(tool.base)||(tool.mode!==null&&!identifier(tool.mode)))invalidShare();ids.push(tool.id);
+   shareRecord(tool.choices,roles);for(const role of roles){const choice=shareRecord(tool.choices[role],['model','effort']);if(typeof choice.model!=='string'||choice.model.length>128||(choice.effort!==null&&(typeof choice.effort!=='string'||choice.effort.length>32)))invalidShare();}
+  }
+  if(payload.scope!==null&&(typeof payload.scope!=='string'||(payload.scope==='all'?ids.length<2:!ids.includes(payload.scope))))invalidShare();
+  throw Object.assign(new Error('This link uses a different release.'),{code:'SHARE_RELEASE_MISMATCH',releaseVersion:payload.release});
+ }
+ const roles=shareList(payload.roles,[...metadata.roles.keys()]);
+ if(!Array.isArray(payload.tools)||payload.tools.length>metadata.clients.length)invalidShare();
+ const selected=[];
+ const tools=payload.tools.map(tool=>{
+  shareRecord(tool,legacy?['id','mode','base','choices']:['id','mode','base','choices','maxConcurrent']);if(!legacy&&(!Number.isInteger(tool.maxConcurrent)||tool.maxConcurrent<1||tool.maxConcurrent>32))invalidShare();
+  const {id,mode,base}=tool;
+  if(!metadata.clients.includes(id)||selected.includes(id)||!metadata.presets.has(base)||(mode!==null&&mode!=='custom'&&!metadata.presets.has(mode)))invalidShare();
+  selected.push(id);shareRecord(tool.choices,roles);
+  const choices=Object.fromEntries(roles.map(role=>[role,shareChoice(tool.choices[role],id,metadata)]));
+  if(mode!==null&&mode!=='custom'){
+   if(mode!==base)invalidShare();
+   const named=metadata.presets.get(mode),preset=named.preferences,clients=preset.clients;
+   if(!legacy&&tool.maxConcurrent!==(clients[id]?.maxConcurrent??preset.maxConcurrent))invalidShare();
+   if(!Object.hasOwn(clients,id))invalidShare();
+   const preferences=shareRecord(clients[id]),own=role=>preferences.roles&&Object.hasOwn(preferences.roles,role);
+   // A preset's optional top model replaces every shared code role that has no role-specific choice, or none of them.
+   const top=named.topModels&&Object.hasOwn(named.topModels,id)?named.topModels[id]:null;
+   const topRoles=roles.filter(role=>metadata.roles.get(role).kind==='code'&&!own(role)),topped=top!==null&&topRoles.some(role=>choices[role].model===top);
+   for(const role of roles){
+    const expected=own(role)?preferences.roles[role]:preferences[metadata.roles.get(role).kind];
+    const choice=shareChoice(expected,id,metadata);if(topped&&topRoles.includes(role))choice.model=top;
+    if(choice.model!==choices[role].model||choice.effort!==choices[role].effort)invalidShare();
+   }
+  }
+  return {id,mode,base,choices,...(legacy?{}:{maxConcurrent:tool.maxConcurrent})};
+ });
+ const scope=payload.scope;
+ if(scope!==null&&(typeof scope!=='string'||(scope==='all'?tools.length<2:!selected.includes(scope))))invalidShare();
+ return {v:payload.v,release:payload.release,roles,tools,scope,...(legacy?{maxConcurrent:payload.maxConcurrent}:{})};
+}
+function shareBase64(bytes){return btoa(Array.from(bytes,byte=>String.fromCharCode(byte)).join('')).replaceAll('+','-').replaceAll('/','_').replace(/=+$/,'');}
+function shareJson(text){
+ const payload=JSON.parse(text),stack=[];
+ // JSON.parse validates syntax; this small token pass preserves duplicate-key
+ // evidence that JSON.parse would otherwise discard, including escaped names.
+ const tokens=text.match(/"(?:[^"\\]|\\.)*"|[{}\[\]:,]/g)??[];
+ for(let at=0;at<tokens.length;at++){
+  const token=tokens[at];
+  if(token==='{')stack.push(new Set());
+  else if(token==='[')stack.push(null);
+  else if(token==='}'||token===']')stack.pop();
+  else if(token[0]==='"'&&tokens[at+1]===':'){
+   const key=JSON.parse(token),keys=stack.at(-1);
+   if(!keys||keys.has(key)||SHARE_UNSAFE.has(key))invalidShare();keys.add(key);
+  }
+ }
+ return payload;
+}
+
+export function encodeFormState(snapshot,release){
+ try{
+  shareData(snapshot);shareRecord(snapshot);
+  const metadata=shareRelease(release),state=shareRecord(snapshot.state),profiles=shareRecord(state.profiles),jobs=shareRecord(state.jobs);
+  const roles=shareList(snapshot.helpers,[...metadata.roles.keys()]),selected=shareList(snapshot.pickedTools,metadata.clients);
+  const modern=Object.values(profiles).some(profile=>Object.hasOwn(profile,'maxConcurrent'));
+  const tools=selected.map(id=>{
+   if(!Object.hasOwn(profiles,id)||!Object.hasOwn(jobs,id))invalidShare();
+   const profile=shareRecord(profiles[id]),choices=shareRecord(jobs[id]);
+   if(typeof profile.custom!=='boolean'||(profile.modeSelected!==undefined&&typeof profile.modeSelected!=='boolean'))invalidShare();
+   return {id,...(modern?{maxConcurrent:Object.hasOwn(profile,'maxConcurrent')?profile.maxConcurrent:state.maxConcurrent}:{}),mode:profile.modeSelected===false?null:profile.custom?'custom':profile.presetId,base:profile.presetId,choices:Object.fromEntries(roles.map(role=>{
+    if(!Object.hasOwn(choices,role))invalidShare();return [role,shareChoice(choices[role],id,metadata)];
+   }))};
+  });
+  const payload=sharePayload({v:modern?2:1,release:release.version,roles,tools,scope:snapshot.selectedScope,...(modern?{}:{maxConcurrent:state.maxConcurrent})},release,metadata);
+  if(!roles.length&&!tools.length)return '';
+  const bytes=new TextEncoder().encode(JSON.stringify(payload));if(bytes.length>SHARE_BYTES)invalidShare();
+  const token=shareBase64(bytes);if(token.length>SHARE_TOKEN)invalidShare();return '#setup='+token;
+ }catch(error){if(error?.code==='INVALID_SHARE_LINK'||error?.code==='SHARE_RELEASE_MISMATCH')throw error;invalidShare();}
+}
+
+export function decodeFormState(fragment,release){
+ try{
+  if(typeof fragment!=='string')invalidShare();
+  if(!fragment.startsWith('#setup='))return null;
+  const token=fragment.slice(7);
+  if(!token.length||token.length>SHARE_TOKEN||!/^[A-Za-z0-9_-]+$/.test(token)||token.length%4===1)invalidShare();
+  const binary=atob(token.replaceAll('-','+').replaceAll('_','/'));
+  if(binary.length>SHARE_BYTES)invalidShare();
+  const bytes=Uint8Array.from(binary,char=>char.charCodeAt(0));if(shareBase64(bytes)!==token)invalidShare();
+  const payload=shareJson(new TextDecoder('utf-8',{fatal:true}).decode(bytes));shareData(payload);
+  return sharePayload(payload,release,shareRelease(release));
+ }catch(error){if(error?.code==='INVALID_SHARE_LINK'||error?.code==='SHARE_RELEASE_MISMATCH')throw error;invalidShare();}
+}
+
+export function archivedReleaseUrl(error,href,hostedReleases=[]){
+ if(error?.code!=='SHARE_RELEASE_MISMATCH'||typeof error.releaseVersion!=='string'||error.releaseVersion.length>128||!SHARE_VERSION.test(error.releaseVersion)||!Array.isArray(hostedReleases)||!hostedReleases.includes(error.releaseVersion))return null;
+ try{
+  const current=new URL(href);if(!['http:','https:'].includes(current.protocol)||current.username||current.password||current.pathname!=='/'||!current.hash.startsWith('#setup='))return null;
+  const target=new URL(`/v/${error.releaseVersion}/`,current.origin);target.hash=current.hash;
+  return target.origin===current.origin?target.href:null;
+ }catch{return null;}
+}

package/src/toml.mjs

@@ -0,0 +1,96 @@
+import { parseForESLint, getStaticTOMLValue } from 'toml-eslint-parser';
+import { isDeepStrictEqual } from 'node:util';
+
+function fail(code) { throw Object.assign(new Error(code), {code}); }
+function ast(text) {
+  if (typeof text !== 'string' || Buffer.byteLength(text) > 1024 * 1024) fail('INVALID_TOML');
+  try { return parseForESLint(text, {tomlVersion:'1.0'}).ast; }
+  catch { fail('INVALID_TOML'); }
+}
+export function parseToml(text) { return getStaticTOMLValue(ast(text)); }
+const keys = key => key.keys.map(k => k.type === 'TOMLBare' ? k.name : k.value);
+const same = (a, b) => isDeepStrictEqual(a, b);
+const literal = value => {
+  if (!['string', 'number', 'boolean'].includes(typeof value) || (typeof value === 'number' && !Number.isSafeInteger(value))) fail('UNSUPPORTED_TOML_VALUE');
+  return JSON.stringify(value);
+};
+const keyText = key => /^[A-Za-z0-9_-]+$/.test(key) ? key : JSON.stringify(key);
+function locate(tree, target) {
+  for (const node of tree.body[0].body) {
+    const table = node.type === 'TOMLTable' ? node : null;
+    for (const kv of table ? table.body : [node]) {
+      if (kv.type !== 'TOMLKeyValue') continue;
+      const full = [...(table?.resolvedKey ?? []), ...keys(kv.key)];
+      if (same(full, target)) return kv;
+      if (full.length < target.length && same(full, target.slice(0, full.length))) fail('UNSUPPORTED_TOML_STRUCTURE');
+    }
+  }
+  return null;
+}
+function replace(text, start, end, value) { return text.slice(0, start) + value + text.slice(end); }
+function newline(text) { return text.includes('\r\n') ? '\r\n' : '\n'; }
+function endLine(text, position) { const i = text.indexOf('\n', position); return i === -1 ? text.length : i + 1; }
+function removeStatement(text, node) {
+  const startLine = text.lastIndexOf('\n', node.range[0] - 1) + 1;
+  const start = /^\s*$/.test(text.slice(startLine, node.range[0])) ? startLine : node.range[0];
+  const end = endLine(text, node.range[1]);
+  const tail = text.slice(node.range[1], end);
+  return replace(text, start, /^\s*$/.test(tail) ? end : node.range[1], '');
+}
+
+export function setTomlValue(text, target, value) {
+  const tree = ast(text);
+  const found = locate(tree, target);
+  const after = literal(value);
+  const ownership = {kind:'scalar',path:target,before:found ? text.slice(...found.value.range) : null,after};
+  if (found) return {text:replace(text, ...found.value.range, after),ownership};
+  const tablePath = target.slice(0, -1);
+  const tables = tree.body[0].body.filter(n => n.type === 'TOMLTable');
+  // Arrays of tables and inline/dotted parent definitions cannot be extended safely here.
+  if (tables.some(n => n.kind === 'array' && same(n.resolvedKey.slice(0, tablePath.length), tablePath))) fail('UNSUPPORTED_TOML_STRUCTURE');
+  const table = tables.find(n => n.kind === 'standard' && same(n.resolvedKey, tablePath));
+  const nl = newline(text);
+  const entry = `${keyText(target.at(-1))} = ${after}${nl}`;
+  if (table) {
+    const at = endLine(text, table.key.range[1]);
+    const separator = at === text.length && !text.endsWith('\n') ? nl : '';
+    text = replace(text, at, at, separator + entry);
+  } else if (tablePath.length === 0) {
+    text = entry + text;
+  } else {
+    const prefix = text.length && !text.endsWith('\n') ? nl : '';
+    text += `${prefix}${nl}[${tablePath.map(keyText).join('.')}]${nl}${entry}`;
+    ownership.addedTable = tablePath;
+  }
+  ast(text);
+  return {text,ownership};
+}
+
+export function restoreTomlValue(text, ownership) {
+  const tree = ast(text);
+  const found = locate(tree, ownership.path);
+  if (ownership.kind === 'removed') {
+    if (found) fail('OWNED_DRIFT');
+    if (ownership.before === null) return text;
+    const before = parseToml(`value = ${ownership.before}\n`).value;
+    return setTomlValue(text,ownership.path,before).text;
+  }
+  if (!found || text.slice(...found.value.range) !== ownership.after) fail('OWNED_DRIFT');
+  if (ownership.before !== null) return replace(text, ...found.value.range, ownership.before);
+  text = removeStatement(text, found);
+  if (ownership.addedTable) {
+    const table = ast(text).body[0].body.find(n => n.type === 'TOMLTable' && n.kind === 'standard' && same(n.resolvedKey, ownership.addedTable));
+    if (table && table.body.length === 0) text = removeStatement(text, table);
+  }
+  ast(text);
+  return text;
+}
+
+export function removeTomlValue(text,target) {
+  const tree=ast(text),found=locate(tree,target);
+  if(!found)return {text,ownership:{kind:'removed',path:target,before:null}};
+  const ownership={kind:'removed',path:target,before:text.slice(...found.value.range)};
+  const result=removeStatement(text,found);
+  ast(result);
+  return {text:result,ownership};
+}