@runeditrun/rer 0.2.85 → 0.2.87

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/README.md +138 -29
  2. package/cli/README.md +61 -1
  3. package/cli/agent-bindings.mjs +25 -0
  4. package/cli/agent-door.mjs +145 -0
  5. package/cli/agent-fixtures.mjs +16 -0
  6. package/cli/agent-journey-fixtures.mjs +17 -0
  7. package/cli/agent-mail.mjs +54 -0
  8. package/cli/agent-network.mjs +64 -0
  9. package/cli/agent-reviewers.mjs +110 -0
  10. package/cli/agent-rpc.mjs +23 -0
  11. package/cli/agent-secrets.mjs +23 -0
  12. package/cli/agent-sponsors.mjs +43 -0
  13. package/cli/agent-surface.mjs +34 -0
  14. package/cli/agent-verifier.mjs +31 -0
  15. package/cli/agent-webhooks.mjs +19 -0
  16. package/cli/authoring.mjs +2 -1
  17. package/cli/business/archive-task.mjs +32 -0
  18. package/cli/business/carry.mjs +3 -1
  19. package/cli/business/catchup-task.mjs +42 -0
  20. package/cli/business/choices.mjs +97 -0
  21. package/cli/business/command.mjs +23 -5
  22. package/cli/business/connect.mjs +19 -7
  23. package/cli/business/detector.mjs +4 -1
  24. package/cli/business/device.mjs +13 -0
  25. package/cli/business/export-inputs.mjs +69 -0
  26. package/cli/business/export-task.mjs +17 -0
  27. package/cli/business/invocation.mjs +8 -1
  28. package/cli/business/keychain.mjs +8 -1
  29. package/cli/business/lease.mjs +11 -1
  30. package/cli/business/local-commands.mjs +79 -31
  31. package/cli/business/outbound.mjs +9 -4
  32. package/cli/business/parsers-config.mjs +8 -7
  33. package/cli/business/parsers-syntax.mjs +7 -3
  34. package/cli/business/permissions.mjs +2 -0
  35. package/cli/business/questions.mjs +89 -9
  36. package/cli/business/setup-command.mjs +49 -0
  37. package/cli/business/setup-company.json +15 -0
  38. package/cli/business/setup-demo.mjs +95 -0
  39. package/cli/business/state.mjs +44 -10
  40. package/cli/business/supervisor.mjs +94 -35
  41. package/cli/business/vendor-door.mjs +230 -0
  42. package/cli/business/vendors/README.md +29 -3
  43. package/cli/business/vendors/common.mjs +8 -6
  44. package/cli/business/vendors/index.mjs +22 -11
  45. package/cli/business/vendors/sorry.mjs +106 -0
  46. package/cli/contract.mjs +2 -2
  47. package/cli/demo-deploy-error.mjs +14 -0
  48. package/cli/demo-native.mjs +4 -1
  49. package/cli/deploy-config.mjs +1 -1
  50. package/cli/deploy-owner-input.mjs +3 -1
  51. package/cli/deploy-variables.mjs +89 -0
  52. package/cli/door-clauses.mjs +157 -0
  53. package/cli/export.mjs +17 -4
  54. package/cli/hosted-output.mjs +31 -8
  55. package/cli/inspect.mjs +4 -0
  56. package/cli/jsonc.mjs +8 -4
  57. package/cli/lifecycle.mjs +3 -1
  58. package/cli/main.mjs +1 -0
  59. package/cli/managed-data-schema.mjs +14 -1
  60. package/cli/managed-data.mjs +8 -4
  61. package/cli/portability-empty.mjs +6 -0
  62. package/cli/portability-migrations.mjs +26 -4
  63. package/cli/portability-worker.mjs +2 -1
  64. package/cli/portability.mjs +1 -0
  65. package/cli/production-auth.mjs +2 -2
  66. package/cli/production-mail.mjs +19 -3
  67. package/cli/server-registry.mjs +2 -0
  68. package/edition-authoring/archive-source.mjs +65 -0
  69. package/edition-authoring/base-copies.mjs +108 -21
  70. package/edition-authoring/cli.mjs +1 -1
  71. package/edition-authoring/copy-namespaces.mjs +28 -0
  72. package/edition-authoring/edition-migrations.mjs +7 -3
  73. package/edition-authoring/files.mjs +2 -1
  74. package/edition-authoring/module-closure.mjs +58 -27
  75. package/edition-authoring/module-edges.mjs +13 -2
  76. package/edition-authoring/workflow-copies.mjs +1 -1
  77. package/edition-authoring/workflow-scripts.mjs +12 -3
  78. package/foundation/runtime/contract-docs.mjs +220 -32
  79. package/foundation/runtime/contract-prose-patterns.mjs +14 -0
  80. package/foundation/runtime/contract-prose.mjs +88 -0
  81. package/global/CHANGELOG.md +151 -0
  82. package/global/README.md +138 -29
  83. package/global/door/command.mjs +3 -1
  84. package/global/main.mjs +1 -1
  85. package/modules/agent-door/CLAUSES.md +215 -0
  86. package/modules/agent-door/conformance/audit-pages.mjs +11 -0
  87. package/modules/agent-door/conformance/audit-rows.mjs +20 -0
  88. package/modules/agent-door/conformance/audit.mjs +63 -0
  89. package/modules/agent-door/conformance/authority.d.mts +2 -0
  90. package/modules/agent-door/conformance/authority.mjs +17 -0
  91. package/modules/agent-door/conformance/crypto.mjs +36 -0
  92. package/modules/agent-door/conformance/discovery.mjs +61 -0
  93. package/modules/agent-door/conformance/fixtures.mjs +41 -0
  94. package/modules/agent-door/conformance/index.mjs +41 -0
  95. package/modules/agent-door/conformance/injection.mjs +24 -0
  96. package/modules/agent-door/conformance/invocation.mjs +33 -0
  97. package/modules/agent-door/conformance/journey.mjs +117 -0
  98. package/modules/agent-door/conformance/narrowing.d.mts +2 -0
  99. package/modules/agent-door/conformance/narrowing.mjs +29 -0
  100. package/modules/agent-door/conformance/negative.mjs +48 -0
  101. package/modules/agent-door/conformance/network-modules.mjs +86 -0
  102. package/modules/agent-door/conformance/network-runtime.mjs +46 -0
  103. package/modules/agent-door/conformance/policy-phases.mjs +83 -0
  104. package/modules/agent-door/conformance/protocol.mjs +153 -0
  105. package/modules/agent-door/conformance/replay.mjs +39 -0
  106. package/modules/agent-door/conformance/schema.mjs +71 -0
  107. package/modules/agent-door/conformance/security.mjs +34 -0
  108. package/modules/agent-door/conformance/sponsors.mjs +68 -0
  109. package/modules/agent-door/conformance/step-hooks.mjs +4 -0
  110. package/modules/agent-door/conformance/surface.mjs +92 -0
  111. package/modules/agent-door/conformance/target.mjs +19 -0
  112. package/modules/agent-door/conformance/tool-name.d.mts +1 -0
  113. package/modules/agent-door/conformance/tool-name.mjs +7 -0
  114. package/modules/agent-door/conformance/webhooks.mjs +31 -0
  115. package/modules/container/image-variables.mjs +8 -2
  116. package/modules/delivery-producer/mail.mjs +20 -0
  117. package/modules/demo-host/README.md +6 -0
  118. package/modules/demo-host/ownership.mjs +39 -0
  119. package/modules/demo-host/plan.mjs +2 -1
  120. package/modules/demo-host/remove.mjs +6 -1
  121. package/modules/import-kit/schema/importer-verification-receipt.schema.json +171 -0
  122. package/modules/import-kit/schema/importers.schema.json +107 -0
  123. package/modules/import-kit/src/door/ADOPTING.md +20 -0
  124. package/modules/import-kit/src/door/README.md +2 -1
  125. package/modules/import-kit/src/door/admission.ts +5 -3
  126. package/modules/import-kit/src/door/archive.ts +5 -2
  127. package/modules/import-kit/src/door/authority.ts +1 -0
  128. package/modules/import-kit/src/door/grants.ts +1 -1
  129. package/modules/import-kit/src/door/handler.ts +14 -8
  130. package/modules/import-kit/src/door/index.ts +1 -1
  131. package/modules/import-kit/src/door/jobs.ts +40 -0
  132. package/modules/import-kit/src/door/operator.ts +3 -3
  133. package/modules/import-kit/src/door/planning.ts +10 -6
  134. package/modules/import-kit/src/door/protocol.ts +2 -2
  135. package/modules/import-kit/src/door/raw.ts +25 -0
  136. package/modules/import-kit/src/door/refusals.ts +1 -0
  137. package/modules/import-kit/src/door/types.ts +26 -6
  138. package/modules/import-kit/src/receipt/encoding.ts +37 -0
  139. package/modules/import-kit/src/receipt/index.ts +69 -0
  140. package/modules/import-kit/src/receipt/policy.ts +24 -0
  141. package/modules/import-kit/src/receipt/types.ts +64 -0
  142. package/modules/import-kit/src/receipt/uri.ts +45 -0
  143. package/modules/import-kit/src/receipt/validation.ts +87 -0
  144. package/modules/import-kit/src/status/encoding.ts +13 -0
  145. package/modules/import-kit/src/status/evidence.ts +218 -0
  146. package/modules/import-kit/src/status/index.ts +56 -0
  147. package/modules/import-kit/src/status/schema.ts +208 -0
  148. package/modules/import-kit/src/status/types.ts +86 -0
  149. package/modules/operator-auth/accounts/delegated.mjs +48 -0
  150. package/modules/operator-auth/index.d.mts +7 -0
  151. package/modules/operator-auth/service.mjs +2 -0
  152. package/modules/portability/README.md +37 -13
  153. package/modules/portability/bridge.mjs +22 -2
  154. package/modules/portability/catalogue.mjs +12 -2
  155. package/modules/portability/copies.mjs +8 -1
  156. package/modules/portability/derived.mjs +33 -0
  157. package/modules/portability/http-errors.mjs +1 -1
  158. package/modules/portability/import.mjs +14 -7
  159. package/package.json +4 -2
  160. package/scripts/publish-check/copy_identities.py +3 -1
  161. package/scripts/publish-check/github_refs.py +32 -13
  162. package/cli/business/opt-ins.mjs +0 -37
