agent-policy-kit 0.0.0-stage → 0.1.0

package/src/policy.mjs

@@ -0,0 +1,44 @@
+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']);
+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']);
+    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:'Fast & economical',description:'For small, well-defined tasks. Lighter models, with extra reasoning for review and tests.'},{id:'balanced',label:'Balanced',description:'Stronger coding and verification, lighter exploration and mechanical work.'},{id:'quality',label:'Quality first',description:'For demanding implementation and verification. Prioritizes capability over response time and usage.'}].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,141 @@
+// Pure URL state codec, also embedded in the offline configuration page.
+const SHARE_BYTES=65536,SHARE_TOKEN=87384;
+const SHARE_VERSION=/^\d+\.\d+\.\d+(?:-[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);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&&(id==='agy'||!metadata.catalog[id].efforts.includes(choice.effort))))invalidShare();
+ return {model:choice.model,effort:choice.effort};
+}
+function sharePayload(payload,release,metadata){
+ shareRecord(payload,['v','release','roles','tools','scope','maxConcurrent']);
+ if(payload.v!==1||typeof payload.release!=='string'||!SHARE_VERSION.test(payload.release))invalidShare();
+ if(payload.release!==release.version)throw Object.assign(new Error('This link uses a different release.'),{code:'SHARE_RELEASE_MISMATCH'});
+ if(!Number.isInteger(payload.maxConcurrent)||payload.maxConcurrent<1||payload.maxConcurrent>32)invalidShare();
+ 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,['id','mode','base','choices']);
+  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 clients=metadata.presets.get(mode).preferences.clients;
+   if(!Object.hasOwn(clients,id))invalidShare();
+   const preferences=shareRecord(clients[id]);
+   for(const role of roles){
+    const expected=preferences.roles&&Object.hasOwn(preferences.roles,role)?preferences.roles[role]:preferences[metadata.roles.get(role).kind];
+    const choice=shareChoice(expected,id,metadata);
+    if(choice.model!==choices[role].model||choice.effort!==choices[role].effort)invalidShare();
+   }
+  }
+  return {id,mode,base,choices};
+ });
+ const scope=payload.scope;
+ if(scope!==null&&(typeof scope!=='string'||(scope==='all'?tools.length<2:!selected.includes(scope))))invalidShare();
+ return {v:1,release:payload.release,roles,tools,scope,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 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,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:1,release:release.version,roles,tools,scope:snapshot.selectedScope,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();}
+}

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};
+}