@@ -0,0 +1,49 @@
1
+ import { constants } from 'node:fs';
2
+ import { open } from 'node:fs/promises';
3
+ import { setupDemo } from './setup-demo.mjs';
4
+
5
+ // The platform command prints its receipt as JSON in both human and --json mode.
6
+ export async function setupCommand(args) {
7
+ try { return await setup(args) ?? 0; }
8
+ catch (error) {
9
+ // Paths, cookies and peer bodies must never appear in diagnostics.
10
+ const code=typeof error?.message==='string'&&/^[a-z0-9_]{1,100}$/.test(error.message)?error.message:'demo_setup_failed';
11
+ process.stderr.write(JSON.stringify({code})+'\n');return 1;
12
+ }
13
+ }
14
+
15
+ async function setup(args){
16
+ const usage='Usage: rer business setup --origin URL --session-file FILE --confirm-demo [--hosting managed|assisted|self_host] [--wait-seconds 0..240] [--json]';
17
+ if(args.some(arg => ['--help', '-h'].includes(arg))){process.stdout.write(usage+'\n');return;}
18
+ const options={};
19
+ for(let i=0;i<args.length;i++){
20
+ if(args[i]==='--json'&&!options.json){options.json=true;continue;}
21
+ if(args[i]==='--confirm-demo'){options.confirm=true;continue;}
22
+ if(!['--origin','--session-file','--hosting','--wait-seconds'].includes(args[i])||!args[i+1]||Object.hasOwn(options,args[i]))throw Error('demo_arguments_invalid');
23
+ options[args[i]]=args[++i];
24
+ }
25
+ if(!options.confirm||!options['--origin']||!options['--session-file'])throw Error('demo_confirmation_and_session_file_required');
26
+ const url=new URL(options['--origin']);
27
+ if(url.username||url.password||url.search||url.hash||url.pathname!=='/'||url.protocol!=='https:'&&!(url.protocol==='http:'&&['localhost','127.0.0.1','[::1]'].includes(url.hostname)))throw Error('demo_origin_invalid');
28
+ const hosting=options['--hosting']??'managed',waitSeconds=Number(options['--wait-seconds']??240);
29
+ if(!['managed','assisted','self_host'].includes(hosting)||!Number.isInteger(waitSeconds)||waitSeconds<0||waitSeconds>240)throw Error('demo_arguments_invalid');
30
+ const handle=await open(options['--session-file'],constants.O_RDONLY|constants.O_NOFOLLOW);
31
+ let cookie;
32
+ try{
33
+ const stat=await handle.stat();if(!stat.isFile()||(stat.mode&0o777)!==0o600||stat.uid!==process.getuid()||stat.size>16384)throw Error('demo_session_file_must_be_private');
34
+ cookie=(await handle.readFile('utf8')).trim();
35
+ }finally{await handle.close();}
36
+ if(!/^(?:__Host-)?rer_session=[^\s;]+$/.test(cookie))throw Error('demo_session_file_invalid');
37
+ const session=cookie.slice(cookie.indexOf('=')+1);
38
+ try {
39
+ const receipt=await setupDemo({origin:url.origin,cookie,hosting,waitSeconds});
40
+ const output=JSON.stringify(receipt,null,2)+'\n';
41
+ if(output.includes(session))throw Error('demo_session_in_response');
42
+ process.stdout.write(output);
43
+ if(receipt.complete !== true)return 1;
44
+ return 0;
45
+ } catch(error) {
46
+ if(String(error?.message).includes(session))throw Error('demo_session_in_response');
47
+ throw error;
48
+ }
49
+ }
@@ -0,0 +1,15 @@
1
+ {
2
+ "synthetic": true,
3
+ "name": "Juniper Harbor Software — Synthetic demo",
4
+ "profile": {
5
+ "display_name": "Juniper Harbor Software — Synthetic demo",
6
+ "legal_name": "Juniper Harbor Software Inc. (synthetic)",
7
+ "country": "US",
8
+ "state": "Delaware",
9
+ "state_of_organization": "Delaware",
10
+ "entity_type": "Corporation",
11
+ "currency": "USD",
12
+ "timezone": "America/New_York",
13
+ "brand_color": "#245943"
14
+ }
15
+ }
@@ -0,0 +1,95 @@
1
+ // Mirrored from runeditrun/platform 0261033177e8e05284c037369ee9c3a85922a8aa, scripts/business/demo.mjs.
2
+ import { readFile } from 'node:fs/promises';
3
+ const company = JSON.parse(await readFile(new URL('./setup-company.json', import.meta.url), 'utf8'));
4
+ export const demoPolicy={schema:'rer-agent-policy/1',catalogue:'rer-agent-classes/1',rules:[
5
+ {id:'internal',class:'standard',do:'autonomous'},
6
+ {id:'context',class:'sensitive',do:'autonomous'},
7
+ {id:'owner',class:'*',do:'approval',approver:['role:owner'],wait:'P1D'},
8
+ ],spend:{none:true}};
9
+
10
+ /** The only injectable boundary is HTTP. Tokens, cookies, policy envelopes and peer bodies never enter the receipt. */
11
+ export async function setupDemo({origin,cookie,hosting='managed',waitSeconds=240,fetch:request=globalThis.fetch,now=Date.now,wait=ms=>new Promise(resolve=>setTimeout(resolve,ms))}) {
12
+ const api=async(path,method='GET',body,token)=>{
13
+ let response;
14
+ try{response=await request(new URL(path,origin),{method,redirect:'manual',signal:AbortSignal.timeout(60000),headers:{Origin:origin,Cookie:cookie,'Content-Type':'application/json',...(token?{'X-RER-Demo-Seed-Token':token}:{})},...(body===undefined?{}:{body:JSON.stringify(body)})});}
15
+ catch{throw Error('platform_transport_unavailable');}
16
+ let answer;try{answer=await response.json();}catch{throw Error(`platform_http_${response.status}`);}
17
+ if(!response.ok){const code=answer?.code;throw Error(typeof code==='string'&&/^[a-z0-9_]{1,100}$/.test(code)?code:`platform_http_${response.status}`);}
18
+ return answer;
19
+ };
20
+ const businesses=(await api('/api/business')).businesses;
21
+ let business=businesses.find(row=>row.name===company.name);
22
+ if(!business){
23
+ business=(await api('/api/business','POST',{name:company.name,default_hosting:hosting,executor_preference:hosting==='self_host'?'local':'managed'})).business;
24
+ await api('/api/business/'+encodeURIComponent(business.id)+'/profile','PUT',company.profile);
25
+ }
26
+ if(business.default_hosting!==hosting)throw Error('existing_demo_hosting_differs');
27
+ const root='/api/business/'+encodeURIComponent(business.id),initial=await api(root+'/demo');
28
+ // Return exactly the same projection after the first successful run and on every repeat.
29
+ if(initial.complete)return initial;
30
+ const pending=initial.seeds.filter(seed=>seed.adopted&&!seed.complete);
31
+ if(!pending.length)return initial;
32
+ let policy=await api(root+'/agents/policy');
33
+ if(policy.paused)throw Error('demo_is_paused_resume_as_owner');
34
+ const errors=new Map(),credentials=new Map(),ready=pending.filter(seed=>seed.provisioned);
35
+ let waiting=pending.filter(seed=>!seed.provisioned);
36
+ if(waiting.length){
37
+ const plan=await api(root+'/demo/plan','POST',{confirmed:true});
38
+ if(plan.plan_id&&!plan.approved)await api(root+'/plans/'+encodeURIComponent(plan.plan_id)+'/approve','POST',{});
39
+ const deadline=now()+waitSeconds*1000;
40
+ do{
41
+ await api(root+'/demo/advance','POST',{});
42
+ const status=await api(root+'/demo'),apps=(await api(root+'/apps')).apps,next=[];
43
+ for(const seed of waiting){
44
+ const current=status.seeds.find(row=>row.app===seed.app),installed=apps.find(row=>row.app===seed.app);
45
+ if(current?.provisioned)ready.push(current);
46
+ else if(installed?.failure||installed?.stage==='failed')errors.set(seed.app,'M4 provisioning failed');
47
+ else if(installed?.waits?.length||installed?.answers_needed?.length)errors.set(seed.app,'M4 setup needs hosting, payment, domain or app answers');
48
+ else next.push(seed);
49
+ }
50
+ waiting=next;
51
+ if(waiting.length&&now()<deadline)await wait(Math.min(3000,Math.max(0,deadline-now())));
52
+ }while(waiting.length&&now()<deadline);
53
+ for(const seed of waiting)errors.set(seed.app,'Run the same command to resume provisioning');
54
+ }
55
+ const eligible=[];
56
+ for(const seed of ready){
57
+ try{
58
+ // This is the shared Business sender, not a demo-specific settings signer or transport.
59
+ const settings=await api(root+'/settings/deliver','POST',{});
60
+ const delivery=settings.deliveries.find(row=>row.installation_id===seed.installation_id);
61
+ if(!delivery||delivery.state!=='delivered')throw Error(delivery?.code??'settings_not_delivered');
62
+ if(policy.revision&&!seed.no_policy_refused)throw Error('no_policy_probe_requires_fresh_demo');
63
+ const issued=await api(root+'/agents/seed-token','POST',{seed:seed.app,installation_id:seed.installation_id,
64
+ agent:{id:'demo:'+business.id,name:'Synthetic demo setup'},scopes:seed.scopes});
65
+ credentials.set(seed.app,issued.access_token);
66
+ if(!policy.revision&&!seed.no_policy_refused)await api(root+'/demo/apps/'+encodeURIComponent(seed.app)+'/door','POST',{phase:'unset'},issued.access_token);
67
+ eligible.push(seed);
68
+ }catch(error){errors.set(seed.app,error.message);}
69
+ }
70
+ if(eligible.length&&!policy.revision){
71
+ let draft=policy.draft;
72
+ if(draft&&JSON.stringify(draft.document)!==JSON.stringify(demoPolicy))throw Error('existing_policy_draft_requires_owner_review');
73
+ if(!draft)draft=(await api(root+'/agents/policy/revisions','POST',{document:demoPolicy})).revision;
74
+ await api(root+'/agents/policy/revisions/'+draft.revision+'/confirm','POST',{digest:draft.document_sha256});
75
+ policy=await api(root+'/agents/policy');
76
+ }
77
+ const seeded=[];
78
+ for(const seed of eligible){
79
+ try{await api(root+'/demo/apps/'+encodeURIComponent(seed.app)+'/door','POST',{phase:'seed'},credentials.get(seed.app));seeded.push(seed);}
80
+ catch(error){errors.set(seed.app,error.message);}
81
+ }
82
+ if(seeded.length){
83
+ await api(root+'/pause','POST',{paused:true});
84
+ let allPaused=true;
85
+ for(const seed of seeded){
86
+ try{await api(root+'/demo/apps/'+encodeURIComponent(seed.app)+'/door','POST',{phase:'paused'},credentials.get(seed.app));}
87
+ catch(error){allPaused=false;errors.set(seed.app,error.message);}
88
+ }
89
+ if(allPaused)await api(root+'/pause','POST',{paused:false});
90
+ }
91
+ credentials.clear();
92
+ const receipt=await api(root+'/demo');
93
+ for(const seed of receipt.seeds)if(!seed.complete&&errors.has(seed.app))seed.cause=errors.get(seed.app);
94
+ return receipt;
95
+ }
@@ -1,4 +1,5 @@
1
- import { mkdir, readFile, readdir, writeFile, rename, chmod, open, unlink, rm, rmdir, lstat } from 'node:fs/promises';
1
+ import { mkdir, readFile, readdir, writeFile, rename, chmod, open, unlink, rm, rmdir, lstat, utimes } from 'node:fs/promises';
2
+ import { readFileSync, unlinkSync } from 'node:fs';
2
3
  import { dirname, join, resolve } from 'node:path';
3
4
  import { homedir } from 'node:os';
4
5
  import { createHash, randomUUID } from 'node:crypto';
@@ -81,7 +82,15 @@ export async function checkStateWritable() {
81
82
 
82
83
  // Files this CLI writes in its state folder. A folder named by RER_BUSINESS_STATE_DIR
83
84
  // may hold other things, so only these are removed from it.
84
- const owned = /^(?:(?:state|pairing|progress|permissions|service|carried)\.json|run\.lock|disconnect|service(?:-error)?\.log|discovery-[A-Za-z0-9_.:-]+\.(?:json|tmp)|.*[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp(?:\.check)?)$/;
85
+ const owned = /^(?:(?:state|pairing|progress|permissions|service|carried)\.json|run\.lock|disconnect|service(?:-error)?\.log|discovery-[A-Za-z0-9_.:-]+\.(?:json|tmp)|export-[0-9a-f]{32}\.bundle|.*[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp(?:\.check)?)$/;
86
+ /** After a revocation whose local cleanup was refused, keep only what a later
87
+ * disconnect needs to finish: the state and the receipts of what remains. */
88
+ export async function removeWorkFiles(keep = ['state.json', 'permissions.json', 'service.json']) {
89
+ let entries;
90
+ try { entries = await readdir(stateDirectory()); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
91
+ for (const name of entries) if (owned.test(name) && !keep.includes(name)) await rm(join(stateDirectory(), name), { force: true });
92
+ }
93
+
85
94
  export async function removeStateDirectory() {
86
95
  const directory = stateDirectory();
87
96
  if (!chosenStateDirectory()) {
@@ -96,22 +105,47 @@ export async function removeStateDirectory() {
96
105
  await rmdir(directory).catch(error => { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; });
97
106
  }
98
107
 
108
+ // run.lock holds the supervisor's process id, and its time is refreshed while
109
+ // it runs. A lock whose process is gone, or that has not been refreshed for
110
+ // two minutes (a process id a sandbox cannot check), is stale and replaced.
111
+ const lockFresh = 120_000;
112
+ export const lockPath = () => join(stateDirectory(), 'run.lock');
113
+ export async function liveSupervisor(path = lockPath()) {
114
+ let text, info;
115
+ try { [text, info] = await Promise.all([readFile(path, 'utf8'), lstat(path)]); }
116
+ catch (error) { if (error.code === 'ENOENT') return null; throw error; }
117
+ // A lock is written right after it is created; give an empty one a moment.
118
+ if (!text) return Date.now() - info.mtimeMs < 5_000 ? 'starting' : null;
119
+ const pid = Number(text);
120
+ if (!Number.isSafeInteger(pid) || pid <= 0) return null;
121
+ try { process.kill(pid, 0); }
122
+ catch (error) { if (error.code === 'ESRCH') return null; if (error.code !== 'EPERM') throw error; }
123
+ return Date.now() - info.mtimeMs > lockFresh ? null : pid;
124
+ }
125
+
126
+ /** Take run.lock, replacing a stale one. The returned release removes it; it is
127
+ * also removed on every exit of this process, including after a signal. */
99
128
  export async function lockSupervisor() {
100
- const directory = stateDirectory();
129
+ const directory = stateDirectory(), path = lockPath();
101
130
  await mkdir(directory, { recursive: true, mode: 0o700 });
102
- const path = join(directory, 'run.lock');
103
131
  for (let attempt = 0; attempt < 2; attempt++) {
104
132
  try {
105
133
  const file = await open(path, 'wx', 0o600);
106
134
  await file.writeFile(String(process.pid)); await file.close();
107
- return async () => { await unlink(path).catch(error => { if (error.code !== 'ENOENT') throw error; }); };
135
+ const refresh = setInterval(() => { const now = new Date(); utimes(path, now, now).catch(() => {}); }, 30_000);
136
+ refresh.unref();
137
+ const exit = () => { try { if (readFileSync(path, 'utf8') === String(process.pid)) unlinkSync(path); } catch { /* Already gone. */ } };
138
+ process.once('exit', exit);
139
+ const release = async () => { clearInterval(refresh); process.off('exit', exit); exit(); };
140
+ // A signal is often followed closely by SIGKILL (an agent closing its
141
+ // terminal), so a signal handler removes the lock synchronously at once.
142
+ release.now = exit;
143
+ return release;
108
144
  } catch (error) {
109
145
  if (error.code !== 'EEXIST') throw error;
110
- const pid = Number(await readFile(path, 'utf8'));
111
- if (!Number.isSafeInteger(pid) || pid <= 0) throw Error('Business supervisor lock is invalid.');
112
- try { process.kill(pid, 0); throw Error('A Business supervisor is already running.'); }
113
- catch (check) { if (check.code !== 'ESRCH') throw check; }
114
- await unlink(path);
146
+ const pid = await liveSupervisor(path);
147
+ if (pid) throw Error(`A Business supervisor is already running for this computer${pid === 'starting' ? '' : ` (process ${pid})`}. Let it keep working, or stop it before starting another.`);
148
+ await unlink(path).catch(error => { if (error.code !== 'ENOENT') throw error; });
115
149
  }
116
150
  }
117
151
  throw Error('Could not acquire Business supervisor lock.');
@@ -3,36 +3,73 @@ import { randomUUID } from 'node:crypto';
3
3
  import { access, unlink } from 'node:fs/promises';
4
4
  import { join } from 'node:path';
5
5
  import { Api, taskPath, pause } from './api.mjs';
6
- import { paired } from './local-commands.mjs';
7
- import { createCredentialStore } from './keychain.mjs';
8
- import { nextQuestions } from './questions.mjs';
9
- import { lockSupervisor, stateDirectory, credentialHandle } from './state.mjs';
6
+ import { paired, revokedByServer, revokedText } from './local-commands.mjs';
7
+ import { nextQuestions, ownerLink, waitingFor, agentWaiting, ownerWaiting } from './questions.mjs';
8
+ import { lockSupervisor, stateDirectory, saveState, loadState } from './state.mjs';
10
9
  import { loadProgress, saveProgress } from './progress.mjs';
11
10
  import { Lease } from './lease.mjs';
12
11
  import { runDiscovery } from './discovery-task.mjs';
13
- import { applyOptIns } from './opt-ins.mjs';
12
+ import { applyChoices } from './choices.mjs';
13
+ import { businessCommand } from './invocation.mjs';
14
+ import { ExportWaiting, vendorHandle } from './vendor-door.mjs';
15
+ import { runExport } from './export-task.mjs';
16
+ import { runCatchup } from './catchup-task.mjs';
17
+ import { runArchive } from './archive-task.mjs';
14
18
 
15
- const kinds = new Set(['discover.local', 'export.vendor']);
16
- const unavailableReasons = new Set(['ambiguous-target-installation', 'no-linked-installation', 'installation-import-origin-unavailable', 'installation-owner-claim-unconfigured', 'connected-seed-import-required']);
19
+ // The vendor tasks this computer performs into an app's import door.
20
+ const vendorWork = { 'export.vendor': runExport, 'catchup.vendor': runCatchup, 'switchoff.archive': runArchive };
21
+ const kinds = new Set(['discover.local', ...Object.keys(vendorWork)]);
22
+ export function supportsTaskKind(kind) { return kinds.has(kind); }
23
+ const checkIn = 25_000;
17
24
 
25
+ /** Work this computer's tasks. It says what it is doing and what it waits
26
+ * for, applies the owner's choices at every check-in, and removes run.lock on
27
+ * every exit, including Ctrl-C, SIGTERM and a closed terminal (SIGHUP). */
18
28
  export async function run({ once = false } = {}) {
19
29
  const { state, credential } = await paired(), api = new Api(state.origin, credential), directory = stateDirectory();
20
- const parked = new Set(), unlock = await lockSupervisor(), stop = new AbortController();
21
- const interrupted = () => stop.abort(Error('Business supervisor stopped.'));
22
- process.once('SIGTERM', interrupted); process.once('SIGINT', interrupted);
23
- const monitor = setInterval(() => { access(join(directory, 'disconnect')).then(interrupted, () => {}); }, 250);
24
- let progress, stopCarry;
25
-
30
+ // Tasks this run handed back as paused, with what each waits for. An export
31
+ // waiting only for the owner's vendor key is picked up again once it is stored.
32
+ const parked = new Map(), unlock = await lockSupervisor(), stop = new AbortController();
33
+ // A terminal's Ctrl-C reaches npx and this process together, and npx then
34
+ // forwards another SIGINT, which can arrive at any moment until this process
35
+ // has exited. So the handlers stay for the rest of the process: a repeated
36
+ // signal finds them instead of Node's default action, which would end the
37
+ // process before it hands its lease back, removes run.lock or says it stopped.
38
+ // Each one removes run.lock (again, harmlessly); the first one stops the run.
39
+ const interrupted = signal => () => { unlock.now(); stop.abort(Object.assign(Error('Business supervisor stopped.'), { signal })); };
40
+ for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, interrupted(signal));
41
+ const monitor = setInterval(() => { access(join(directory, 'disconnect')).then(() => stop.abort(Error('Business supervisor stopped for disconnect.')), () => {}); }, 250);
42
+ let progress, stopCarry, said = '', held = null, summaries = [];
43
+ const say = text => { if (text !== said) { said = text; process.stdout.write(text + '\n'); } };
44
+ // An agent step that waits is said in its own words, never as "Nothing yet".
45
+ const waits = () => [...new Set([...summaries.filter(task => parked.has(task.task_id)).map(task => parked.get(task.task_id).message), ...agentWaiting(summaries)])];
46
+ // With no agent step waiting, a move's owner step (freeze, rollback, cancellation) is named with its link.
47
+ const idle = () => { const owner = ownerWaiting(summaries, state); return owner.length ? owner.join('\n') : waitingFor(state); };
26
48
  try {
27
- await applyOptIns(api, state, { report: false });
28
49
  stopCarry = await startCarryRefresh(api, state, stop.signal);
29
50
  progress = await loadProgress();
51
+ // A claim saved before this computer stopped is the task it was doing.
52
+ held = progress.pendingClaim?.task_id ?? null;
30
53
  await unlink(join(directory, 'disconnect')).catch(error => { if (error.code !== 'ENOENT') throw error; });
54
+ if (!once) process.stdout.write(`Business run is working this computer's tasks for ${ownerLink(state)}. It checks in every ${checkIn / 1000} seconds and keeps going until you stop it (Ctrl-C).\n`);
31
55
  do {
56
+ const { serviceInstalled } = await applyChoices(api, state);
57
+ if (serviceInstalled && !once) {
58
+ process.stdout.write('The background service now works this computer\'s tasks, so this run stops here.\n');
59
+ return;
60
+ }
32
61
  if (!progress.pendingClaim) {
33
- const summaries = await nextQuestions(api, stop.signal);
62
+ summaries = await nextQuestions(api, stop.signal);
63
+ const handles = (await loadState())?.vendorHandles ?? [];
64
+ for (const [id, wait] of parked) if (wait.keyMissing && handles.includes(vendorHandle(wait.keyMissing))) parked.delete(id);
34
65
  const selected = summaries.find(task => kinds.has(task.kind) && ['ready','leased'].includes(task.state) && !parked.has(task.task_id));
35
- if (!selected) { if (once) { process.stdout.write('Nothing yet.\n'); return; } await pause(25_000, stop.signal); continue; }
66
+ if (!selected) {
67
+ const waiting = waits();
68
+ say(waiting.length ? waiting.join('\n') : idle());
69
+ if (once) { if (!waiting.length) process.stdout.write('Nothing yet.\n'); return; }
70
+ await pause(checkIn, stop.signal); continue;
71
+ }
72
+ held = selected.state === 'leased' ? selected.task_id : null;
36
73
  progress.pendingClaim = { claim_id: randomUUID(), task_id: selected.task_id };
37
74
  await saveProgress(progress);
38
75
  }
@@ -42,11 +79,21 @@ export async function run({ once = false } = {}) {
42
79
  if (error.status !== 409) throw error;
43
80
  progress = {}; await saveProgress(progress);
44
81
  if (once) throw error;
45
- await pause(25_000, stop.signal); continue;
82
+ await pause(checkIn, stop.signal); continue;
46
83
  }
47
84
  if (!claimed.task || claimed.task.state !== 'leased' || claimed.task.fence !== claimed.fence || Date.parse(claimed.lease_expires_at) <= Date.now()) {
85
+ const interrupted = held === progress.pendingClaim?.task_id;
48
86
  progress = {}; await saveProgress(progress);
49
- if (once && !claimed.task) { process.stdout.write('Nothing yet.\n'); return; }
87
+ // A task this computer held before it was stopped stays leased until the
88
+ // lease ends; then the server returns it to ready with its checkpoint.
89
+ if (!claimed.task && interrupted) say('Waiting for the server to hand back the task this computer was doing when it stopped; its earlier lease has not ended yet.');
90
+ if (once && !claimed.task) {
91
+ // Only with no agent step waiting does run say "Nothing yet".
92
+ const waiting = interrupted ? [] : waits();
93
+ if (!interrupted) say(waiting.length ? waiting.join('\n') : idle());
94
+ if (!interrupted && !waiting.length) process.stdout.write('Nothing yet.\n');
95
+ return;
96
+ }
50
97
  continue;
51
98
  }
52
99
  if (!kinds.has(claimed.task.kind) || claimed.task.kind_version !== 1) throw Error('Business server returned an unimplemented task kind.');
@@ -55,22 +102,32 @@ export async function run({ once = false } = {}) {
55
102
  try {
56
103
  progress.current = { kind: claimed.task.kind, checkpoint: claimed.task.checkpoint, uploadedBytes: claimed.task.checkpoint?.bytes_done ?? 0 };
57
104
  await saveProgress(progress);
58
- if (claimed.task.kind === 'export.vendor') {
59
- // A destination is not upload authority. Keep vendor keys local until
60
- // the seed's signed import grant and chunk transport are connected.
61
- await lease.send(taskPath(claimed.task.id, 'events'), { event: { kind: 'question', payload: { question: 'connected_runner_required' } } });
62
- parked.add(claimed.task.id);
63
- if (claimed.grant.available === false && claimed.grant.destination === `unavailable:${claimed.grant.reason}`) {
64
- const reason = unavailableReasons.has(claimed.grant.reason) ? claimed.grant.reason : 'connected-seed-import-required';
65
- throw Error(`Business vendor export unavailable: ${reason}. Task released as paused.`);
105
+ if (Object.hasOwn(vendorWork, claimed.task.kind)) {
106
+ try {
107
+ const done = await vendorWork[claimed.task.kind]({ lease, task: claimed.task, grant: claimed.grant, directory, say, ownerPage: ownerLink(state) });
108
+ finished = true;
109
+ say(done);
110
+ } catch (error) {
111
+ if (!(error instanceof ExportWaiting) || lease.signal.aborted) throw error;
112
+ // Business shows the owner what this vendor task waits for; the lease goes back as paused.
113
+ parked.set(claimed.task.id, { message: error.message, keyMissing: error.keyMissing });
114
+ await lease.send(taskPath(claimed.task.id, 'events'), { event: { kind: 'question', payload: { question: error.question } } });
115
+ throw error;
66
116
  }
67
- throw Error('Business vendor export needs a connected seed upload grant and execution-input contract.');
117
+ } else {
118
+ const page = claimed.task.checkpoint?.page;
119
+ say(page ? `Resuming the names-only scan of this computer's allowed folders from page ${page + 1}.` : 'Scanning this computer\'s allowed folders for tool names (names only; no file contents leave this computer).');
120
+ const result = await runDiscovery({ task: claimed.task, grant: claimed.grant, checkpoint: claimed.task.checkpoint, signal: lease.signal,
121
+ send: (destination, body) => lease.send(destination, body), stateDir: directory,
122
+ saveCheckpoint: async checkpoint => {
123
+ await lease.checkpointSaved(checkpoint);
124
+ if (checkpoint.page) process.stdout.write(`Sent page ${checkpoint.page} of ${checkpoint.total}; the server has ${checkpoint.records_done} names and saved this checkpoint.\n`);
125
+ } });
126
+ await lease.complete(); finished = true;
127
+ await result.cleanup();
128
+ if (!state.discovered) { state.discovered = true; await saveState(state); }
129
+ say('Business discover.local completed and checked by the server.');
68
130
  }
69
- const result = await runDiscovery({ task: claimed.task, grant: claimed.grant, checkpoint: claimed.task.checkpoint, signal: lease.signal,
70
- send: (destination, body) => lease.send(destination, body), saveCheckpoint: checkpoint => lease.checkpointSaved(checkpoint), stateDir: directory });
71
- await lease.complete(); finished = true;
72
- await result.cleanup();
73
- process.stdout.write('Business discover.local completed and checked by the server.\n');
74
131
  } catch (error) { failure = lease.signal.aborted ? lease.signal.reason : error; }
75
132
  finally {
76
133
  if (!finished && failure?.status !== 401) {
@@ -88,11 +145,13 @@ export async function run({ once = false } = {}) {
88
145
  } while (!stop.signal.aborted);
89
146
  } catch (error) {
90
147
  if (error.status === 401) {
91
- await createCredentialStore().delete(credentialHandle(state.origin));
92
- process.stderr.write('Business pairing expired or was revoked. Supervisor stopped.\n');
148
+ const revoked = await revokedByServer(state);
149
+ process.stderr.write(`Business pairing expired or was revoked, so this supervisor stopped. This computer was ${revokedText(revoked)}\n`);
93
150
  } else if (!stop.signal.aborted) throw error;
94
151
  } finally {
95
152
  await stopCarry?.();
96
- clearInterval(monitor); process.off('SIGTERM', interrupted); process.off('SIGINT', interrupted); await unlock();
153
+ clearInterval(monitor);
154
+ await unlock();
155
+ if (stop.signal.reason?.signal) process.stdout.write(`Business supervisor stopped (${stop.signal.reason.signal}); run.lock removed. Run ${businessCommand('run')} again to continue from the saved checkpoint.\n`);
97
156
  }
98
157
  }